ADR 0001 — Variantes de orquestração: docker-compose, prod-test e swarm¶

Nota

Fonte mantida em docs/decisions/0001-docker-compose-vs-swarm.md.

Status¶

Aceito (registra decisão implícita já em vigor no repositório).

Contexto¶

O repositório mantém três variantes de arquivo de orquestração na raiz:

docker-compose.yml — orquestração principal, usada em desenvolvimento local e como base do deploy em produção.
docker-compose.prod-test.yaml — variante para validação de configuração de produção antes do deploy real.
docker-compose.swarm.yaml — variante para orquestração via Docker Swarm.

Todas as três seguem o mesmo padrão de labels Traefik (ver docs/modelo trafik yaml/docker-compose.yaml), mas diferem em como lidam com réplicas, redes externas e segredos.

Decisão¶

Manter docker-compose.yml como fonte de verdade para desenvolvimento e para o deploy real em produção via docker compose (não Swarm), reservando docker-compose.swarm.yaml para um cenário de múltiplos nós que ainda não é o caso de uso atual (stack roda em um único host). docker-compose.prod-test.yaml é usado como bancada de teste de configuração antes de qualquer mudança em docker-compose.yml chegar à produção.

Consequências¶

Mudanças estruturais em serviços (labels Traefik, healthchecks, networks) devem ser replicadas manualmente entre as três variantes quando aplicável.
Divergência entre as variantes é um risco conhecido.
Se o projeto crescer para múltiplos hosts, a variante Swarm já existe como ponto de partida.