Guia Rápido do Docker Compose – Os comandos mais úteis com exemplos

Aqui está um Docker Compose cheatsheet com exemplos anotados para ajudar você a dominar rapidamente arquivos e comandos do Compose.

Este guia faz parte de Developer Tools: The Complete Guide to Modern Development Workflows.

Pré-requisitos

O Docker Engine deve estar instalado antes de usar o Compose. No Ubuntu, siga Install Docker on 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 básica:

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

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"   # Porta do host 8080:Porta do contêiner 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 com nome
  db_data:

• services: Cada contêiner no seu aplicativo multi-contêiner. No exemplo acima, temos dois serviços: web e db. Para operações individuais de contêineres, veja o Docker Cheatsheet.
• networks & volumes: Define redes isoladas e armazenamento persistente - aqui temos a rede appnet e o volume db_data.

Exemplos

Serviço único com mapeamento de porta

services:
  app:
    build: .
    ports:
      - "8000:80"   # Porta do host 8000:Porta do contêiner 80

Exibe 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 build docker image 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: Define variáveis ENV para contêineres.
• depends_on: Controla a ordem de inicialização dos serviços.
• deploy.replicas: Escala o serviço em 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 o estado de prontidão).

Comandos Essenciais do Docker Compose

Padrões Comuns de 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 banco persistem no volume mysql_data entre reinicializações do contêiner.

• Montagem de bind do código para desenvolvimento

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

  Edite o código ao vivo no host, refletido automaticamente no contêiner.

Flags Úteis

• -d: Modo detach (executar em segundo plano).
• --build: Força a reconstrução das imagens antes de iniciar.
• --force-recreate: Recria contêineres mesmo se não houver mudanças.
• --remove-orphans: Remove contêineres 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 suas necessidades de configuração e orquestração da aplicação.

• Os Serviços são definidos sob a chave services.
• Cada serviço representa uma configuração de contêiner, onde você pode definir:
  • Image: Selecione uma imagem do Docker Hub ou outro registro.
  • Ports: Mapeie portas do contêiner 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 a quais redes o serviço pode acessar.

Exemplo:

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"   # Porta do host 8080:Porta do contêiner 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 à rede frontend. O serviço db faz algo semelhante para PostgreSQL.

Personalizando Redes

• As Networks 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 se junta a qual rede para isolamento fino.
• Defina redes no nível superior sob networks e liste quais redes um serviço deve anexar usando 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 nas redes frontend e backend, enquanto db é acessível apenas dentro da backend.

Personalizando Volumes

• Os Volumes são definidos sob a chave de nível superior volumes. Monte-os em contêineres usando a chave volumes sob um serviço.
• Volumes podem ter nomes, 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 é persistido e disponível para qualquer contêiner que o monte. db_data garante que os dados do banco de dados nunca sejam perdidos na recriação do contêiner.
• 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 dentro do contêiner.

Resumo das Boas 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 contêineres, considere Install Portainer on Linux.

Vários arquivos compose

Para organizar configurações complexas multi-serviço no Docker Compose, você pode usar vários arquivos compose e arquivos de substituição, permitindo configurações modulares, específicas de ambiente e escaláveis. Veja como isso funciona:

1. Estrutura de Arquivo Base e de Substituição

• Crie um arquivo base (compose.yaml ou docker-compose.yml) contendo todas as definições padrão comuns dos serviços.
• Adicione arquivos de substituição específicos de 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  # Substituições locais/dev (aplicadas automaticamente)
|-- docker-compose.prod.yml      # Substituições de produção
|-- docker-compose.test.yml      # Substituições de teste (se necessário)

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

2. Como Funcionam as Substituições de Arquivos

• Mesclagem: Quando você executa docker compose up, o Docker Compose mescla a base com qualquer substituição na ordem; arquivos subsequentes substituem, estendem ou adicionam configurações dos arquivos anteriores.
• Substituição de Campos: Se um serviço ou campo for definido em múltiplos arquivos, o valor do arquivo especificado por último será 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 porta da base quanto a variável de ambiente DEBUG substituída.

3. Uso de Comandos para Vários 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 que ordem:

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

  • Isso ignora a substituição 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 substituição 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.
• Interruptores de funcionalidade: Arquivos adicionais podem introduzir ou remover serviços ou configurações opcionais para necessidades temporárias (por exemplo, um compose.debug.yml para logs extras).

5. Benefícios

• Clareza: Mantém os arquivos individuais pequenos e focados.
• Escalabilidade: Fácil adicionar novos serviços, ambientes ou configurações.
• Manutabilidade: Altere ou revise apenas as 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 todas as configurações compartilhadas no arquivo base.

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

Para implantação de produção em um único host Linux — inicialização na startup, desligamento limpo, atualizações e rotação de logs — veja Run Docker Compose as a Linux Service with systemd. Para uma comparação com Podman Quadlet, veja Podman Quadlet vs Docker Compose for Linux Services.

Links úteis

• https://docs.docker.com/compose/
• Docker Cheatsheet
• Kubernetes Cheatsheet
• Dockerising Flutter Web app with dockerised Flutter build and Nginx
• Install Portainer on Linux
• Backup and Restore Gitea server