Pt

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

⚠️ Importante: Para a migração para orchestrator-db:v5.9.1+, é mais seguro usar um dump lógico e um novo volume. Isso evita o risco de danificar o diretório de dados antigo e permite fazer rollback sem perda de dados.

1. O que saber com antecedência#

Nas imagens Sherpa Orchestrator baseadas em Chainguard para MariaDB, é usado:

  • apenas MYSQL_ROOT_PASSWORD para inicialização;
  • o mount existente ./backend/config/my.cnf:/etc/mysql/conf.d/my.cnf.

Os parâmetros antigos MYSQL_ALLOW_EMPTY_PASSWORD, MYSQL_USER e MYSQL_PASSWORD para o contêiner integrado não são mais necessários.

2. Verificar a configuração atual#

cd /opt/SherpaOrchestrator

grep -E "^(DB_ENGINE|MYSQL_HOST|MYSQL_PORT|MYSQL_USER|MYSQL_PASSWORD|MYSQL_DB)=" .env

Para o MariaDB integrado, pelo menos os itens abaixo devem estar corretos:

  • DB_ENGINE=mysql
  • MYSQL_HOST=orchestrator-db
  • MYSQL_DB=orchestrator

Verifique o contêiner e o volume atuais:

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

docker volume ls | grep orchestrator-mysql-data

3. Colocar a aplicação em modo de manutenção#

Pare os serviços da aplicação para que não haja novas gravações durante o dump:

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

Garanta que o contêiner orchestrator-db continue em execução:

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

4. Criar um backup lógico do MariaDB#

Crie um diretório:

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

Gere um dump dos bancos em uso:

docker exec orchestrator-db sh -lc 'mariadb-dump \
  -uroot \
  -p"$MYSQL_ROOT_PASSWORD" \
  --databases orchestrator orchestrator_archive \
  --single-transaction \
  --routines \
  --events \
  --triggers' > "$DB_BACKUP_FILE"

Verifique o resultado:

ls -lh "${DB_BACKUP_FILE}"
tail -n 20 "${DB_BACKUP_FILE}"
💡 Por que usar mariadb-dump

Um dump lógico transfere os dados no nível SQL e não depende do formato interno do datadir. O volume antigo permanece intacto, e o novo contêiner sobe em um diretório limpo.

5. Parar o contêiner antigo do MariaDB#

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

Ainda não remova o volume antigo.

6. Criar um novo volume para o MariaDB Chainguard#

Verifique o volume antigo:

docker volume ls | grep orchestrator-mysql-data

Crie um novo:

docker volume create orchestrator-mysql-data-chainguard

Confira-o:

docker volume inspect orchestrator-mysql-data-chainguard

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

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

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

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

volumes:
  # orchestrator-mysql-data:
  #   driver: local

  orchestrator-mysql-data-chainguard:
    driver: local

Verifique se em environment permanece apenas o seguinte:

environment:
  MYSQL_ROOT_PASSWORD: '${MYSQL_PASSWORD}'
💡 Por que isso é importante

Para o novo contêiner MariaDB na Chainguard, é mais seguro usar uma única senha de root, sem a combinação legada MYSQL_ALLOW_EMPTY_PASSWORD e usuários bootstrap adicionais. Isso remove pontos extras de falha em um volume vazio.

8. Subir o novo contêiner MariaDB#

docker compose --profile mariadb up -d orchestrator-db

Confira os logs:

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

Verifique se está pronto para consultas:

docker exec orchestrator-db sh -lc 'mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" -Nse "SELECT 1;"'

Resultado esperado:

1

9. Restaurar o backup no novo contêiner#

docker exec -i orchestrator-db sh -lc 'mariadb \
  -uroot \
  -p"$MYSQL_ROOT_PASSWORD"' < "$DB_BACKUP_FILE"

10. Verificar os bancos de dados e a configuração#

Confirme que ambos os bancos estão presentes:

docker exec orchestrator-db sh -lc 'mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" -Nse "SHOW DATABASES LIKE '\''orchestrator'\'';"'

docker exec orchestrator-db sh -lc 'mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" -Nse "SHOW DATABASES LIKE '\''orchestrator_archive'\'';"'

Verifique consultas de teste:

docker exec orchestrator-db sh -lc 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb \
  -uroot \
  orchestrator \
  -Nse "SELECT COUNT(*) FROM accounts;"'

docker exec orchestrator-db sh -lc 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb \
  -uroot \
  orchestrator \
  -Nse "SELECT COUNT(*) FROM processes;"'

Confira se o my.cnf personalizado foi aplicado:

docker exec orchestrator-db sh -lc 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb \
  -uroot \
  -Nse "SHOW VARIABLES LIKE '\''max_allowed_packet'\'';"'

Se o mount de configuração estiver correto, você verá o valor atual de backend/config/my.cnf.

11. Subir a aplicação novamente#

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

Se necessário, inicie os serviços adicionais:

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

Confira os logs do backend:

docker logs --tail=100 orchestrator

Confira a UI e algumas telas de trabalho.

12. Rollback se algo der errado#

Se o novo MariaDB não funcionar corretamente:

  1. Pare os serviços:
docker compose stop orchestrator orchestrator-nginx orchestrator-websocket orchestrator-db
  1. Restaure o volume antigo em docker-compose.yml:
volumes:
  - orchestrator-mysql-data:/var/lib/mysql
  1. Suba a versão antiga e validada da imagem MariaDB que originalmente funcionava com o volume.
  2. Inicie os contêineres novamente:
docker compose --profile mariadb up -d orchestrator-db
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 imediatamente o seguinte após a troca:

  • o backup SQL;
  • o volume antigo;
  • os arquivos antigos da imagem.

Depois de um período de observação, o volume antigo pode ser removido:

docker volume rm orchestrator-mysql-data

Faça isso apenas após uma verificação completa.