# Docker Compose configuracao: guia passo a passo completo

> Docker Compose é uma ferramenta para definir e executar aplicações multi-contêiner Docker. O guia passo a passo completo ensina a criar o arquivo docker-compose.yml, configurar serviços como bancos de dados e aplicações web, e iniciar o ambiente com um único comando. O processo simplifica a orquestração de contêineres para desenvolvimento e produção.

*Digitorack · Apps e Software · 20 de julho de 2026 · Letícia Sampaio Khoury*

Montar um ambiente com Docker Compose é mais simples do que parece. Neste guia, mostro o passo a passo para criar seu primeiro arquivo docker-compose.yml, definir serviços e subir tudo com um comando.

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 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.

---

Fonte (canonical): https://digitorack.com.br/apps-e-software/docker-compose-configuracao-guia-passo-a-passo-completo/