Pt

Migração do PostgreSQL para o contêiner orchestrator-pg:v5.9.2+#

Migração do PostgreSQL para Chainguard#

⚠️ Importante: No PostgreSQL, a mudança para orchestrator-pg:v5.9.1+ não deve ser feita sobre o volume antigo. A nova imagem pode vir com uma versão major mais nova do PostgreSQL, e o diretório de dados antigo não vai subir. O único cenário seguro é: pg_dump -> novo volume -> restore.

1. O que preparar com antecedência#

O servidor deve ter:

  • o diretório de instalação do Sherpa Orchestrator;
  • um docker-compose.yml atualizado;
  • um arquivo .env com valores válidos para POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD e POSTGRES_DBNAME;
  • espaço livre suficiente em disco para o arquivo de dump e o novo volume;
  • permissão para executar docker compose, docker exec e docker volume.

Verifique os valores atuais:

cd /opt/SherpaOrchestrator

grep -E "^(DB_ENGINE|POSTGRES_HOST|POSTGRES_PORT|POSTGRES_USER|POSTGRES_PASSWORD|POSTGRES_DBNAME|POSTGRES_SCHEMA_NAME)=" .env
💡 Como o resultado deve ficar

Você deve ver os parâmetros de conexão do PostgreSQL vindos do .env.

É especialmente importante verificar:

  • DB_ENGINE=pgsql
  • POSTGRES_HOST=orchestrator-pg para o banco integrado no Docker
  • POSTGRES_DBNAME=orchestrator

Se o .env apontar para um PostgreSQL externo, este guia não se aplica.

2. Verificar o contêiner e o volume atuais#

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

docker volume ls | grep orchestrator-postgres

Confira também a versão do PostgreSQL:

docker exec orchestrator-pg sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DBNAME" -tAc "SELECT version();"'
💡 Por que isso é necessário

Se o volume atual foi inicializado, por exemplo, com PostgreSQL 14, e chainguard/postgres:latest já estiver em PostgreSQL 18, o novo contêiner não conseguirá usar diretamente o diretório de dados antigo.

3. Colocar o Orchestrator em modo de manutenção#

Antes do dump, pare a aplicação para que ninguém escreva no banco:

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

Se alguns serviços não forem usados na sua instalação, o Docker apenas informará isso.

Garanta que o contêiner do banco continue em execução:

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

4. Criar um backup lógico do PostgreSQL#

Crie um diretório para o backup:

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"

Gere o 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"

Confira se o arquivo foi criado:

ls -lh "${PG_BACKUP_FILE}"
tail -n 20 "${PG_BACKUP_FILE}"
💡 Por que usar pg_dump

pg_dump transfere a estrutura e os dados no nível SQL e não depende do formato interno do diretório de dados. Por isso ele é seguro ao migrar entre versões major do PostgreSQL.

5. Parar o contêiner antigo do PostgreSQL#

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

Ainda não remova o volume antigo. Ele é necessário para rollback.

6. Criar um volume novo para o PostgreSQL Chainguard#

Verifique o volume antigo:

docker volume ls | grep orchestrator-postgres

Crie um volume novo:

docker volume create orchestrator-postgres-chainguard

Verifique a criação:

docker volume inspect orchestrator-postgres-chainguard

7. Trocar o compose do cliente para o novo volume#

Abra docker-compose.client.yml e, no serviço orchestrator-pg, deixe o volume antigo comentado e ative o novo:

volumes:
  # O volume antigo é mantido como referência durante a migração:
  # - orchestrator-postgres:/data/postgres
  - orchestrator-postgres-chainguard:/data/postgres

Na seção volumes: no final do arquivo, o novo volume também deve estar ativo, e o antigo deve continuar comentado:

volumes:
  # orchestrator-postgres:
  #   driver: local

  orchestrator-postgres-chainguard:
    driver: local

Garanta também que a imagem orchestrator-pg já tenha sido compilada ou baixada com a base chainguard/postgres:latest.

docker image ls orchestrator-pg
💡 Por que o volume muda no compose

O novo contêiner deve iniciar em um diretório de dados vazio. Se o volume antigo continuar ativo, o PostgreSQL tentará abrir o diretório antigo e vai falhar por incompatibilidade de versão.

8. Subir o novo contêiner PostgreSQL#

Inicie apenas o PostgreSQL:

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

Confira os logs:

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

Quando o contêiner estiver pronto, verifique a conexão:

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

Resultado esperado:

1

9. Restaurar o dump no novo contêiner#

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

Depois da restauração, execute verificações 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 o esquema e os dados#

Confirme que o esquema de trabalho existe:

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 se o usuário admin continua presente:

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

Se você tiver suas próprias tabelas de controle, também verifique-as com SELECT COUNT(*).

11. Subir a aplicação novamente#

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

Se usar serviços adicionais:

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

Confira se o backend enxerga o banco:

docker logs --tail=100 orchestrator

Verifique a UI e a autenticação.

12. Rollback se algo der errado#

Se algo falhar após a migração:

  1. Pare os contêineres novos:
docker compose stop orchestrator orchestrator-nginx orchestrator-websocket orchestrator-pg
  1. Restaure o volume antigo em docker-compose.yml:
volumes:
  - orchestrator-postgres:/data/postgres
  1. Suba a versão antiga da imagem do PostgreSQL que originalmente funcionava com o volume.
  2. Inicie os serviços novamente:
docker compose --profile pg up -d orchestrator-pg
docker compose up -d orchestrator orchestrator-websocket orchestrator-nginx

13. O que pode ser removido após uma migração bem-sucedida#

Não remova nada imediatamente após a troca.

Quando tiver certeza de que o novo banco está estável:

  • mantenha a cópia SQL em um local separado;
  • mantenha o volume antigo durante o período de monitoramento;
  • só então remova o volume antigo manualmente.

Comando para remover o volume antigo:

docker volume rm orchestrator-postgres

Use-o apenas após uma verificação completa e somente se tiver certeza de que o rollback não é mais necessário.