Docker Compose no desenvolvimento local: arquivos de override, profiles, dependências saudáveis e watch

Objetivo

Um único docker compose up que entregue a todo colaborador as mesmas versões de banco de dados, fila e serviços usadas em produção, com recarga rápida de código, sem transformar o arquivo versionado em um artefato exclusivo do ambiente local.

Pré-requisitos

Um Dockerfile por serviço que compile a partir de um checkout limpo, health checks definidos para as dependências com estado e configuração lida de variáveis de ambiente.

Passos

1. Escreva o compose.yaml como a base no formato de produção: imagens referenciadas por tag, nomes de serviço iguais aos nomes DNS usados na configuração, sem portas no host e sem bind mounts. A documentação do Docker (citada) afirma que o Compose lê por padrão o compose.yaml e um compose.override.yaml opcional e os mescla, com os arquivos posteriores sobrescrevendo ou estendendo os anteriores.
2. Coloque as conveniências locais no compose.override.yaml: portas publicadas, um bind mount da árvore de código-fonte e variáveis de ambiente de depuração. Faça o commit dele se todos os desenvolvedores quiserem o mesmo; caso contrário, versione um arquivo .example e ignore o arquivo real.
3. Declare as dependências com condições: depends_on: {db: {condition: service_healthy}} faz o Compose esperar pelo health check da dependência, e não apenas pela inicialização do contêiner; service_completed_successfully espera um contêiner de migração de execução única terminar com código 0 (ambos na referência de serviços citada).
4. Associe as ferramentas opcionais (captura de e-mail, interface de administração, gerador de carga) a profiles: para que um up simples as ignore; inicie-as com --profile debug ou COMPOSE_PROFILES.
5. Adicione uma seção develop.watch: sync para código interpretado, sync+restart quando o processo precisa reiniciar para assumir as mudanças e rebuild quando os manifestos de dependências mudam; execute com docker compose up --watch ou com docker compose watch para manter os eventos de sincronização fora dos logs da aplicação. A página citada do Compose Watch documenta essas ações e observa que o watch só acompanha serviços construídos a partir de código local com build, e não os que usam uma image já pronta.
6. Guarde em .env os valores padrão não secretos usados na interpolação de variáveis e mantenha as credenciais fora dos arquivos versionados; passe-as por entradas env_file ignoradas pelo git.
7. Execute docker compose config na CI para renderizar o arquivo mesclado e detectar erros de caminho ou de interpolação.

Resultado esperado

Novos colaboradores chegam a um ambiente funcional com um único comando; o arquivo base serve também como documentação da topologia de execução; as diferenças em relação à produção aparecem em um pequeno arquivo de override, em vez de edições espalhadas.

Limites e base de verificação

O Compose descreve um único host e não é um orquestrador de produção; limites de recursos, políticas de reinício e rede diferem do Kubernetes. A página citada do Compose Watch apresenta o watch como complemento dos bind mounts, não como substituto: suas regras de ignore permitem deixar uma árvore como node_modules/ fora da sincronização, o que a página justifica pela carga de E/S gerada por muitos arquivos pequenos e por artefatos compilados que não podem ser compartilhados entre as plataformas do host e do contêiner. O comportamento segue as referências citadas; nenhuma medição de tempo é afirmada.