O que é Docker Compose

Docker Compose define e executa aplicações formadas por vários contêineres. Em vez de iniciar cada serviço com comandos separados, você descreve o ambiente em YAML.

A ferramenta nasceu no ecossistema Docker para resolver um problema prático: uma aplicação pode depender de banco, cache, fila, API e frontend ao mesmo tempo.

O arquivo fica versionado no Git e funciona como uma documentação executável do ambiente local.

Como funciona

O arquivo costuma se chamar compose.yaml. Cada serviço recebe imagem, portas, variáveis, volumes e dependências.

Ao executar Docker compose up, o Docker cria a rede do projeto, baixa imagens e inicia os serviços. Eles se encontram pelo nome do serviço.

Volumes mantem dados fora do ciclo de vida do contêiner, algo essencial para bancos e arquivos persistentes.

💡
Dica

Se o banco se chama db, use db como host dentro da rede Compose. localhost aponta para o contêiner atual.

Principais recursos

Serviços isolam cada parte da aplicação e podem usar imagens prontas ou um Dockerfile.

Redes internas permitem que API, banco e workers troquem dados com nomes previsíveis. Portas só precisam ser expostas quando existe necessidade externa.

Volumes, variáveis, perfis e comandos de inicialização completam a descrição do ambiente.

  • Serviços em contêineres.
  • Rede interna por projeto.
  • Volumes para persistência.
  • Variáveis centralizadas.

Como começar: instalação e acesso

Instale o Docker Desktop ou o Docker Engine com o plugin Compose. A sintaxe atual usa o comando com espaço: Docker compose.

Crie uma pasta e salve um arquivo compose.yaml. Depois suba o ambiente em segundo plano:

mkdir compose-exemplo
cd compose-exemplo
Docker compose up -d
Docker compose ps

Use Docker compose logs -f para acompanhar os registros e Docker compose stop para parar sem remover os serviços.

⚠️
Atenção

Docker compose down remove contêineres e a rede. Antes de usar -v, confirme que nenhum volume contem dados importantes.

Exemplo prático com API e PostgreSQL

Uma API pode compartilhar uma rede com PostgreSQL e receber a URL interna do banco por variável de ambiente.

Este exemplo e adequado para desenvolvimento local:

services:
  api:
    image: node:22-alpine
    working_dir: /app
    volumes:
      - .:/app
    command: npm run dev
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      - db
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/PostgreSQL/data
volumes:
  pgdata:

Em produção, retire credenciais do arquivo versionado e trate a prontidão do banco com healthchecks e retry na aplicação.

Comparação com alternativas

Para um único contêiner, Docker run e direto. Mas seus parâmetros ficam difíceis de repetir quando o projeto cresce.

Kubernetes atende clusters, alta disponibilidade e escalabilidade, com uma curva de aprendizado maior.

Podman Compose oferece uma experiência semelhante para equipes que preferem Podman. A escolha depende do runtime e da compatibilidade do projeto.

  • Um contêiner: Docker run.
  • Ambiente local com vários serviços: Docker Compose.
  • Cluster distribuído: Kubernetes.

Pontos positivos e limitações

A vantagem principal e a clareza. O ambiente inteiro fica descrito em um arquivo legível e revisavel.

Também reduz o tempo de preparação: novos integrantes sobem banco, cache e API sem instalar cada dependência no sistema.

A limitação aparece em operações distribuídas com failover, atualizações graduais e vários servidores.

🔴
Cuidado

Compose não e automaticamente uma configuração segura de produção. Revise portas, segredos, imagens, volumes e atualizações.

Casos de uso reais

Desenvolvedores web usam Compose para subir uma API junto com PostgreSQL, Redis ou filas.

Equipes de dados podem reunir ferramentas auxiliares e um banco temporário sem poluir o sistema operacional.

Projetos open source usam o arquivo para reduzir a distancia entre clonar o repositório e executar a primeira funcionalidade.

Em integração continua, Compose cria dependências temporárias para testes e permite limpar o ambiente ao final.

Dicas e boas práticas

Separe configuração comum de configuração específica do ambiente. Perfis evitam iniciar ferramentas de debug por engano.

💡
Dica

Fixe versões de imagens em ambientes compartilhados. A tag latest pode introduzir mudanças inesperadas.

Defina healthchecks quando a aplicação precisa esperar um serviço pronto. Estar em execução não significa aceitar conexões.

🚀
Pro tip

Use Docker compose config para validar a configuração final antes de iniciar o ambiente.

Documente portas, volumes e restauração de backup. Volume não substitui uma copia restaurável.

Vale a pena?

Docker Compose vale a pena para quem precisa reproduzir um ambiente com dois ou mais serviços.

Ele é especialmente útil em desenvolvimento, testes e demonstrações. O arquivo também documenta a topologia do projeto.

Para operação distribuída, avalie uma plataforma de orquestração. O próximo passo e criar um compose.yaml pequeno e observar os logs.