Cheat Sheet do Docker Compose - Comandos mais úteis com exemplos

Aqui está uma Guia de referência do Docker Compose com exemplos anotados para ajudar você a dominar arquivos e comandos do Compose rapidamente.

Este guia faz parte de Ferramentas de Desenvolvimento: O Guia Completo para Fluxos de Trabalho Modernos.

Pré-requisitos

O Docker Engine deve estar instalado antes de usar o Compose. No Ubuntu, siga Instalar Docker no Ubuntu para escolher o método de instalação adequado e configurar o plugin docker compose.

Referência do Arquivo Compose: docker-compose.yml

Estrutura principal:

version: '3'       # Versão do formato do arquivo Compose

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"   # Porta do host 8080: Porta do container 80
  db:
    image: postgres
    environment:            # Variáveis de ambiente
      POSTGRES_PASSWORD: example
    volumes:
      - db_data:/var/lib/postgresql/data

networks:          # Rede personalizada
  appnet:
    driver: bridge

volumes:           # Volume nomeado
  db_data:

• services: Cada container em seu aplicativo multi-container. No exemplo acima, temos dois serviços: web e db. Para operações de container individual, consulte o Guia de Referência do Docker.
• networks & volumes: Defina redes isoladas e armazenamento persistente - temos a rede appnet e o volume db_data aqui.

Exemplos

Serviço único com mapeamento de porta

services:
  app:
    build: .
    ports:
      - "8000:80"   # Porta do host 8000: Porta do container 80

Expõe o aplicativo na porta 8000 do host e constrói a partir do Dockerfile no diretório atual.

Multi-serviço com volume compartilhado e rede personalizada

version: '3'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - type: bind
        source: ./app
        target: /app
    networks:
      - mynet
  db:
    image: postgres
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - mynet

networks:
  mynet:

volumes:
  db_data:

Web e DB na mesma rede; DB usa volume nomeado persistente - db_data.

Usando contexto de build e caminho do Dockerfile

Você pode construir imagem docker sob demanda a partir do Dockerfile especificado no docker-compose.yml.

services:
  app:
    build:
      context: .
      dockerfile: docker/MyDockerfile

Compartilhando dados entre serviços

services:
  web:
    image: nginx
    volumes:
      - shared_data:/usr/share/nginx/html
  worker:
    image: myworker
    volumes:
      - shared_data:/usr/src/app/data

volumes:
  shared_data:

Ambos os serviços acessam o mesmo volume (para arquivos estáticos ou trocas de dados) - shared_data.

Opções Avançadas do Arquivo Compose

• environment: Defina variáveis ENV para containers.
• depends_on: Controle a ordem de inicialização dos serviços.
• deploy.replicas: Escalone o serviço no modo Swarm.

Exemplo:

services:
  web:
    image: nginx
    deploy:
      replicas: 3
    depends_on:
      - db

Inicia 3 instâncias web; controla apenas a ordem de inicialização (não a prontidão).

Comandos Essenciais do Docker Compose

Padrões Comuns do Compose

• Bancos de dados com dados persistentes

  services:
    mysql:
      image: mysql
      environment:
        MYSQL_ROOT_PASSWORD: password
      volumes:
        - mysql_data:/var/lib/mysql
  
  volumes:
    mysql_data:
  

  Os dados do DB persistem no volume mysql_data entre reinicializações de container.

• Montagem de bind de código para desenvolvimento

  services:
    app:
      build: .
      volumes:
        - .:/app
  

  Edite código em tempo real no host, refletido automaticamente no container.

Flags Úteis

• -d: Modo detach (executar em segundo plano).
• --build: Força reconstrução de imagens antes de iniciar.
• --force-recreate: Recria containers mesmo se não houver mudanças.
• --remove-orphans: Remove containers não definidos no arquivo Compose.

Definindo e Personalizando Serviços

Você pode definir e personalizar serviços, redes e volumes no Docker Compose aproveitando o arquivo docker-compose.yml, que centraliza todas as necessidades de configuração e orquestração do seu aplicativo.

• Serviços são definidos sob a chave services.
• Cada serviço representa uma configuração de container, onde você pode definir:
  • Image: Selecione uma imagem do Docker Hub ou outro registro.
  • Ports: Mapeie portas do container para portas do host.
  • Environment variables: Passe valores de configuração.
  • Volumes: Persista dados ou compartilhe arquivos/pastas com o host ou outros serviços.
  • Networks: Controle quais redes o serviço pode acessar.

Exemplo:

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"   # Porta do host 8080: Porta do container 80
    environment:
      - NGINX_HOST=localhost
    volumes:
      - web_data:/usr/share/nginx/html
    networks:
      - frontend

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

• Aqui, o serviço web usa a imagem nginx, define uma variável de ambiente, anexa um volume, abre a porta 80 como 8080 no host e conecta-se à rede frontend. O serviço db faz algo similar para o PostgreSQL.

Personalizando Redes

• Redes controlam quais serviços podem se comunicar. O Compose cria uma rede padrão, mas você pode definir mais, especificar drivers personalizados, definir opções e determinar qual serviço entra em qual rede para isolamento fino.
• Defina redes no nível superior sob networks, e liste quais redes um serviço deve anexar com a chave networks no nível do serviço.

Exemplo:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"

• Anexe redes aos serviços:

services:
  app:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

• Esta configuração permite que o serviço app acesse tanto usuários na rede frontend quanto na backend, enquanto db é acessível apenas dentro da backend.

Personalizando Volumes

• Volumes são definidos sob a chave de nível superior volumes. Monte-os em containers usando a chave volumes sob um serviço.
• Volumes podem ser nomeados, usar drivers personalizados e ser compartilhados entre múltiplos serviços para persistência e compartilhamento de dados.

Exemplo:

volumes:
  web_data:                # Volume nomeado para conteúdo web
  db_data:                 # Volume nomeado para banco de dados

services:
  web:
    volumes:
      - web_data:/usr/share/nginx/html

  db:
    volumes:
      - db_data:/var/lib/postgresql/data

• Neste exemplo, web_data é persistente e disponível para qualquer container que o montar. db_data garante que os dados do banco de dados nunca sejam perdidos na recriação do container.
• Você pode definir bind-mounts com opções de driver personalizadas para casos avançados:

volumes:
  db_data:
    driver: local
    driver_opts:
      type: none
      device: /data/db_data
      o: bind

• Esta configuração define um bind-mount do caminho do host /data/db_data para o container.

Resumo das Melhores Práticas:

• Use o nome do serviço como nome de host DNS para comunicação entre serviços.
• Anexe serviços a múltiplas redes conforme necessário para controlar o acesso.
• Use volumes nomeados para armazenamento persistente e compartilhamento de dados.
• Defina tudo usando YAML, permitindo controle de versão e scripts de implantação fáceis.
• Para gerenciamento e visualização de containers, considere Instalar Portainer no Linux.

Múltiplos arquivos Compose

Para organizar configurações complexas multi-serviço no Docker Compose, você pode usar múltiplos arquivos Compose e arquivos de sobrescrita (override), permitindo configurações modulares, específicas por ambiente e escaláveis. Veja como isso funciona:

1. Estrutura de Arquivo Base e de Sobrescrita

• Crie um arquivo base (compose.yaml ou docker-compose.yml) contendo todas as definições de serviço comuns e padrão.
• Adicione arquivos de sobrescrita específicos do ambiente (por exemplo, docker-compose.override.yml, docker-compose.dev.yml, docker-compose.prod.yml).

Exemplo de estrutura de arquivos:

/diretorio-do-projeto
|-- docker-compose.yml           # Configuração base
|-- docker-compose.override.yml  # Sobrescritas locais/dev (aplicadas automaticamente)
|-- docker-compose.prod.yml      # Sobrescritas de produção
|-- docker-compose.test.yml      # Sobrescritas de teste (se necessário)

A configuração base define serviços principais, enquanto cada sobrescrita personaliza configurações para um ambiente ou caso específico.

2. Como as Sobrescritas de Arquivo Funcionam

• Mesclagem: Quando você executa docker compose up, o Docker Compose mescla o base com quaisquer sobrescritas em ordem; arquivos subsequentes sobrescrevem, estendem ou adicionam configurações em arquivos anteriores.
• Sobrescrevendo Campos: Se um serviço ou campo for definido em múltiplos arquivos, o valor do arquivo especificado por último é usado. Novos campos são adicionados.

Exemplo de mesclagem:

• docker-compose.yml:

  services:
    web:
      image: myapp
      ports:
        - "8000:80"
  

• docker-compose.override.yml:

  services:
    web:
      environment:
        - DEBUG=true
  

• Resultado: O serviço web usa tanto a imagem e a porta base quanto a variável de ambiente DEBUG sobrescrita.

3. Uso de Comandos para Múltiplos Arquivos

• Comportamento padrão: Se presente, o Docker Compose carrega automaticamente docker-compose.override.yml junto com docker-compose.yml quando você executa qualquer comando.
• Especificando arquivos manualmente: Use flags -f para controlar quais arquivos são mesclados e em qual ordem:

  docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
  

  • Isso ignora a sobrescrita padrão e usa as configurações específicas de produção.

4. Estratégias Práticas de Organização

• Separação de ambientes: Use uma sobrescrita por ambiente: dev, test, prod, etc.
• Microsserviços e equipes: Divida a configuração em arquivos separados para diferentes serviços ou equipes, e combine conforme necessário.
• Alternativas de recursos (Feature toggles): Arquivos adicionais podem introduzir ou remover serviços opcionais ou configurações para necessidades temporárias (por exemplo, um compose.debug.yml para logs extras).

5. Benefícios

• Clareza: Mantém arquivos individuais pequenos e focados.
• Escalabilidade: Adicione facilmente novos serviços, ambientes ou configurações.
• Manutenibilidade: Altere ou revise apenas seções relevantes para uma determinada implantação.

6. Exemplo: Alternando Ambientes

Desenvolvimento:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

Produção:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Cada ambiente recebe apenas a configuração necessária para ele, com toda configuração compartilhada no arquivo base.

Organizar configurações Compose complexas com múltiplos arquivos - e aproveitar o sistema de sobrescrita/mesclagem - garante modularidade, personalização específica de ambiente e escalabilidade fácil para aplicativos Docker grandes e multi-serviço.

Para implantação em produção em um único host Linux — inicialização na partida, encerramento limpo, atualizações e rotação de logs — veja Executar Docker Compose como Serviço Linux com systemd.

Links Úteis

• https://docs.docker.com/compose/
• Guia de Referência do Docker
• Guia de Referência do Kubernetes
• Dockerizando aplicativo Web Flutter com build Flutter dockerizado e Nginx
• Instalar Portainer no Linux