Migración de PostgreSQL al contenedor orchestrator-pg:v5.9.2+#

Migración de PostgreSQL a Chainguard#

⚠️ Importante: En PostgreSQL, el cambio a orchestrator-pg:v5.9.1+ no debe hacerse sobre el volumen anterior. La nueva imagen puede venir con una versión major más nueva de PostgreSQL, y el directorio de datos antiguo no arrancará. El único escenario seguro es: pg_dump -> volumen nuevo -> restore.

1. Qué preparar de antemano#

El servidor debe tener:

• el directorio de instalación de Sherpa Orchestrator;
• un docker-compose.yml actualizado;
• un archivo .env con valores válidos para POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD y POSTGRES_DBNAME;
• espacio libre suficiente en disco para el archivo de dump y el volumen nuevo;
• permisos para ejecutar docker compose, docker exec y docker volume.

Revise los valores actuales:

cd /opt/SherpaOrchestrator

grep -E "^(DB_ENGINE|POSTGRES_HOST|POSTGRES_PORT|POSTGRES_USER|POSTGRES_PASSWORD|POSTGRES_DBNAME|POSTGRES_SCHEMA_NAME)=" .env

2. Verificar el contenedor y el volumen actuales#

docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}" | grep orchestrator-pg

docker volume ls | grep orchestrator-postgres

Compruebe también la versión de PostgreSQL:

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT version();"'

3. Poner Orchestrator en modo de mantenimiento#

Antes del dump, detenga la aplicación para que nadie escriba en la base de datos:

docker compose stop orchestrator orchestrator-nginx orchestrator-websocket orchestrator-vnc-proxy orchestrator-autopilot

Si algunos servicios no se usan en su instalación, Docker simplemente lo informará.

Asegúrese de que el contenedor de la base de datos siga ejecutándose:

docker ps --format "table {{.Names}}\t{{.Status}}" | grep orchestrator-pg

4. Crear una copia de seguridad lógica de PostgreSQL#

Cree un directorio para la copia de seguridad:

sudo mkdir -p ./backups/postgresql
sudo chown -R "$USER:$USER" ./backups
export PG_MIGRATION_TS="$(date +%Y%m%d_%H%M%S)"
export PG_BACKUP_FILE="./backups/postgresql/orchestrator_${PG_MIGRATION_TS}.sql"

Genere el dump:

docker exec orchestrator-pg sh -lc 'pg_dump \
  -U "$POSTGRES_USER" \
  -d "$POSTGRES_DBNAME" \
  --clean \
  --if-exists \
  --no-owner \
  --no-privileges' > "$PG_BACKUP_FILE"

Compruebe que el archivo se creó:

ls -lh "${PG_BACKUP_FILE}"
tail -n 20 "${PG_BACKUP_FILE}"

5. Detener el contenedor antiguo de PostgreSQL#

docker compose stop orchestrator-pg
docker ps -a --format "table {{.Names}}\t{{.Status}}" | grep orchestrator-pg

Todavía no elimine el volumen antiguo. Se necesita para rollback.

6. Crear un volumen nuevo para PostgreSQL Chainguard#

Revise el volumen antiguo:

docker volume ls | grep orchestrator-postgres

Cree un volumen nuevo:

docker volume create orchestrator-postgres-chainguard

Verifique su creación:

docker volume inspect orchestrator-postgres-chainguard

7. Cambiar el compose del cliente al volumen nuevo#

Abra docker-compose.client.yml y en el servicio orchestrator-pg deje el volumen antiguo comentado y active el nuevo:

volumes:
  # El volumen antiguo se conserva como referencia durante la migración:
  # - orchestrator-postgres:/data/postgres
  - orchestrator-postgres-chainguard:/data/postgres

En la sección volumes: al final del archivo, el volumen nuevo también debe estar activo y el antiguo debe seguir comentado:

volumes:
  # orchestrator-postgres:
  #   driver: local

  orchestrator-postgres-chainguard:
    driver: local

Asegúrese también de que la imagen orchestrator-pg ya se haya compilado o descargado con la base chainguard/postgres:latest.

docker image ls orchestrator-pg

8. Levantar el nuevo contenedor de PostgreSQL#

Inicie solo PostgreSQL:

docker compose --profile pg up -d orchestrator-pg

Revise los logs:

docker logs -f --tail=100 orchestrator-pg

Cuando el contenedor esté listo, verifique la conexión:

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT 1;"'

Resultado esperado:

1

9. Restaurar el dump en el nuevo contenedor#

docker exec -i orchestrator-pg sh -lc 'psql \
  -U "$POSTGRES_USER" \
  -d "$POSTGRES_DBNAME" \
  -v ON_ERROR_STOP=1' < "$PG_BACKUP_FILE"

Después de la restauración, ejecute comprobaciones básicas:

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT COUNT(*) FROM orchestrator.accounts;"'

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT COUNT(*) FROM orchestrator.processes;"'

10. Verificar el esquema y los datos#

Compruebe que exista el esquema de trabajo:

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT schema_name FROM information_schema.schemata WHERE schema_name = '\''orchestrator'\'';"'

Verifique que el usuario admin siga presente:

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT COUNT(*) FROM orchestrator.accounts WHERE login = '\''admin'\'';"'

Si tiene sus propias tablas de control, también verifíquelas con SELECT COUNT(*).

11. Volver a levantar la aplicación#

docker compose up -d orchestrator orchestrator-websocket orchestrator-nginx

Si usa servicios adicionales:

docker compose up -d orchestrator-vnc-proxy
docker compose up -d orchestrator-autopilot
docker compose up -d orchestrator-vault

Compruebe que el backend vea la base de datos:

docker logs --tail=100 orchestrator

Revise la UI y la autenticación.

12. Rollback si algo sale mal#

Si algo falla después de la migración:

1. Detenga los contenedores nuevos:

docker compose stop orchestrator orchestrator-nginx orchestrator-websocket orchestrator-pg

2. Restaure el volumen antiguo en docker-compose.yml:

volumes:
  - orchestrator-postgres:/data/postgres

3. Inicie la versión antigua de la imagen de PostgreSQL que originalmente funcionaba con el volumen.
4. Vuelva a iniciar los servicios:

docker compose --profile pg up -d orchestrator-pg
docker compose up -d orchestrator orchestrator-websocket orchestrator-nginx

13. Qué se puede eliminar después de una migración exitosa#

No elimine nada inmediatamente después del cambio.

Cuando esté seguro de que la nueva base de datos es estable:

• conserve la copia SQL en una ubicación separada;
• conserve el volumen antiguo durante el período de monitoreo;
• solo entonces elimine manualmente el volumen antiguo.

Comando para eliminar el volumen antiguo:

docker volume rm orchestrator-postgres

Úselo solo después de una verificación completa y solo si está seguro de que ya no se necesita rollback.