Docker Compose: como subir ambientes completos com um comando

Para subir ambientes completos com um unico comando, o Docker Compose e a ferramenta definitiva. Basta ter um arquivo compose.yaml configurado na raiz do seu projeto e executar docker compose up -d no terminal. Este comando instrui a engine a ler as configuracoes, baixar as imagens necessarias, criar redes isoladas e iniciar todos os servicos (como bancos de dados e APIs) simultaneamente em segundo plano.

Principais Aprendizados

• O comando antigo docker-compose (com hifen) foi descontinuado; o padrao atual em 2026 e o plugin docker compose (v5).
• A funcionalidade watch substitui os antigos bind mounts, oferecendo hot-reload em milissegundos para desenvolvimento.
• O campo version no topo do arquivo YAML nao e mais necessario e e ignorado pelas versoes modernas.

O fim do V1 e a era do Docker Compose V5

E um fato verificado que o binario original em Python (docker-compose com hifen) foi oficialmente descontinuado e removido de imagens de runners do GitHub Actions entre 2024 e abril de 2025, conforme documentado por fontes como o BDTeo. O consenso atual e unanime da area e que o uso do plugin em Go (com espaco, docker compose) e obrigatorio. Manter scripts com o hifen e considerado um debito tecnico critico. Atualmente, a versao estavel e a v5, que pulou as versoes 3 e 4 para alinhar a nomenclatura e evitar confusoes com os antigos formatos de arquivo.

Como estruturar seu compose.yaml moderno

Um erro muito comum no passado era a preocupacao com a tag de versao. E um fato documentado pela Docker Documentation que a declaracao do campo version no topo dos arquivos YAML tornou-se inutil. O Compose v2 e v5 ignoram esse campo e utilizam a Compose Specification continua. Seu arquivo deve comecar diretamente com services:. Se voce estiver configurando um banco de dados relacional e um cache em memoria como o Redis, basta declara-los como servicos distintos, aproveitando o Docker Bake como motor de build padrao por tras dos panos.

Developer Experience (DX): A revolucao do Watch

O estado da arte no desenvolvimento local envolve uma DX avancada. O consenso da comunidade e que usar volumes tradicionais (bind mounts) para desenvolvimento em macOS e Windows gera severos gargalos de I/O. A solucao, que e um fato verificado desde a introducao na v2.22 e aprimorada na v5, e o docker compose watch. Ele permite acoes de sync e rebuild em tempo real. Se voce trabalha com Node.js, por exemplo, as alteracoes no codigo refletem no container em milissegundos, acionando o Hot Module Replacement instantaneamente, sem precisar reconstruir a imagem.

Modularizacao com Include e Alertas de Seguranca

Para evitar arquivos compose monoliticos com dezenas de servicos, a nova diretiva include permite importar fragmentos de outros diretorios ou repositorios. No entanto, e um fato verificado recentemente que o uso dessa diretiva com artefatos OCI apresentou a vulnerabilidade critica CVE-2025-62725 (path traversal). O consenso de seguranca exige a atualizacao para as versoes v2.40.2+ ou v5.x para mitigar o risco de comprometimento do sistema.

Docker Compose em Producao: A Controversia

Existe um debate continuo sobre o uso da ferramenta em producao. Puristas da nuvem argumentam que adotar o Kubernetes ou servicos gerenciados e o unico caminho viavel. Contudo, minha opiniao profissional como especialista senior e que o deploy em no unico (Single-Node Deploy) com Docker Compose e perfeitamente aceitavel e ate recomendado para startups, projetos menores e MVPs, onde a complexidade de orquestradores maiores e um desperdicio de recursos e tempo.

Perguntas Frequentes

Preciso colocar version: '3.9' no meu compose.yaml?

Nao. O campo version esta morto e e ignorado pelas versoes atuais (v2 e v5). O arquivo deve comecar diretamente pela chave services seguindo a Compose Specification.

Posso usar docker-compose up em pipelines de CI/CD?

Nao. O binario v1 (com hifen) foi removido dos principais provedores como GitHub Actions. Usar o comando antigo quebrara sua esteira. O comando correto em 2026 e docker compose up.

O Docker Compose e lento para desenvolvimento frontend?

Isso e um mito antigo. Com a funcionalidade docker compose watch, a acao de sync atualiza os arquivos no container em milissegundos, resolvendo os problemas de lentidao dos antigos bind mounts.

Fontes

• Docker Documentation (Compose CLI Versioning & History) - Acessar documentacao
• BDTeo (Docker Compose v1 is Dead, v5 is Here) - Acessar artigo