O que é Docker Compose

Quase toda aplicação real tem mais de uma peça: um servidor web, um banco de dados, talvez um cache ou uma fila. Subir cada uma com um docker run comprido, lembrando de portas, redes e volumes, vira uma lista de comandos que ninguém consegue repetir sem errar. O Docker Compose existe para trocar essa lista por um arquivo.

Você descreve o que a aplicação precisa em YAML, versiona o arquivo junto com o código e qualquer pessoa da equipe sobe o mesmo ambiente com um comando.

O que o Docker Compose faz, na prática?#

O Compose lê um arquivo que declara os componentes da aplicação e cria tudo o que é necessário para eles funcionarem juntos. Segundo a documentação oficial, o arquivo tem estes elementos de nível superior:

• services: os componentes da aplicação. Cada serviço roda um ou mais containers criados da mesma imagem e configuração.
• networks: as redes que permitem os serviços conversarem entre si.
• volumes: armazenamento persistente, que sobrevive à remoção do container.
• configs e secrets: configuração e dados sensíveis montados nos containers como arquivos.
• name: o nome do projeto, que agrupa os recursos e isola implantações diferentes.

Você não precisa usar todos. A maioria dos arquivos tem só services e volumes.

Como é um arquivo compose.yaml?#

O exemplo abaixo sobe uma aplicação Node.js que fala com um PostgreSQL. O código da aplicação fica na pasta atual, com um Dockerfile.

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s

volumes:
  db-data:

Como ler esse arquivo:

• build: . manda construir a imagem a partir do Dockerfile da pasta. image: postgres:18 usa uma imagem pronta.
• ports: "3000:3000" publica a porta 3000 do container na porta 3000 da sua máquina.
• Dentro da rede criada pelo Compose, um serviço alcança o outro pelo nome. Por isso a URL usa db como host, não localhost.
• ${DB_PASSWORD} é lido do ambiente ou de um arquivo .env na mesma pasta, para a senha não ficar escrita no YAML. Veja o que é um arquivo .env.
• O volume db-data mantém os dados do banco mesmo se o container for recriado.
• $$ no healthcheck escapa o cifrão, para a variável ser resolvida dentro do container e não pelo Compose.

O arquivo não precisa do campo version: no topo. Ele é obsoleto: serve só como informação e gera um aviso se for usado.

Quais comandos você usa no dia a dia?#

Com o arquivo na pasta do projeto, o ciclo básico é este:

docker compose up -d        # cria redes e volumes e sobe os serviços em segundo plano
docker compose ps           # mostra o estado de cada serviço
docker compose logs -f web  # acompanha os logs do serviço web
docker compose down         # para e remove os containers e a rede

O down mantém os volumes. Para apagar também os dados, use docker compose down -v, com cuidado. O comando é docker compose (com espaço), um subcomando do Docker. A forma antiga docker-compose (com hífen) ainda aparece em tutoriais velhos, e os nomes de arquivo docker-compose.yml continuam aceitos.

Se você alterar o código e quiser reconstruir a imagem, rode docker compose up -d --build. Como o Compose guarda a configuração de cada container, serviços que não mudaram são reaproveitados.

O depends_on espera o banco ficar pronto?#

Por padrão, não. O depends_on só garante a ordem: o Compose espera o container do banco estar em execução, não pronto para aceitar conexões. Um PostgreSQL pode levar alguns segundos para inicializar, e a aplicação que sobe antes dele costuma falhar com erro de conexão.

A solução é declarar um healthcheck no banco e usar condition: service_healthy no depends_on, como no exemplo acima. Assim o Compose segura o serviço web até o teste do banco passar. Mesmo assim, uma boa aplicação tenta reconectar sozinha, porque o banco pode cair depois.

Para que o Docker Compose serve?#

A documentação oficial destaca três usos:

1. Ambiente de desenvolvimento: banco, cache, fila e APIs de que o projeto depende sobem com um comando, iguais para toda a equipe.
2. Testes automatizados: o pipeline de CI cria um ambiente isolado, roda a suíte e destrói tudo no final.
3. Deploy em um único servidor: o Compose pode implantar em um host ou em um host Docker remoto, com configurações próprias de produção.

Para diferenciar ambientes, dá para combinar vários arquivos (por exemplo, um base e um de produção) ou usar variáveis, que deixam uma mesma configuração servir para pessoas e ambientes diferentes.

Quando o Compose não basta?#

O Compose trabalha com um host. Ele não distribui containers entre vários servidores, não move uma carga para outra máquina se o servidor cair e não ajusta o número de réplicas conforme a demanda. Se você precisa disso, o caminho é um orquestrador de cluster, como o Kubernetes, que também é bem mais complexo de operar.

O Compose descreve containers, não a segurança do servidor. Portas publicadas, senhas em texto no YAML e imagens sem versão fixa (latest) são problemas comuns. Fixe a versão das imagens, mantenha segredos fora do repositório e publique só as portas que precisam ser acessadas de fora.

Que termos costumam ser confundidos com Compose?#

• Dockerfile: receita para construir uma imagem. O Compose a usa em build, mas não a substitui. Para escrever uma, veja como containerizar uma aplicação.
• Docker: o motor que executa os containers. Veja o que é Docker.
• Imagem e container: a imagem é o modelo imutável, o container é uma instância em execução dela.
• Kubernetes e Swarm: orquestradores de cluster, para vários hosts.