<\> Casa do Dev
Notícias abrir
Ferramentas abrir
Vagas abrir
Aprender abrir
Comunidade abrir
Guia de Compras abrir

Docker Compose do zero: suba um ambiente completo com um comando

DA

8 min

Docker Compose do zero: suba um ambiente completo com um comando

Aprenda Docker Compose do zero: aplicação, banco e cache juntos com um comando, com volumes, redes e o YAML comentado.

Neste artigo

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.

O que você achou deste artigo?

Responda a Pergunta do Dia Teste seu conhecimento e mantenha sua streak. Crie seu Dev Card público Perfil dev compartilhável em um único link.

Depois dessa formação...

Veja vagas de cloud e DevOps →

Vagas relacionadas

Ver todas as vagas →
DA

Escrito por

Dagmar

Atualizado em 06/10/2026 •

Ver perfil do autor

COMPARTILHAR