docker-postgres-production-stack

name

docker-postgres-production-stack

description

Builds production-grade Docker and PostgreSQL application stacks using Docker Compose and Docker Swarm with mandatory security, efficiency, robustness, and scalability rules. Generates compose files, service definitions, secrets, configs, networks, and PostgreSQL configurations ready for software development and deployment. Use when containerizing applications with PostgreSQL, defining multi-service Compose stacks, or deploying stateful services to Docker Swarm. Don't use for non-PostgreSQL databases, standalone container deployments without orchestration, or local-only experiments that do not require production-ready defaults.

Stack de Produção Docker + PostgreSQL

Procedimentos

Etapa 1: Carregar as Regras Obrigatórias

1. Ler references/compose-rules.md e aplicar cada regra como obrigatória.
2. Ler references/postgres-hardening.md e aplicar cada regra como obrigatória.
3. Ler references/swarm-rules.md e aplicar cada regra como obrigatória.

Etapa 2: Preparar o Diretório do Projeto

1. Criar um diretório dedicado ao stack.
2. Criar um diretório .stack-secrets/ com permissões restritas ao operador (por exemplo, chmod 700).
3. Verificar se o Docker Engine e o Docker Compose CLI estão instalados e se o contexto ativo aponta para o swarm ou ambiente de nó único desejado.

Etapa 3: Gerar Secrets e Configs

1. Executar python3 scripts/generate-stack-secrets.py --output-dir .stack-secrets/.
2. Verificar se os seguintes arquivos existem em .stack-secrets/:
   • postgres_password.txt
   • db_password.txt
   • tls.crt
   • tls.key
   • pg_hba.conf
   • healthcheck.sh
   • traefik.yml
3. Adicionar .stack-secrets/ ao .gitignore e nunca commitar arquivos de secret.
4. Copiar assets/postgres-config-template.conf para .stack-secrets/postgresql.conf.
5. Ajustar shared_buffers, effective_cache_size, work_mem e maintenance_work_mem em .stack-secrets/postgresql.conf para corresponder ao limite de memória do container PostgreSQL declarado em compose.yaml.

Etapa 3.1: Usar Certificado TLS Real (Produção)

1. Obter um certificado TLS válido assinado por uma CA confiável (por exemplo, Let's Encrypt) ou fornecido pela equipe de infraestrutura.
2. Importar o certificado e a chave:
   • python3 scripts/import-tls-certificate.py --cert-file /caminho/certificado.crt --key-file /caminho/chave.key --output-dir .stack-secrets --create-secrets
3. Este comando copia os arquivos para .stack-secrets/tls.crt e .stack-secrets/tls.key e cria/atualiza os secrets tls_certificate e tls_key no swarm.

Etapa 4: Construir o Arquivo Compose

1. Copiar assets/compose-template.yaml para compose.yaml na raiz do projeto.
2. Substituir cada placeholder em compose.yaml por valores concretos:
   • ${TRAEFIK_VERSION} pela versão principal fixa do Traefik.
   • ${TRAEFIK_DIGEST} pelo digest SHA256 da imagem do Traefik.
   • ${SERVER_IMAGE} pelo repositório da imagem do server.
   • ${SERVER_TAG} pela tag de versão imutável do server.
   • ${SERVER_DIGEST} pelo digest SHA256 da imagem do server.
   • ${SERVER_HOST} pelo hostname público atendido pelo Traefik.
   • ${WORKER_IMAGE} pelo repositório da imagem do worker.
   • ${WORKER_TAG} pela tag de versão imutável do worker.
   • ${WORKER_DIGEST} pelo digest SHA256 da imagem do worker.
   • ${POSTGRES_VERSION} pela versão principal fixa do PostgreSQL.
   • ${POSTGRES_DIGEST} pelo digest SHA256 da imagem do PostgreSQL.
3. Nunca deixar uma imagem sem pinagem ou referenciando uma tag flutuante como latest.
4. Executar python3 scripts/validate-compose.py compose.yaml.
5. Se o script reportar falhas, ler as mensagens, consultar references/compose-rules.md, aplicar a regra correspondente e executar o validador novamente até obter sucesso.

Etapa 5: Criar Secrets e Configs do Docker Swarm

1. Inicializar o swarm caso ainda não esteja ativo: docker swarm init.
2. Criar os secrets obrigatórios a partir dos arquivos gerados:
   • docker secret create postgres_password .stack-secrets/postgres_password.txt
   • docker secret create db_password .stack-secrets/db_password.txt
   • docker secret create tls_certificate .stack-secrets/tls.crt
   • docker secret create tls_key .stack-secrets/tls.key
3. Criar os configs obrigatórios:
   • docker config create traefik_config .stack-secrets/traefik.yml
   • docker config create postgres_config .stack-secrets/postgresql.conf
   • docker config create postgres_hba .stack-secrets/pg_hba.conf
   • docker config create postgres_healthcheck .stack-secrets/healthcheck.sh
4. Confirmar que os recursos existem com docker secret ls e docker config ls.

Etapa 6: Fazer Deploy e Verificar o Stack

1. Fazer deploy do stack: docker stack deploy -c compose.yaml <nome-do-stack>.
2. Verificar o estado dos serviços: docker service ls.
3. Verificar o posicionamento das tarefas de cada serviço:
   • docker service ps <nome-do-stack>_traefik
   • docker service ps <nome-do-stack>_server
   • docker service ps <nome-do-stack>_worker
   • docker service ps <nome-do-stack>_postgres
4. Inspecionar o status de saúde de cada container:
   • docker inspect --format='{{.State.Health.Status}}' <id-do-container>
5. Confirmar que o Traefik redireciona HTTP para HTTPS e serve o server através do entrypoint websecure.
6. Confirmar que o server e o worker conectam ao PostgreSQL usando sslmode=require e a senha montada em /run/secrets/db_password.

Etapa 7: Operar e Manter

1. Monitorar logs com docker service logs <nome-do-stack>_postgres e docker service logs <nome-do-stack>_traefik.
2. Rotacionar secrets criando novas versões (por exemplo, postgres_password_v2), atualizando o serviço para montar o novo secret e removendo o secret antigo somente após todas as tarefas estarem estáveis.
3. Nunca commitar .stack-secrets/ no controle de versão.

Etapa 8: Backup e Restore

1. Executar backup lógico diário:
   • python3 scripts/backup-postgres.py --stack-name <nome-do-stack> --output-dir ./backups --retention-days 7
2. Verificar se o arquivo .sql.gz foi gerado e tem tamanho maior que zero.
3. Armazenar backups fora do nó do swarm (S3, NFS, outro storage durável).
4. Para restaurar:
   • python3 scripts/restore-postgres.py --stack-name <nome-do-stack> --backup-file ./backups/app_db-YYYYMMDD-HHMMSS.sql.gz
5. O restore exige confirmação digitando restaurar e sobrescreve o banco de destino.

Etapa 9: TLS com Let's Encrypt (Ambientes Públicos)

1. Em ambientes acessíveis pela internet, usar assets/traefik-letsencrypt-template.yaml como base para .stack-secrets/traefik.yml.
2. Preencher ${ACME_EMAIL} com um email válido para notificações da ACME.
3. Configurar tlsChallenge ou dnsChallenge conforme a infraestrutura DNS disponível.
4. Adicionar um volume nomeado traefik_acme no compose.yaml e montá-lo em /letsencrypt no serviço traefik.
5. Alterar as labels do server para incluir:
   • traefik.http.routers.server.tls.certresolver=letsencrypt
6. Remover as secrets tls_certificate e tls_key do serviço traefik, pois o Traefik gerenciará os certificados automaticamente.
7. O PostgreSQL continua usando os secrets tls_certificate e tls_key para TLS entre aplicação e banco; fornecer certificados reais para o PostgreSQL também.

Tratamento de Erros

• Falha de validação: Se scripts/validate-compose.py terminar com erro, ler a saída de stderr, abrir references/compose-rules.md, aplicar a regra correspondente e executar o validador novamente.
• Falha na inicialização do PostgreSQL: Inspecionar docker service logs <nome-do-stack>_postgres. Verificar se PGDATA corresponde ao mount de volume, se o secret postgres_password está montado em /run/secrets/postgres_password e se postgresql.conf está montado em /etc/postgresql/postgresql.conf.
• Falha na inicialização do Traefik: Inspecionar docker service logs <nome-do-stack>_traefik. Verificar se traefik_config está montado em /etc/traefik/traefik.yml e se os secrets TLS estão montados em /run/secrets/tls.crt e /run/secrets/tls.key.
• Rejeição de certificado: Se os clientes rejeitarem o certificado TLS, substituir os certificados autoassinados tls.crt e tls.key por certificados assinados por uma CA confiável, recriar os secrets e refazer o deploy do stack. Ou usar a Etapa 9 para ativar Let's Encrypt.
• Falha de healthcheck: Verificar se os nomes de usuário e banco de dados no healthcheck correspondem a POSTGRES_USER e POSTGRES_DB, e se o arquivo de senha é legível.
• Falha de backup: Verificar se o secret postgres_password existe, se a rede <stack-name>_backend está acessível e se o container consegue resolver postgres.
• Swarm manager quorum loss: Restaurar a partir dos backups do Raft ou seguir o procedimento documentado de recuperação de manager antes de fazer outras alterações no swarm.