Docker Compose: comandos essenciais para servidores

Os comandos do Compose que realmente utiliza

O Docker Compose disponibiliza mais de quarenta subcomandos. No trabalho diário num servidor, utiliza-se cerca de uma dúzia. Esta página agrupa-os pela tarefa que está a executar, apresenta uma razão simples para cada um e aponta para a explicação detalhada quando um comando esconde uma armadilha.

Tudo aqui utiliza o Compose V2: docker compose com um espaço, não o script antigo docker-compose. O V2 é um plugin Go instalado com o Docker Engine, e o V1 deixou de estar disponível nos pacotes atuais. Por isso, um docker-compose: command not found numa instalação nova do Ubuntu em julho de 2026 é esperado e não indica uma falha. Confirme com docker compose version. Se não apresentar nada, instale o pacote docker-compose-plugin.

Todos os comandos abaixo são executados a partir do diretório que contém o seu compose.yaml, porque o Compose obtém o nome do projeto a partir desse diretório e procura o ficheiro relativamente a ele. Se executar o mesmo comando um nível acima, o Compose termina com no configuration file provided: not found. Se o formato do ficheiro ainda lhe for desconhecido, comece por um primeiro ficheiro Compose num VPS e volte aqui para consultar os comandos.

Ciclo de vida: os quatro comandos que utiliza e o que remove os contentores

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d cria a rede, cria os contentores, inicia-os e termina. Termina assim que os contentores são criados. Por isso, um script de implementação que execute uma verificação curl logo depois falha frequentemente na primeira tentativa. up -d --wait bloqueia até que todos os serviços que declaram uma verificação de integridade indiquem um estado saudável. Termina com um código diferente de zero se algum serviço nunca chegar a esse estado. A opção só é tão fiável quanto a verificação que executa. Por isso, escreva uma verificação de integridade em que o Compose possa confiar antes de depender dela na automação.

stop para os contentores e mantém-nos. Assim, start inicia novamente os mesmos contentores com a mesma camada gravável. down para os contentores e depois remove-os, juntamente com a rede do projeto. Tudo o que foi escrito dentro do contentor e fora de um volume é eliminado. Este é o erro de interpretação mais dispendioso no Compose. A diferença completa entre down e stop explica onde esse comportamento causa problemas.

restart não é uma recarga. Para e inicia novamente o mesmo contentor com a configuração que este já possui. Por isso, uma variável de ambiente alterada, uma nova tag de imagem ou um mapeamento de portas editado não têm qualquer efeito. Para aplicar uma alteração no ficheiro, execute up -d novamente. O Compose compara cada serviço com o contentor em execução e recria apenas os contentores cuja configuração foi alterada.

Aplicar uma alteração: recriar, obter ou reconstruir

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -d isoladamente não faz nada quando não há alterações, o que permite executá-lo repetidamente com segurança. --force-recreate ignora essa comparação e substitui todos os contentores mesmo quando a configuração é idêntica, sendo a forma mais rápida de eliminar um estado anómalo dentro do contentor.

A atualização de uma imagem requer dois comandos porque cada um executa uma tarefa diferente. pull transfere a imagem atual para cada tag indicada no ficheiro. Em seguida, up -d deteta que o ID da imagem do serviço já não corresponde ao do contentor em execução e recria-o. Se ignorar o pull, up -d mantém o latest do mês passado em execução sem apresentar um erro.

build aplica-se a serviços que declaram uma secção build: em vez de uma image:. up -d --build compila e inicia numa única etapa, que é o ciclo normal enquanto altera o código. Use --no-cache apenas quando uma camada em cache estiver claramente desatualizada, porque este comando reconstrói todas as camadas de raiz.

O que está em execução

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps lista apenas os containers em execução. Um serviço que falhou durante o arranque fica invisível até adicionar -a. Por isso, um container ausente em ps enquanto ps -a o mostra como Exited (1) é o comportamento normal de uma falha de arranque. Leia o código de saída e, em seguida, leia os logs.

logs -f acompanha todos os serviços em simultâneo e acrescenta o nome do serviço no início de cada linha. Esta é a vista adequada quando os serviços comunicam entre si e a ordem dos eventos é importante. Indique um serviço para limitar a saída. --tail=100 é importante num container que está em execução há um mês, porque o comportamento predefinido apresenta todo o histórico e enche o terminal. --since 15m responde à pergunta mais comum: o que aconteceu durante o reinício que acabou de fazer.

top lista os processos dentro de cada container. Isto permite distinguir entre "o container está em execução" e "o processo dentro dele está em execução". ls sai do diretório atual e lista todos os projetos Compose no host, com o respetivo estado. Assim, pode encontrar a stack que iniciou há três meses.

Obtendo um shell dentro de um serviço

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec executa um comando dentro de um container que já está em execução. run inicia um novo container a partir da mesma definição de serviço. É disso que precisa quando o serviço não permanece em execução tempo suficiente para permitir o uso de exec. Associe sempre run a --rm. Sem essa opção, cada execução deixa um container parado, e esses containers acumulam-se até docker compose ps -a ficar ilegível.

Experimente sh antes de bash. As imagens baseadas em Alpine não incluem bash, e a falha apresenta exec: "bash": executable file not found in $PATH. Adicionar --no-deps a run ignora as dependências do serviço. Assim, uma verificação rápida da configuração não inicia toda a sua base de dados.

run --rm web env é a forma mais rápida de ver o ambiente que um serviço recebeu efetivamente, depois de todos os ficheiros .env, blocos environment: e variáveis de shell terem sido combinados. Quando um valor está errado, a ordem de combinação costuma ser a causa. como o Compose resolve ficheiros env e secrets explica qual origem tem precedência.

Redes, portas e resolução de nomes

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

O Compose coloca todos os serviços numa única rede do projeto, e o nome de cada serviço funciona como um nome DNS nessa rede. Executar getent hosts db dentro de web mostra o IP do contentor quando a resolução funciona e não mostra nada quando falha. Assim, é possível verificar em dois segundos se "estes contentores conseguem comunicar entre si". Se o nome for resolvido mas a ligação for recusada, o processo dentro de db está associado a 127.0.0.1 em vez de 0.0.0.0. Por isso, nunca aceita pacotes de outro contentor. O restante modelo está em como funcionam as redes do Compose e o DNS dos serviços.

port web 80 mostra o endereço e a porta do host em que uma porta do contentor está publicada. Isto evita ter de adivinhar quando o mapeamento veio de uma variável. A publicação de uma porta também cria uma regra de firewall que o Docker gere internamente. Essa regra fica à frente das suas regras. Por isso, um serviço que julgava privado pode ficar acessível pela Internet. Esse caso é explicado em por que as portas Docker publicadas ignoram o ufw.

Volumes e dados

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes imprime os volumes nomeados declarados pelo projeto, um por linha. Essa lista é o que deve ser incluído no backup. cp copia um ficheiro para dentro ou para fora de um contentor sem abrir uma shell, usando o formato service:path no lado em que está o contentor.

down -v remove esses volumes nomeados juntamente com os contentores. É o comando adequado para desmontar uma stack de teste e o comando errado para qualquer stack que contenha dados importantes, porque não pede confirmação e não existe forma de anular a operação. Os bind mounts sobrevivem, porque estão no sistema de ficheiros do host. Essa diferença no impacto é uma das razões para escolher deliberadamente entre bind mounts e volumes nomeados.

Limpeza que libera espaço em disco sem perder dados

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans exclui os containers que pertencem ao projeto, mas que já não aparecem no ficheiro. É exatamente o que acontece depois de mudar o nome de um serviço. Sem esta opção, esses containers continuam a executar, invisíveis para docker compose ps.

docker system df mostra onde o disco foi ocupado antes de eliminar qualquer coisa. Divide o uso entre imagens, containers, volumes locais e cache de compilação, com um valor recuperável para cada categoria. image prune -a remove todas as imagens que não são referenciadas por nenhuma tag. Num servidor que tenha obtido várias versões de uma imagem grande, esta opção costuma produzir o maior ganho. builder prune limpa a cache de compilação, que cresce silenciosamente em qualquer servidor que crie as suas próprias imagens.

Nenhum desses comandos altera um volume nomeado. Apenas docker volume prune e docker compose down -v o fazem.

Verificando o ficheiro antes que cause problemas

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet valida o ficheiro e não imprime nada quando tem sucesso, por isso deve ser usado numa etapa de pré-implantação ou num hook do git. O config simples imprime o ficheiro totalmente combinado e interpolado. É assim que confirma se uma variável foi resolvida e se um ficheiro de substituição foi aplicado pela ordem esperada. Uma variável não definida aparece como um valor vazio, junto do aviso The "X" variable is not set. Defaulting to a blank string.

--dry-run é uma opção global, não uma opção do subcomando, por isso deve ser colocada antes de up. Imprime todas as ações que o Compose executaria e não altera nada. São trinta segundos bem gastos antes de um down numa stack importante.

Trabalhar com ficheiros, perfis e projetos

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Vários sinalizadores -f são combinados pela ordem apresentada, e os ficheiros posteriores substituem as chaves dos ficheiros anteriores, uma a uma. Esta é a forma habitual de manter um ficheiro base com uma pequena substituição para produção. No entanto, as regras diferem para listas e mapas. Consulte como o Compose combina vários ficheiros antes de investigar um resultado inesperado.

--profile inicia os serviços marcados com esse perfil juntamente com os serviços sem perfil. Assim, as ferramentas de depuração ficam fora de um up normal. -p define o nome do projeto. Desta forma, é possível executar duas cópias da mesma stack lado a lado, com redes e nomes de volumes separados. Recuperar a stack depois de um reboot não exige introduzir um comando. É necessária uma unidade que o execute automaticamente, conforme descrito em iniciar stacks do Compose no boot.

FAQ

O que substituiu docker-compose com um hífen?

O Compose V2, chamado como docker compose com um espaço. É um plugin incluído no Docker Engine, e a ferramenta Python V1 já não é instalada pelos pacotes atuais. Se a forma com espaço não produzir qualquer saída, instale o pacote docker-compose-plugin da sua distribuição. Atualize os scripts antigos para a forma com espaço em vez de adicionar um alias, porque o V2 tem flags que o V1 nunca teve.

Por que docker compose restart não aplica a alteração da minha configuração?

restart para e inicia o contentor existente com a configuração usada na sua criação e nunca volta a ler compose.yaml. Qualquer alteração a variáveis de ambiente, portas, volumes ou à tag da imagem requer docker compose up -d, que compara cada serviço com o respetivo contentor em execução e recria os que são diferentes. Adicione --force-recreate quando quiser que a substituição ocorra mesmo que nada tenha sido alterado no ficheiro.

Como atualizo um serviço para uma imagem mais recente?

Execute docker compose pull e depois docker compose up -d. O pull obtém a imagem atual para cada tag no ficheiro, e up -d recria qualquer serviço cujo ID da imagem já não corresponda ao do respetivo contentor. Executar up -d isoladamente reutiliza a imagem que já está no disco. É assim que uma stack fixada em latest pode continuar a usar uma build com meses sem apresentar qualquer erro.

Que comandos de limpeza são seguros num servidor em produção?

docker system df, docker image prune -a e docker builder prune removem apenas imagens e cache. Os serviços em execução continuam a funcionar e os volumes nomeados não são alterados. O par perigoso é docker compose down -v e docker volume prune, que elimina volumes nomeados sem pedir confirmação. Execute primeiro docker compose config --volumes para saber o que está em risco.

Posso executar um comando sem iniciar a stack inteira?

Sim. docker compose run --rm --no-deps web sh inicia um único contentor a partir da definição do serviço web, ignora as dependências e remove o contentor quando sair. Use exec quando o contentor já estiver em execução, porque exec se liga ao processo ativo e mostra o estado real do serviço.