Docker Compose: comandos essenciais em servidores

Os comandos do Compose que você realmente usa

O Docker Compose disponibiliza mais de quarenta subcomandos. O trabalho diário em um servidor usa cerca de uma dúzia. Esta página agrupa esses comandos pela tarefa que você está executando, apresenta um motivo simples para cada um e indica o material detalhado quando um comando esconde uma armadilha.

Tudo aqui usa o Compose V2: docker compose com um espaço, não o script antigo docker-compose. O V2 é um plugin escrito em Go que é instalado com o Docker Engine, e o V1 não faz mais parte dos pacotes atuais. Portanto, ver um docker-compose: command not found em uma instalação nova do Ubuntu em julho de 2026 é esperado, não indica uma falha. Verifique com docker compose version. Se esse comando não exibir nada, instale o pacote docker-compose-plugin.

Todos os comandos abaixo devem ser executados no diretório que contém o seu compose.yaml, porque o Compose obtém o nome do projeto desse diretório e procura o arquivo relativo a ele. Execute o mesmo comando um nível acima e o Compose será interrompido com no configuration file provided: not found. Se o formato do arquivo ainda for novo para você, comece por um primeiro arquivo do Compose em um VPS e volte aqui para consultar os comandos.

Ciclo de vida: os quatro comandos que você digita e o que remove os containers

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 containers, inicia-os e retorna. Ele retorna assim que os containers são criados. Por isso, um script de deploy que executa uma verificação curl logo depois geralmente falha na primeira tentativa. up -d --wait bloqueia até que todo serviço que declara um healthcheck informe um estado saudável e retorna um código diferente de zero se algum serviço nunca atingir esse estado. A opção só é tão confiável quanto a verificação usada por ela. Portanto, escreva um healthcheck em que o Compose possa confiar antes de usá-la na automação.

stop interrompe os containers e os mantém, portanto start inicia novamente os mesmos containers com a mesma camada gravável. down interrompe os containers e depois remove os containers e a rede do projeto. Tudo o que foi gravado dentro do container e fora de um volume é removido com eles. Esse é o mal-entendido mais dispendioso no Compose, e a diferença completa entre down e stop explica onde ele causa problemas.

restart não é um reload. Ele interrompe e inicia novamente o mesmo container com a configuração que ele já possui. Portanto, uma variável de ambiente alterada, uma nova tag de imagem ou um mapeamento de porta editado não tem efeito algum. Para aplicar uma alteração no arquivo, execute up -d novamente. O Compose compara cada serviço com o container em execução e recria apenas aqueles cuja configuração foi alterada.

Aplicando uma alteração: recriar, baixar 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 não faz nada quando nada foi alterado, o que torna seguro executá-lo repetidamente. --force-recreate substitui essa comparação e substitui todos os containers mesmo quando a configuração é idêntica, sendo a maneira mais rápida de limpar estados estranhos dentro dos containers.

A atualização de uma imagem requer dois comandos porque eles executam tarefas diferentes. pull baixa a imagem atual para cada tag nomeada no arquivo. Em seguida, up -d identifica que o ID da imagem do serviço não corresponde mais ao do container em execução e o recria. Se o pull for ignorado, up -d mantém o latest do mês passado em execução sem gerar erro.

build se aplica a serviços que declaram uma seção build: em vez de uma seção image:. up -d --build faz o build e inicia em uma única etapa, que é o fluxo normal enquanto você altera o código. Use --no-cache somente quando uma camada em cache estiver claramente desatualizada, pois ele reconstrói todas as camadas do zero.

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 somente os containers em execução. Um serviço que falhou durante a inicialização fica invisível até você adicionar -a. Portanto, um container ausente em ps enquanto ps -a o mostra como Exited (1) é o comportamento normal de uma falha na inicialização. Leia o código de saída e depois leia os logs.

logs -f acompanha todos os serviços ao mesmo tempo e adiciona o nome do serviço no início de cada linha. Essa é a visualização adequada quando os serviços se comunicam entre si e a ordem dos eventos é importante. Especifique um serviço para limitar a saída. --tail=100 é importante em um container que está em execução há um mês, porque a configuração padrão imprime todo o histórico e enche o terminal. --since 15m responde à pergunta mais comum: o que aconteceu durante a reinicialização que você acabou de fazer.

top lista os processos dentro de cada container. Isso diferencia "o container está em execução" de "o processo dentro dele está em execução". ls sai do diretório atual e lista todos os projetos Compose no host com o status de cada um. Assim, você pode localizar a stack iniciada há três meses.

Obter 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 usando a mesma definição de serviço. Use-o quando o serviço não permanece em execução por tempo suficiente para permitir o uso de exec. Sempre combine run com --rm. Sem essa opção, cada execução deixa um container parado, e eles se acumulam até que docker compose ps -a fique ilegível.

Tente sh antes de bash. As imagens baseadas em Alpine não incluem bash, e a falha exibe exec: "bash": executable file not found in $PATH. Adicionar --no-deps a run ignora as dependências do serviço. Isso impede que uma verificação rápida da configuração inicialize todo o banco de dados.

run --rm web env é a forma mais rápida de ver o ambiente que um serviço realmente recebeu, depois que todos os arquivos .env, blocos environment: e variáveis de shell foram mesclados. Quando um valor está incorreto, a ordem de mesclagem geralmente é a causa. como o Compose resolve arquivos env e secrets explica qual fonte 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 em uma rede do projeto, e cada nome de serviço é um nome DNS nessa rede. Executar getent hosts db dentro de web exibe o IP do contêiner quando a resolução funciona e não exibe nada quando ela falha. Assim, o comando responde em dois segundos à pergunta "estes contêineres conseguem se comunicar?". Se o nome for resolvido, mas a conexão for recusada, o processo dentro de db está associado a 127.0.0.1, e não a 0.0.0.0. Por isso, ele nunca aceita um pacote de outro contêiner. O restante desse modelo está em como funcionam as redes do Compose e o DNS dos serviços.

port web 80 exibe o endereço e a porta do host em que uma porta do contêiner foi publicada. Isso evita suposições quando o mapeamento veio de uma variável. A publicação de uma porta também cria uma regra de firewall que o Docker gerencia por conta própria. Essa regra fica à frente das suas regras. Por isso, um serviço que você considerava privado pode ficar aberto à internet. Esse caso é explicado em por que as portas publicadas pelo Docker 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 exibe os volumes nomeados declarados pelo projeto, um por linha. Essa é a lista que você precisa incluir no backup. cp copia um arquivo para dentro ou para fora de um container sem abrir um shell, usando a forma service:path no lado que corresponde ao container.

down -v remove esses volumes nomeados junto com os containers. Esse é o comando correto para desmontar uma stack de teste e o comando errado para qualquer stack que contenha dados importantes, porque não há confirmação nem como desfazer a operação. Os bind mounts permanecem, pois ficam no sistema de arquivos do host. Essa diferença no impacto é um dos motivos 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 não aparecem mais no arquivo. Isso ocorre exatamente depois de renomear um serviço. Sem esse comando, esses containers continuam em execução e ficam invisíveis para docker compose ps.

docker system df mostra onde o espaço em disco foi usado antes de qualquer exclusão. Ele separa imagens, containers, volumes locais e cache de build e informa o espaço recuperável de cada item. image prune -a remove todas as imagens que não são referenciadas por nenhuma tag. Em um servidor que baixou várias versões de uma imagem grande, essa costuma ser a maior recuperação de espaço. builder prune limpa o cache de build, que cresce silenciosamente em qualquer servidor que crie suas próprias imagens.

Nenhum desses comandos afeta um volume nomeado. Somente docker volume prune e docker compose down -v fazem isso.

Verificar o arquivo antes que ele cause problemas

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

config --quiet valida e não exibe nada quando a validação é bem-sucedida. Por isso, ele deve ser usado em uma etapa de pré-implantação ou em um hook do git. O comando simples config exibe o arquivo completamente mesclado e interpolado. Isso permite confirmar se uma variável foi resolvida e se um arquivo de substituição foi aplicado conforme esperado. 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 flag global, não uma flag de subcomando. Por isso, ela deve vir antes de up. O comando exibe todas as ações que o Compose executaria e não altera nada. Esses trinta segundos são bem aproveitados antes de executar down em uma stack importante.

Trabalhando com arquivos, 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árias opções -f são mescladas na ordem informada, e os arquivos posteriores substituem as chaves dos arquivos anteriores. Essa é a forma padrão de manter um arquivo base com uma pequena substituição para produção. No entanto, as regras diferem para listas e mapas. Leia como o Compose mescla vários arquivos antes de investigar um resultado inesperado.

--profile inicia os serviços associados a esse perfil junto com os serviços sem perfil. Isso mantém as ferramentas de depuração fora de um up normal. -p define o nome do projeto. Assim, duas cópias da mesma stack podem ser executadas lado a lado, com redes e nomes de volumes separados. Para restaurar a stack após uma reinicialização, não é necessário digitar um comando. Use uma unit que faça isso automaticamente, conforme descrito em iniciar stacks do Compose na inicialização do sistema.

FAQ

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

O Compose V2, chamado como docker compose com um espaço. Ele é um plugin incluído no Docker Engine, e a ferramenta Python V1 não é mais instalada pelos pacotes atuais. Se a forma com espaço não exibir nada, instale o pacote docker-compose-plugin da sua distribuição. Atualize os scripts antigos para usar 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 minha alteração de configuração?

restart para e inicia o container existente usando a configuração com a qual ele foi criado, e nunca relê compose.yaml. Qualquer alteração em variáveis de ambiente, portas, volumes ou na tag da imagem exige docker compose up -d, que compara cada serviço com seu container em execução e recria os que forem diferentes. Adicione --force-recreate quando quiser que a substituição ocorra mesmo que nada tenha mudado no arquivo.

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

Execute docker compose pull e depois docker compose up -d. O pull baixa a imagem atual para cada tag no arquivo, e up -d recria qualquer serviço cujo ID da imagem não corresponda mais ao do container. Executar up -d sozinho reutiliza a imagem que já está no disco. Por isso, uma stack fixada em latest pode continuar usando uma build com meses de idade sem exibir nenhum erro.

Quais comandos de limpeza são seguros em um servidor ativo?

docker system df, docker image prune -a e docker builder prune removem apenas imagens e cache. Portanto, os serviços em execução continuam funcionando e os volumes nomeados não são alterados. A dupla perigosa é docker compose down -v e docker volume prune, que exclui volumes nomeados sem confirmação. Execute docker compose config --volumes primeiro 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 container a partir da definição do serviço web, ignora as dependências e remove o container quando você sai. Use exec quando o container já estiver em execução, porque exec se conecta ao processo ativo e mostra o estado real do serviço.