Guía Completa de Activepieces: Automatización Inteligente y Agentes de IA

Actualizar Activepieces no consiste únicamente en descargar una imagen nueva y reiniciar el contenedor. La plataforma guarda flujos, conexiones, ejecuciones y secretos cifrados en distintos componentes, por lo que un cambio realizado sin copia de seguridad puede dejarte con una instalación aparentemente funcional, pero sin acceso a tus credenciales o automatizaciones.

El procedimiento también cambia dependiendo de cómo instalaste la plataforma. Una instancia doméstica con PGLite no se actualiza igual que el despliegue oficial con PostgreSQL, Redis, un servidor principal y varios workers. En esta guía veremos cómo actualizar Activepieces correctamente, comprobar que todo funciona y volver a la versión anterior si aparece algún problema.

Antes de actualizar: identifica cómo instalaste Activepieces

Activepieces ofrece actualmente dos despliegues de Docker principales. Es fundamental saber cuál estás utilizando porque los datos se almacenan de manera diferente en cada modalidad.

• Instalación oficial con Docker Compose: utiliza contenedores separados para la aplicación, el worker, PostgreSQL y Redis. Es la opción recomendada para servidores y entornos de producción.
• Instalación doméstica con Docker Run: ejecuta todo en un único contenedor con PGLite y una cola almacenada en memoria. Está pensada para proyectos personales instalados en una sola máquina.
• Plataforma administrada: si utilizas Activepieces Cloud, el proveedor se encarga de desplegar las actualizaciones y no debes ejecutar estos comandos.

Si tienes una carpeta con los archivos docker-compose.yml y .env, probablemente utilizas el despliegue oficial. En cambio, si ejecutaste un único comando con AP_DB_TYPE=PGLITE y tus datos se encuentran en ~/.activepieces, tienes la instalación doméstica.

También puedes comprobar los contenedores activos mediante:

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

La instalación completa mostrará servicios como app, worker, postgres y redis. La doméstica normalmente mostrará solamente un contenedor llamado activepieces.

Cómo comprobar la versión instalada y la disponible

En el despliegue oficial, la versión suele estar fijada mediante la variable AP_VERSION del archivo .env. Puedes consultarla desde la carpeta de Activepieces con:

grep '^AP_VERSION=' .env

También puedes ver qué imágenes están utilizando los servicios con este comando:

docker compose -p activepieces images

Antes de cambiar la versión, consulta las publicaciones del repositorio oficial y presta especial atención a los apartados denominados Breaking Changes. Estos avisos indican si debes modificar variables, ejecutar una migración especial o actualizar algún componente antes de arrancar la nueva imagen.

No conviene utilizar automáticamente cualquier versión recién publicada en un servidor importante. Activepieces publica actualizaciones con frecuencia, por lo que resulta más prudente fijar una versión concreta, probarla y actualizar de forma controlada.

Cómo hacer una copia de seguridad de Activepieces

En una instalación con Docker Compose, los flujos y conexiones se encuentran en PostgreSQL. Copiar únicamente la carpeta donde guardas el archivo Compose no crea una copia de la base de datos, ya que esta suele residir en un volumen de Docker.

Desde el directorio de Activepieces, crea una carpeta para los respaldos:

mkdir -p backups

Después exporta la base de datos PostgreSQL:

docker compose -p activepieces exec -T postgres \
  pg_dump -U postgres activepieces \
  > "backups/activepieces-$(date +%F-%H%M).sql"

El comando utiliza el usuario y el nombre de base de datos incluidos en el despliegue oficial. Si los modificaste en el archivo .env, tendrás que sustituirlos por tus valores.

Además de PostgreSQL, debes copiar el archivo de variables y la configuración de Compose:

cp .env "backups/env-$(date +%F-%H%M).backup"
cp docker-compose.yml "backups/docker-compose-$(date +%F-%H%M).yml"
chmod 600 backups/*

La copia de .env es imprescindible porque contiene AP_ENCRYPTION_KEY. Activepieces utiliza esta clave para cifrar las conexiones guardadas. Aunque restaures correctamente PostgreSQL, las credenciales no podrán descifrarse si pierdes o sustituyes esta clave.

Para reducir el riesgo de interrumpir una ejecución, realiza la actualización durante un periodo de poca actividad y comprueba previamente que no existan flujos importantes ejecutándose.

Cómo actualizar Activepieces con Docker Compose

Si instalaste Activepieces mediante el script oficial, la forma recomendada de actualizarlo es ejecutar desde su directorio:

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

Este procedimiento conserva el archivo .env, los datos y las modificaciones realizadas en docker-compose.yml. Si prefieres comprobar el script antes de ejecutarlo, puedes mostrar su contenido sin enviarlo directamente al intérprete:

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

Si gestionas Docker Compose manualmente, primero cambia la variable del archivo .env por la versión que quieras instalar:

AP_VERSION=X.Y.Z

Debes reemplazar X.Y.Z por el número exacto publicado en el repositorio. Después descarga las nuevas imágenes y recrea los servicios:

docker compose -p activepieces pull
docker compose -p activepieces up -d

Es importante mantener el nombre de proyecto activepieces. Si ejecutas Compose con otro nombre o desde una configuración distinta, Docker puede crear volúmenes nuevos y aparentemente vacíos, haciendo que parezca que tus flujos han desaparecido.

Al arrancar, Activepieces aplicará las migraciones correspondientes a la base de datos. No detengas los contenedores durante este proceso salvo que los registros muestren un error claro.

Cómo actualizar la instalación doméstica con PGLite

La versión doméstica almacena sus datos dentro de la carpeta ~/.activepieces. Antes de sustituir el contenedor, detenlo y crea una copia completa:

docker stop activepieces
cp -a ~/.activepieces \
  "$HOME/.activepieces-backup-$(date +%F-%H%M)"

Después elimina únicamente el contenedor y descarga la imagen nueva:

docker rm activepieces
docker pull activepieces/activepieces:latest

Finalmente, vuelve a ejecutar el mismo comando utilizado durante la instalación, conservando el volumen, el puerto y las variables originales:

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="https://automatizaciones.ejemplo.com" \
  activepieces/activepieces:latest

Sustituye la URL del ejemplo por la dirección real de tu instancia. Los flujos sobrevivirán porque permanecen en la carpeta montada y no dentro del contenedor eliminado.

Esta modalidad está pensada para una sola máquina y no permite escalar mediante varios workers. Si necesitas migrar a la edición empresarial o desplegar varias instancias, no basta con cambiar unas variables: tendrás que planificar por separado la migración hacia PostgreSQL y Redis.

Cómo actualizar Activepieces desde Dockge, Portainer o Coolify

Cuando Activepieces está gestionado desde un panel visual, evita actualizarlo simultáneamente desde la terminal y desde la interfaz. Haz primero las mismas copias de PostgreSQL y del archivo .env, modifica después la etiqueta de la imagen y utiliza la función de recrear, desplegar o actualizar el stack disponible en el panel.

Si utilizas Dockge, puedes seguir el procedimiento para actualizar un contenedor Docker usando Dockge, manteniendo intactos los volúmenes y las variables de Activepieces.

En todos los casos, comprueba que el panel no haya sustituido la versión fijada por latest sin que te des cuenta. En servidores de producción es preferible utilizar una etiqueta de versión concreta para poder controlar cuándo se aplican los cambios.

Cómo comprobar que la actualización funciona

Cuando los contenedores estén iniciados, comprueba su estado:

docker compose -p activepieces ps

Los servicios principales deben aparecer activos. Después consulta el endpoint de salud:

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

Accede al panel y entra en Platform Admin, Infrastructure y Workers. Debe aparecer al menos un worker conectado. También conviene ejecutar manualmente un flujo de prueba y revisar una automatización que utilice credenciales OAuth o una API externa.

Si necesitas investigar un fallo, consulta por separado los registros de la aplicación y del worker:

docker compose -p activepieces logs --tail=200 app
docker compose -p activepieces logs --tail=200 worker

No des por finalizada la actualización solo porque el panel cargue. Comprueba que los flujos se ejecuten, las conexiones puedan descifrarse y los webhooks sigan siendo accesibles.

Cómo volver a la versión anterior

Si la versión nueva provoca un fallo, cambiar únicamente la etiqueta de la imagen puede no ser suficiente. Algunas actualizaciones modifican el esquema de PostgreSQL, por lo que Activepieces incluye un comando específico para revertir las migraciones de la base de datos.

Primero detén los servicios:

docker compose -p activepieces down

Después ejecuta el rollback utilizando la imagen nueva, ya que es la que contiene la lógica necesaria para deshacer su migración:

docker run --rm --env-file .env --entrypoint npm \
  activepieces/activepieces:VERSION_NUEVA \
  run rollback -- --to VERSION_ANTERIOR

Sustituye ambos valores por las versiones correspondientes. Después cambia AP_VERSION en el archivo .env a la versión anterior y levanta de nuevo los servicios:

docker compose -p activepieces up -d

Antes de hacerlo, revisa las notas de lanzamiento. Algunas migraciones destructivas pueden requerir confirmación adicional y no deben forzarse sin disponer de una copia válida. Si tienes dudas, resulta más seguro restaurar el respaldo de PostgreSQL y recuperar simultáneamente el archivo .env correspondiente.

Errores frecuentes al actualizar Activepieces

Si los flujos han desaparecido, comprueba que sigues utilizando el mismo volumen de PostgreSQL y el mismo nombre de proyecto de Compose. Ejecutar el stack desde otra carpeta o sin -p activepieces puede provocar la creación de un volumen de base de datos diferente.

Cuando las conexiones aparecen, pero dejan de funcionar, revisa AP_ENCRYPTION_KEY. Restaurar la base de datos con una clave distinta impide descifrar las credenciales almacenadas y obliga a volver a conectar las aplicaciones.

Si la sección de workers está vacía y aparecen errores de Socket.IO, el worker probablemente no puede comunicarse con el servicio principal. Dentro de su configuración, AP_FRONTEND_URL debe apuntar al nombre interno del servicio:

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

La URL pública debe mantenerse en la configuración de la aplicación principal. Dentro del contenedor worker, localhost hace referencia al propio worker y no al servidor de Activepieces.

Si Docker rechaza los comandos, comprueba que estás usando Docker Compose v2:

docker compose version

El antiguo comando docker-compose no es compatible con el despliegue oficial actual.

Cuando el contenedor principal se reinicia continuamente, revisa sus registros. Una causa posible en la edición empresarial es mantener AP_EXECUTION_MODE=UNSANDBOXED, un valor rechazado actualmente. En este escenario debe utilizarse un modo compatible, como SANDBOX_CODE_ONLY.

Por último, si el panel carga, pero determinadas ejecuciones empiezan a fallar después de actualizar, comprueba los cambios incompatibles de la versión instalada. Una pieza, una variable o un comportamiento de los webhooks puede haber cambiado aunque el despliegue general parezca correcto.

Actualizar Activepieces de forma segura requiere identificar el tipo de instalación, respaldar PostgreSQL o PGLite y conservar las claves del archivo .env. Con una versión fijada, una copia comprobada y una validación posterior de los workers y flujos, puedes incorporar las novedades sin poner en riesgo las automatizaciones que ya tienes en producción.