Comandos essenciais do Docker Compose: tutorial completo

Execute todos os comandos docker compose na pasta onde está compose.yaml (ou em uma subpasta), ou especifique o arquivo com -f. Você pode informar um serviço após o comando para operar somente nele; sem um serviço, o comando se aplica ao projeto inteiro. Os exemplos desta seção usam o projeto compose-demo do tutorial Introdução ao Compose.

Iniciar e parar

Veja a saída real de up, stop, start e down em Introdução ao Compose.

Consultar o status

$ docker compose ps
NAME                     IMAGE               COMMAND                  SERVICE   CREATED          STATUS         PORTS
compose-demo-adminer-1   adminer             "entrypoint.sh docke…"   adminer   10 seconds ago   Up 9 seconds   0.0.0.0:8081->8080/tcp, [::]:8081->8080/tcp
compose-demo-db-1        postgres:18         "docker-entrypoint.s…"   db        10 seconds ago   Up 9 seconds   5432/tcp
compose-demo-web-1       nginx:1.30-alpine   "/docker-entrypoint.…"   web       10 seconds ago   Up 8 seconds   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

$ docker compose ls
NAME                STATUS              CONFIG FILES
compose-demo        running(3)          /work/compose-demo/compose.yaml

$ docker compose images
CONTAINER                REPOSITORY          TAG                 PLATFORM            IMAGE ID            SIZE                CREATED
compose-demo-adminer-1   adminer             latest              linux/amd64         74f29c416e14        164MB               2 weeks ago
compose-demo-db-1        postgres            18                  linux/amd64         74935e722416        644MB               6 days ago
compose-demo-web-1       nginx               1.30-alpine         linux/amd64         0985e772fb9f        92.8MB              2 weeks ago

$ docker compose top web
SERVICE  #   PID    USER  TIME  COMMAND
web      1   21356  root  0:00  nginx: master process nginx -g daemon off;
web      1   21425  101   0:00  nginx: worker process

Consultar os logs

$ docker compose logs --tail 2 -t web
web-1  | 2026-10-13T00:18:19.618825771Z 2026/10/13 00:18:19 [notice] 1#1: start worker processes
web-1  | 2026-10-13T00:18:19.619080382Z 2026/10/13 00:18:19 [notice] 1#1: start worker process 30

docker compose logs               # todos os serviços
docker compose logs -f app        # acompanhar app continuamente
docker compose logs --tail 50 -t  # últimas 50 linhas, com horário

Executar comandos em um serviço

exec: dentro de um contêiner em execução

$ docker compose exec web nginx -v
nginx version: nginx/1.30.5

$ docker compose exec db psql -U postgres -c "SELECT now();"
              now
-------------------------------
 2026-10-13 00:18:28.618314+00
(1 row)


$ docker compose exec -T db pg_dump -U postgres postgres > backup.sql && wc -l backup.sql
27 backup.sql

$ rm backup.sql

• Use o nome do serviço (web, db) para especificar o contêiner; você não precisa saber o nome real do contêiner.
• -T desativa o terminal virtual. Ao redirecionar a saída para um arquivo (por exemplo, pg_dump > backup.sql, acima) ou usar o comando em um script, sempre adicione essa opção; caso contrário, a saída pode incluir caracteres de controle do terminal.
• docker compose exec web sh abre um shell interativo.

run: inicie um novo contêiner descartável

$ docker compose run --rm web nginx -t
Container compose-demo-web-run-80040d25219f Creating
Container compose-demo-web-run-80040d25219f Created
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

run usa a configuração do serviço (imagem, variáveis de ambiente, Volume, rede) para criar um novo contêiner e executar o comando (com o nome compose-demo-web-run-…); --rm o remove automaticamente quando termina. Acima, usamos esse comando para verificar a configuração do nginx (nginx -t) sem afetar o serviço em execução.

Depois de alterar a configuração: restart não basta; use up -d

Este é o mal-entendido mais comum. Experimente: adicione a variável de ambiente SITE_TITLE: v2 ao serviço web em compose.yaml e teste restart e up -d separadamente:

$ docker compose --progress plain restart web
 Container compose-demo-web-1 Restarting
 Container compose-demo-web-1 Started

$ docker compose exec web sh -c "echo SITE_TITLE=\$SITE_TITLE"
SITE_TITLE=

$ docker compose up -d
[+] up 3/3
 ✔ Container compose-demo-db-1      Running                                                     0.0s
 ✔ Container compose-demo-adminer-1 Running                                                     0.0s
 ✔ Container compose-demo-web-1     Started                                                     0.4s

$ docker compose exec web sh -c "echo SITE_TITLE=\$SITE_TITLE"
SITE_TITLE=v2

• restart apenas para e inicia novamente o contêiner existente. Como a configuração do contêiner é definida quando ele é criado, a nova variável de ambiente não aparece (SITE_TITLE= fica vazio).
• up -d compara compose.yaml com os contêineres existentes. Ao detectar uma alteração na configuração de web, ele recria web (Started); db e adminer, que não mudaram, permanecem como estão (Running).

Depois de alterar compose.yaml ou .env, sempre use docker compose up -d.

Build e imagens

docker compose build              # Constrói a imagem de todos os serviços com configuração de build
docker compose build --no-cache app
docker compose pull               # Baixa as imagens mais recentes de todos os serviços
docker compose push               # Envia os serviços que têm um nome de imagem

$ docker compose pull
[+] pull 3/3
 ✔ Image adminer           Pulled                                                               0.7s
 ✔ Image nginx:1.30-alpine Pulled                                                               0.5s
 ✔ Image postgres:18       Pulled                                                               1.3s

Fluxo comum para atualizar serviços que usam imagens prontas:

docker compose pull
docker compose up -d
docker image prune -f   # Remove imagens antigas substituídas

Verificar a configuração

$ docker compose config --services
db
adminer
web

$ docker compose config --volumes
pgdata

$ docker compose port web 80
0.0.0.0:8080

docker compose config             # Exibe a configuração completa após mesclar arquivos e substituir variáveis
docker compose config --services  # Lista os nomes de todos os serviços
docker compose config --volumes   # Lista os Volumes
docker compose port web 80        # Mostra a porta do host correspondente a uma porta do contêiner do serviço

Veja um exemplo da saída completa de docker compose config em sintaxe de compose.yaml.

Outros

docker compose cp web:/etc/nginx/nginx.conf ./nginx.conf   # Copia arquivos
docker compose watch                                       # Detecta alterações nos arquivos durante o desenvolvimento e sincroniza ou reconstrói automaticamente
docker compose up -d --scale worker=3                      # Inicia 3 workers

Opções globais

Essas opções são especificadas entre docker compose e o subcomando:

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose -p myproject up -d          # Define o nome do projeto
docker compose --env-file .env.prod up -d  # Especifica o arquivo .env
docker compose --profile tools up -d       # Ativa o profile
docker compose --progress plain up -d      # Exibe o progresso em texto simples (útil para registros de CI)

Resumo das situações do dia a dia

Resumo

• Depois de alterar compose.yaml ou .env, sempre use docker compose up -d.
• Use exec em um contêiner em execução; run --rm inicia um contêiner descartável.
• Use docker compose config para verificar a configuração final após a mesclagem.
• Veja todas as opções de up e down em docker compose up e docker compose down.

Exercícios

Exercício 1: Altere a porta do host de web em compose.yaml e teste docker compose restart web e docker compose up -d. Qual deles aplica a nova porta?

Exercício 2: Use um contêiner descartável para executar psql --version na rede do serviço db e remova o contêiner automaticamente ao terminar.

docker compose run --rm db psql --version

Atualizado 14 de outubro de 2026