Neste artigo
- O que o Docker Compose resolve
- Seu primeiro docker-compose.yml comentado
- Como a rede interna liga os containers
- Volumes: por que o dado não pode morar no container
- Os comandos do dia a dia
- Healthcheck: quando depends_on não resolve tudo
- Compose na carreira e no pipeline
- Como investigar quando o compose não sobe
- Build versus image: a escolha que acelera a subida
- Qual a diferença entre Docker e Docker Compose?
- Como faço para reconstruir a imagem depois de mudar o código?
- Compose funciona em produção?
- Como vejo o que o container está fazendo quando algo quebra?
- Dependência entre serviços garante que o banco já está pronto?
Docker resolve a sua aplicação; Docker Compose resolve o ambiente inteiro. Em vez de subir container de app, banco e cache na mão, você descreve tudo num arquivo e sobe com um único comando. É a diferença entre um onboarding de horas e um docker compose up que funciona na máquina de qualquer pessoa do time.
Docker Compose define vários serviços num docker-compose.yml, com portas, volumes e redes. Um docker compose up sobe tudo junto. O essencial é entender a hierarquia do arquivo (services → image/build → ports → volumes) e como os containers se acham pela rede interna. Se você nunca usou Docker, comece pelo Docker do zero antes.
O que o Docker Compose resolve
Um projeto real quase nunca é um container só: tem a aplicação, o banco e talvez um cache. Rodar cada um manualmente, com as portas e os volumes certos, é propenso a erro e difícil de explicar para quem entra no time. O Compose declara essa orquestração como código, versiona junto do projeto e reproduz o ambiente em qualquer máquina.
💡 Dica: o arquivo do Compose é a documentação executável do ambiente. Quem clona o repositório e roda docker compose up reproduz o setup sem precisar adivinhar porta, senha ou ordem de inicialização.
Seu primeiro docker-compose.yml comentado
O exemplo abaixo define uma API Node com PostgreSQL e Redis, o trio mais comum em aplicação web. Cada serviço entra na chave services, com a imagem, as portas e os volumes.
services:
api:
build: .
ports:
- "3000:3000"
environment:
DATABASE_URL: postgres://postgres:senha@db:5432/app
depends_on:
- db
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: senha
POSTGRES_DB: app
volumes:
- db_data:/var/lib/postgresql/data
cache:
image: redis:7
volumes:
db_data:
Três pontos fazem o setup funcionar: a build: . constrói a imagem da API a partir do Dockerfile; o depends_on garante a ordem de subida; e o volume db_data persiste o banco entre execuções. A URL usa db:5432 porque dentro da rede o container se chama pelo nome do serviço, não por localhost.
Como a rede interna liga os containers
O erro mais comum de iniciante é achar que a API enxerga o banco como localhost. Dentro do Compose, cada serviço tem o nome da sua chave como hostname interno. A API conecta em db:5432, e o localhost:3000 fica reservado para você, na sua máquina, acessar a aplicação de fora.
⚠️ Atenção: trocar db por localhost na URL do banco é o erro que mais derruba startup de ambiente. Se a API não conecta, o primeiro suspeito é o hostname interno do serviço.
Volumes: por que o dado não pode morar no container
Container é descartável, então dado que precisa sobreviver tem de viver num volume. No exemplo, o volume db_data guarda os arquivos do PostgreSQL fora do container. Quando você derruba e sobe de novo, o banco mantém as tabelas. Sem volume, cada down apaga tudo e o ambiente volta do zero.
Os comandos do dia a dia
docker compose up -d # sobe em segundo plano
docker compose ps # vê o status dos serviços
docker compose logs -f api # acompanha o log da API
docker compose down # derruba, preservando volumes
docker compose down -v # derruba e apaga volumes (dados!)
O -d solta o terminal, o ps mostra o que está de pé e o logs é a investigação padrão. O down -v merece respeito: apaga o volume e os dados junto. Reserve para quando a reinicialização limpa é o objetivo, nunca para o dia a dia.
Healthcheck: quando depends_on não resolve tudo
O depends_on ordena a subida, mas não garante que o banco está pronto para aceitar conexão quando a API tenta. O healthcheck resolve isso: ele roda uma verificação dentro do container e só considera o serviço saudável quando a checagem passa. Você pode então condicionar a API a só subir depois do banco saudável.
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: senha
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 3s
retries: 5
api:
build: .
depends_on:
db:
condition: service_healthy
O condition: service_healthy é o detalhe que muda o comportamento: a API espera o banco ficar saudável em vez de subir às cegas. Em ambiente local o problema costuma aparecer como "conexão negada" no primeiro boot, e o healthcheck o elimina na fonte.
ℹ️ Info: o healthcheck é a ponte entre o depends_on básico e um ambiente que sobe na primeira tentativa. Faça a checagem com um comando que o seu banco já traz pronto, como o pg_isready, em vez de inventar teste manual.
Compose na carreira e no pipeline
Dominar Compose é pré-requisito silencioso em vaga de backend e DevOps, porque é a forma padrão de rodar ambiente de desenvolvimento e stack de apoio. O mesmo conceito de orquestrar serviços vira, em escala maior, o mundo de Kubernetes, com caminho de certificação no bootcamp de Docker e Kubernetes da Microsoft.
O ambiente que o Compose sobe é também o alvo natural da sua esteira: ela constrói a imagem, roda os testes em container e publica a versão. Isso fecha o ciclo com o guia de CI/CD, transformando o docker compose up que você roda na máquina no mesmo ambiente que o pipeline valida.
Como investigar quando o compose não sobe
Ambiente que não sobe tem três suspeitos na maioria das vezes: porta já usada, banco ainda não pronto e erro de digitação no YAML. O caminho de investigação é olhar o status, depois o log do serviço com problema, e só então entrar no container para inspecionar o ambiente interno.
docker compose up -d # sobe e mostra o erro se houver
docker compose ps # qual serviço está parado
docker compose logs db # log do serviço de banco
docker compose exec db sh -c "pg_isready" # checa o banco por dentro
O erro de porta aparece logo no up, com mensagem de bind falhado. O de banco não pronto aparece como conexão negada da API, resolvido com healthcheck. Já o erro de YAML falha antes mesmo de subir, e o próprio compose aponta a linha. Resolva nessa ordem, do sintoma externo para o interno.
💡 Dica: mude só uma coisa por tentativa. Alterar porta, rede e volume ao mesmo tempo esconde a causa raiz. Faça um ajuste, tente de novo e observe o que mudou.
Build versus image: a escolha que acelera a subida
Num serviço, você usa build quando a imagem vem de um Dockerfile seu, ou image quando usa uma imagem pronta do registro. No exemplo, a API usa build e o banco usa a imagem oficial do PostgreSQL. Misturar muitos builds deixa o up lento, porque reconstrói o que não mudou.
services:
api:
build: . # constrói a partir do Dockerfile local
cache:
image: redis:7 # puxa a imagem pronta do registro
A regra prática: código seu, você constrói; infraestrutura de terceiro, você puxa pronto. Essa separação deixa o ambiente fiel ao que o projeto realmente é e evita rebuild desnecessário a cada subida. Para mudança frequente de código, combine com cache de build e volume de desenvolvimento.
Perguntas frequentes
Qual a diferença entre Docker e Docker Compose?
Docker roda container individual; Compose orquestra vários de uma vez a partir de um arquivo. Um complementa o outro: o Compose usa o Docker por baixo, mas cuida da subida, das redes e dos volumes do conjunto.
Como faço para reconstruir a imagem depois de mudar o código?
Rode docker compose up -d --build. Ele reconstrói a imagem do serviço e sobe o conjunto atualizado. Para mudança só de código em volume de desenvolvimento, o reinício costuma bastar.
Compose funciona em produção?
Funciona para ambientes únicos e projetos menores, mas em escala maior a orquestração é feita com plataformas mais robustas, como Kubernetes. Use o Compose para desenvolvimento e setups simples, e escale com a ferramenta adequada.
Como vejo o que o container está fazendo quando algo quebra?
Siga três passos: docker compose ps para o status, docker compose logs -f servico para o log, e o docker compose exec servico sh para entrar e investigar por dentro.
Dependência entre serviços garante que o banco já está pronto?
Não totalmente. O depends_on ordena a subida, mas o banco pode demorar a aceitar conexão. Em produção, adicione retry de conexão na aplicação para tolerar esse intervalo.