Cómo instalar Activepieces con Docker en tu servidor

Activepieces es una plataforma de automatización que permite conectar aplicaciones, recibir webhooks y ejecutar flujos de trabajo desde una interfaz visual. Además de utilizar su servicio en la nube, puedes instalar Activepieces en tu propio servidor y controlar directamente la aplicación, la base de datos y las actualizaciones.

La forma recomendada de autoalojarlo es mediante Docker Compose. Este método despliega por separado la interfaz y API, los workers encargados de ejecutar los flujos, PostgreSQL y Redis. También existe una instalación simplificada en un único contenedor, aunque está limitada a proyectos personales y pruebas.

Autoalojar la plataforma mejora el control sobre la infraestructura, pero no significa que todos los datos permanezcan automáticamente en el servidor. Cuando un flujo utiliza Gmail, Slack, OpenAI u otra API externa, la información necesaria seguirá enviándose a ese proveedor. Por eso también debes conectar agentes y automatizaciones sin exponer credenciales.

Qué instalación de Activepieces debes elegir

Activepieces ofrece dos rutas principales mediante Docker. La elección depende del uso previsto, la cantidad de ejecuciones y la posibilidad de ampliar posteriormente la infraestructura.

Instalación	Componentes	Uso recomendado
Contenedor único	Aplicación, PGLite y cola en memoria	Pruebas y proyectos personales
Docker Compose	Aplicación, worker, PostgreSQL y Redis	Servidor estable y equipos
Arquitectura de producción	Apps, workers, PostgreSQL, Redis y almacenamiento S3	Alta concurrencia y despliegues escalables

El contenedor único utiliza PGLite como base de datos integrada y mantiene la cola de trabajos en memoria. Solamente admite una instancia en una máquina y no puede convertirse directamente en una instalación Enterprise. Si posteriormente necesitas migrar a la arquitectura completa, tendrás que preparar un despliegue nuevo.

Docker Compose resulta más apropiado cuando quieres conservar los flujos en PostgreSQL, utilizar Redis para las colas y separar la ejecución de las automatizaciones mediante workers.

Requisitos para instalar Activepieces con Docker

La instalación oficial mediante Docker Compose necesita los siguientes recursos:

• Docker y Docker Compose v2.
• Al menos 2 vCPU y 4 GB de memoria RAM.
• Un sistema Linux o un servidor compatible con Docker.
• WSL2 si vas a ejecutar el instalador desde Windows.
• Acceso a una terminal con permisos para administrar Docker.
• Un dominio si necesitas recibir webhooks desde Internet.
• HTTPS para una instalación pública o de producción.

Comprueba que Docker Compose v2 está disponible:

docker compose version

El comando correcto contiene un espacio entre docker y compose. La antigua herramienta docker-compose corresponde a Compose v1 y no funciona con el despliegue actual.

Si utilizas Windows, abre una distribución de Linux mediante WSL2 y ejecuta allí los comandos de instalación. Docker Desktop debe estar configurado para integrarse con esa distribución.

Instalación rápida para proyectos personales

Si solamente quieres probar Activepieces en una máquina y no necesitas escalar, puedes iniciar la versión simplificada con un único contenedor:

docker run -d --name activepieces -p 8080:80 \
  -v ~/.activepieces:/root/.activepieces \
  -e AP_DB_TYPE=PGLITE \
  -e AP_REDIS_TYPE=MEMORY \
  -e AP_FRONTEND_URL="http://localhost:8080" \
  activepieces/activepieces:latest

Este comando:

• Publica Activepieces mediante el puerto 8080.
• Guarda la configuración y la base de datos en ~/.activepieces.
• Utiliza PGLite como base de datos integrada.
• Gestiona la cola de ejecuciones dentro de la memoria del proceso.

Cuando el contenedor haya arrancado, abre:

http://localhost:8080

El primer usuario que registres se convertirá en el administrador. No existen un nombre de usuario ni una contraseña predeterminados.

Esta modalidad no es adecuada para producción, múltiples réplicas ni instalaciones que puedan necesitar funciones empresariales. Si existe la posibilidad de ampliar el proyecto, comienza directamente con Docker Compose.

Cómo instalar Activepieces con un solo comando

La documentación oficial recomienda un script que crea la configuración, genera los secretos y levanta los contenedores. Entra primero en la carpeta donde quieres guardar los archivos del despliegue y ejecuta:

curl -fsSL https://get.activepieces.com | sh

Si prefieres revisar el contenido antes de ejecutarlo, puedes mostrarlo en la terminal:

curl -fsSL https://get.activepieces.com

El instalador crea una carpeta llamada activepieces, prepara el archivo .env y despliega los servicios necesarios.

Si el puerto 8080 ya está ocupado, indica otro:

curl -fsSL https://get.activepieces.com | sh -s -- --port 8090

También puedes elegir otro directorio:

curl -fsSL https://get.activepieces.com | sh -s -- --dir /ruta/activepieces

Cuando termine, abre http://localhost:8080 o sustituye localhost por la dirección IP del servidor.

Cómo instalar Activepieces manualmente con Docker Compose

La instalación manual permite revisar el archivo de Compose y las variables antes de iniciar ningún contenedor. Comienza clonando el repositorio:

git clone --depth 1 https://github.com/activepieces/activepieces.git
cd activepieces

Después ejecuta el script que prepara el archivo .env y genera las contraseñas:

sh tools/deploy.sh

Este proceso necesita openssl. Si no está instalado, el script puede terminar sin mostrar un fallo evidente y dejar vacíos algunos secretos. Compruébalos antes de continuar:

grep -E '^(AP_ENCRYPTION_KEY|AP_JWT_SECRET|AP_POSTGRES_PASSWORD)=' .env

Las tres variables deben contener un valor:

• AP_ENCRYPTION_KEY cifra las conexiones guardadas.
• AP_JWT_SECRET firma los tokens de autenticación.
• AP_POSTGRES_PASSWORD protege el acceso a PostgreSQL.

La instalación utiliza la edición Community de forma predeterminada. Si dispones de una licencia comercial y quieres activarla posteriormente, debes preparar la edición correspondiente antes de iniciar el despliegue y utilizar un modo de ejecución compatible.

En una instalación manual, el servicio worker debe poder comunicarse con la aplicación mediante el nombre interno del contenedor. Revisa que su sección contenga:

worker:
  environment:
    - AP_CONTAINER_TYPE=WORKER
    - AP_FRONTEND_URL=http://app

Esta dirección solamente se aplica al worker. La variable AP_FRONTEND_URL general del archivo .env debe conservar la URL pública que utilizarán los navegadores y servicios externos.

Finalmente, inicia los contenedores:

docker compose -p activepieces up -d

Qué contenedores instala Activepieces

El despliegue mediante Docker Compose crea cuatro tipos de servicio:

Contenedor	Función
app	Proporciona la interfaz, la API y la administración de la plataforma.
worker	Recoge trabajos de la cola y ejecuta los flujos.
postgres	Almacena flujos, conexiones, usuarios y ejecuciones.
redis	Gestiona la cola de trabajos y las ejecuciones pendientes.

Los datos de PostgreSQL no se guardan directamente en la carpeta clonada. Permanecen dentro del volumen de Docker postgres_data. Por tanto, copiar únicamente la carpeta de Activepieces no crea una copia de seguridad completa.

Cómo comprobar que Activepieces funciona

Consulta el estado de los contenedores:

docker compose -p activepieces ps

Todos los servicios deberían aparecer iniciados. Después comprueba el endpoint de salud:

curl http://localhost:8080/api/v1/health

Inicia sesión y abre Platform Admin > Infrastructure > Workers. Debe aparecer al menos un worker disponible. Si la lista está vacía, el worker probablemente no consigue comunicarse con la aplicación.

También puedes consultar los registros en tiempo real:

docker compose -p activepieces logs -f app
docker compose -p activepieces logs -f worker

Cómo configurar el dominio y los webhooks

Activepieces utiliza AP_FRONTEND_URL para generar direcciones de webhooks, redirecciones OAuth y enlaces públicos. Si contiene localhost, servicios como Stripe, GitHub o Slack no podrán enviar datos desde Internet.

Edita el archivo .env e introduce el dominio público:

AP_FRONTEND_URL=https://automatizaciones.tudominio.com

Después recrea los servicios para aplicar el cambio:

docker compose -p activepieces up -d

Para realizar pruebas desde un ordenador sin dirección pública puedes utilizar un túnel temporal:

ngrok http 8080

Introduce la dirección HTTPS proporcionada por el túnel en AP_FRONTEND_URL y reinicia los contenedores. Ngrok resulta útil para pruebas, pero su dirección puede cambiar y no debe considerarse una configuración permanente de producción.

Cloudflare Tunnel también puede utilizarse para publicar la instancia sin abrir directamente el puerto 8080. Sin embargo, tendrás que configurar correctamente el dominio, HTTPS y la compatibilidad con WebSockets.

Cómo proteger Activepieces con HTTPS

Una instancia pública debe utilizar HTTPS. Puedes terminar el cifrado mediante un proxy inverso como Nginx, un balanceador de carga o el servicio de proxy incluido por tu proveedor.

Una configuración básica de Nginx debe reenviar las peticiones al puerto 8080 y permitir las conexiones WebSocket:

location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

El certificado puede obtenerse mediante Let’s Encrypt, Certbot, Cloudflare o el proveedor de infraestructura. Una vez activado HTTPS, comprueba que AP_FRONTEND_URL comienza por https://.

No publiques PostgreSQL ni Redis directamente en Internet. Limita también el acceso SSH, mantén Docker actualizado y utiliza contraseñas diferentes para el servidor y las aplicaciones conectadas.

Cómo hacer una copia de seguridad

Antes de actualizar Activepieces, exporta la base de datos:

docker compose -p activepieces exec postgres \
  pg_dump -U postgres activepieces > backup.sql

Guarda también una copia segura del archivo .env. Sin la misma AP_ENCRYPTION_KEY, Activepieces no podrá descifrar las conexiones almacenadas, aunque restaures correctamente PostgreSQL.

En la instalación personal con PGLite, debes respaldar la carpeta:

~/.activepieces

No guardes las copias únicamente en el mismo servidor. Utiliza otro equipo, un almacenamiento cifrado o un sistema de copias con versiones.

Cómo actualizar Activepieces

Consulta primero los cambios incompatibles publicados para la versión nueva. Después de crear la copia de seguridad, ejecuta:

curl -fsSL https://get.activepieces.com | sh -s -- --upgrade

El instalador conserva el archivo .env, los datos y las modificaciones realizadas en docker-compose.yml. La versión utilizada queda fijada mediante AP_VERSION, lo que evita actualizar accidentalmente cada vez que se reinician los contenedores.

En el contenedor personal, debes detenerlo, respaldar ~/.activepieces, eliminar el contenedor antiguo, descargar la imagen nueva y volver a crearlo utilizando el mismo volumen.

Errores frecuentes al instalar Activepieces

El comando docker compose no existe

Comprueba la versión:

docker compose version

Si el comando falla, instala Docker Compose v2. No sustituyas automáticamente el comando por docker-compose, ya que el despliegue actual no admite Compose v1.

El puerto 8080 ya está ocupado

Realiza la instalación en otro puerto:

curl -fsSL https://get.activepieces.com | sh -s -- --port 8090

En una instalación existente, cambia AP_HOST_PORT dentro de .env y recrea los contenedores. No cambies AP_PORT, porque corresponde al puerto interno y puede romper el mapeo.

La página de Workers aparece vacía

Consulta los registros:

docker compose -p activepieces logs worker | grep -i socket

Los errores repetidos de Socket.IO suelen indicar que el worker está intentando conectarse a localhost o al dominio público desde dentro de Docker. Configura para ese servicio:

AP_FRONTEND_URL=http://app

Los webhooks muestran localhost

Introduce el dominio público en la variable AP_FRONTEND_URL del archivo .env y reinicia los servicios. La dirección debe ser accesible desde la aplicación externa que enviará el webhook.

Los botones de prueba o las actualizaciones en tiempo real no funcionan

El proxy inverso probablemente no está reenviando correctamente las conexiones WebSocket. Revisa las cabeceras Upgrade y Connection y activa HTTPS, ya que algunos navegadores bloquean WebSockets sin cifrar.

Las claves del archivo .env están vacías

Instala openssl y ejecuta de nuevo:

sh tools/deploy.sh

No inicies la instalación hasta confirmar que AP_ENCRYPTION_KEY, AP_JWT_SECRET y AP_POSTGRES_PASSWORD contienen valores.

La aplicación se reinicia continuamente

Revisa el error de arranque:

docker compose -p activepieces logs app | grep -i "failed to start"

Una causa posible es utilizar AP_EDITION=ee junto con AP_EXECUTION_MODE=UNSANDBOXED. La edición empresarial rechaza esta combinación; utiliza un modo de sandbox compatible como SANDBOX_CODE_ONLY.

Los flujos desaparecen después de recrear los contenedores

Comprueba que el volumen postgres_data siga existiendo y que no hayas ejecutado una eliminación con purga. Borrar contenedores no debería eliminar el volumen, pero comandos que eliminan volúmenes pueden destruir definitivamente la base de datos.

Cuando una automatización deja de ejecutarse, revisa primero los registros de la aplicación y del worker. Esta misma metodología resulta útil para determinar qué hacer cuando una automatización falla y separar un problema del flujo de un fallo de infraestructura.

Cuándo necesitas una arquitectura de producción

Docker Compose es suficiente para comenzar con un servidor propio, pero una organización con muchas ejecuciones simultáneas necesitará separar y escalar los componentes.

La arquitectura de producción recomendada utiliza workers independientes, varias réplicas de la aplicación, PostgreSQL, Redis y almacenamiento compatible con S3. La capacidad debe calcularse según el número máximo de flujos concurrentes, no solamente por la cantidad diaria de ejecuciones.

También debes configurar monitorización, retención de registros, copias de seguridad verificadas y aislamiento de las ejecuciones. El autoalojamiento entrega control, pero también traslada al administrador la responsabilidad sobre disponibilidad, actualizaciones y seguridad.

Instalar Activepieces mediante Docker Compose permite disponer de una plataforma de automatización controlada desde tu propia infraestructura. La parte más importante no es levantar los contenedores, sino elegir correctamente entre PGLite y PostgreSQL, proteger los secretos, configurar una URL pública estable y conservar copias de seguridad de la base de datos y de la clave de cifrado.

Con estas precauciones, podrás ejecutar flujos, recibir webhooks y conectar aplicaciones sin depender de la infraestructura alojada de Activepieces, manteniendo la posibilidad de ampliar el sistema conforme aumente la carga de trabajo.