Docker Compose configuracao: guia passo a passo completo

Se você já tentou subir vários contêineres Docker manualmente, sabe que o negócio vira bagunça rápido. O Docker Compose resolve isso: com um único arquivo YAML, você define tudo, serviços, redes, volumes, e sobe o ambiente inteiro com um comando. Vou te mostrar como configurar o seu do zero.

Pré-requisitos: Docker Desktop instalado (no Windows ou Mac, ele já vem com o Compose; no Linux, instale o plugin docker-compose-plugin). E um projeto qualquer, tipo uma aplicação web com banco de dados.

Passo 1: Crie o arquivo docker-compose.yml

Na raiz do seu projeto, crie um arquivo chamado docker-compose.yml. A indentação é sagrada no YAML, use dois espaços, nunca TAB. Um erro comum é pular a indentação e o Compose reclamar de sintaxe. Comece com a versão (recomendo '3.8' ou superior, mas hoje o Compose aceita sem declarar versão).

Dica: Use um editor que destaque YAML, como VS Code, para evitar erros de indentação.

Passo 2: Defina os serviços

Dentro do arquivo, escreva services: e, abaixo, nomeie cada serviço. Exemplo para uma aplicação Node.js com MongoDB:

services: app: build: . ports:

• "3000:3000"

depends_on:

• db

db: image: mongo:6 volumes:

• mongodb_data:/data/db

volumes: mongodb_data:

Cada serviço pode usar uma imagem pronta (image:) ou construir a partir de um Dockerfile (build: .). O depends_on garante a ordem de inicialização, mas não espera o serviço ficar pronto, você pode precisar de um script de healthcheck para isso.

Passo 3: Configure redes e volumes

Por padrão, o Compose cria uma rede para os serviços se comunicarem. Se precisar de redes específicas (isolamento, driver personalizado), declare em networks:. Volumes persistentes, como o mongodb_data acima, mantêm os dados mesmo se o contêiner for recriado.

Erro comum: Esquecer de declarar o volume no nível raiz (fora de services). Sem isso, o volume não é criado e os dados somem ao derrubar o container.

Passo 4: Suba o ambiente

No terminal, dentro da pasta do projeto, execute:

docker compose up -d

A flag -d roda em background. Para ver os logs, use docker compose logs -f. Para parar tudo: docker compose down. Se mudar o YAML, rode docker compose up -d novamente que ele atualiza só o que mudou.

Checklist do que você fez

• [ ] Arquivo docker-compose.yml criado na raiz do projeto
• [ ] Serviços definidos com imagem ou build
• [ ] Portas mapeadas (quando necessário)
• [ ] Volumes declarados e referenciados
• [ ] Redes configuradas (se aplicável)
• [ ] Ambiente rodando com docker compose up -d

Perguntas frequentes sobre configuração do Docker Compose

Qual a diferença entre docker-compose e docker compose?

docker-compose (com hífen) é a versão antiga, um script Python separado. docker compose (com espaço) é o plugin integrado ao Docker CLI, recomendado hoje. Se você instalou o Docker Desktop, use docker compose.

Preciso declarar a versão no arquivo YAML?

Não é mais obrigatório. O Compose moderno detecta a sintaxe automaticamente. Se declarar, use version: '3.8' ou superior. Versões antigas (como '2') podem limitar recursos.

Como faço para um serviço esperar outro ficar pronto?

depends_on só controla ordem de inicialização, não saúde. Para esperar o banco ficar acessível, use um script de entrypoint no serviço dependente ou configure healthcheck no YAML.

Onde ficam os logs do Docker Compose?

Use docker compose logs <nome-do-servico> no terminal. Para ver todos em tempo real, docker compose logs -f. Os logs não persistem após o container parar a menos que você os redirecione para um arquivo.

Posso usar variáveis de ambiente no docker-compose.yml?

Sim. Crie um arquivo .env na mesma pasta e referencie $VARIAVEL no YAML. O Compose lê automaticamente. Exemplo: ports: - "$PORTA:3000".

O que fazer se o Compose reclamar de sintaxe?

Verifique a indentação (use espaços, não TAB) e se não faltou dois-pontos após chaves como services:. Use um validador YAML online ou a extensão do VS Code para YAML.