SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Docker Compose exec: abrir shell interativo no serviço

Use docker compose exec web bash para abrir um shell no servico em execucao. Se a imagem nao tiver bash, use sh; para criar outro contentor, use run.

Obter um shell interativo com docker compose exec

docker compose exec web bash abre um shell interativo dentro do contentor que já está em execução como o serviço web. O nome depois de exec é o nome do serviço definido no seu compose.yaml, não o nome do contentor. Se a imagem não tiver bash, peça sh.

docker compose ps
docker compose exec web bash

Execute docker compose ps primeiro. O comando deve listar web com o estado running. Depois, o segundo comando coloca-o numa linha de comandos dentro do contentor. exit ou Ctrl-D devolve-o ao host. O serviço continua em execução depois de sair, porque exec iniciou um segundo processo juntamente com o processo principal. Fechar o shell não afeta o PID 1 (processo com ID 1), que é o processo para o qual o contentor foi criado.

Esta é uma das duas formas de entrar. exec liga-se a um contentor que já existe. docker compose run cria um novo contentor a partir da mesma definição de serviço. Quase tudo o resto neste guia resulta desta única diferença.

Por que -it é opcional no Compose, mas obrigatório com o docker simples

Duas flags controlam a parte interativa de uma sessão. -i mantém a entrada padrão aberta, para que o que escrever seja recebido pelo processo. -t aloca um terminal pseudo, chamado TTY, para que a shell mostre um prompt e processe as teclas de seta. O docker exec simples deixa ambas desativadas por padrão. Por isso, todos os exemplos apresentados escrevem docker exec -it. O docker compose exec ativa ambas por si só. Assim, docker compose exec -it web bash e docker compose exec web bash fazem a mesma coisa. O Compose também aceita -it, para manter compatibilidade com hábitos antigos.

É possível detetar a ausência de um TTY em poucos segundos. A shell é executada, mas não mostra nenhum prompt, e Ctrl-C nunca chega ao processo. O caso oposto, em que é necessário pedir ao Compose para não alocar um TTY, tem a sua própria flag e a sua própria secção mais abaixo.

O que fazer quando a imagem não tem bash

Ao pedir bash a uma imagem baseada em Alpine, o comando exec falha desta forma:

OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH: unknown

Essa mensagem não indica um problema do exec. Indica que não foi encontrado nenhum bash nos diretórios listados no PATH do contentor. Para uma shell, isso quase sempre significa que a imagem não inclui nenhuma. O Alpine inclui o BusyBox, que fornece ash como /bin/sh, mas não inclui bash. Por isso, peça sh:

docker compose exec web sh

As imagens baseadas em Debian e Ubuntu, incluindo as tags -slim, incluem bash. O bash fornece histórico de comandos e melhor conclusão automática. Por isso, tente primeiro o bash e use sh como alternativa. sh existe em quase todas as imagens de uso geral.

Algumas imagens não têm nenhuma shell. As imagens Distroless e as imagens compiladas FROM scratch contêm apenas o binário da aplicação e as respetivas bibliotecas. Isso é intencional, porque uma shell que não existe não pode ser usada contra a aplicação. Nessas imagens, sh falha com a mesma mensagem e não há outra shell para tentar. Há duas abordagens possíveis. As imagens Distroless da Google disponibilizam tags :debug que adicionam uma shell BusyBox. Pode mudar temporariamente para essa tag para entrar no contentor. Em alternativa, inicie um contentor separado dentro dos namespaces do destino:

CID=$(docker compose ps -q web)
docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot

Agora tem as ferramentas do netshoot ligadas à rede da aplicação. Assim, curl localhost:8080 e ss -lntp comportam-se como se fossem executados dentro dela. O sistema de ficheiros apresentado pertence ao netshoot, não à aplicação. Como o namespace de processos é partilhado, /proc/1/root/ aponta para o sistema de ficheiros do processo de destino. No entanto, ls /proc/1/root/ também tem de passar a verificação de permissões ptrace do kernel. O facto de ambos os processos serem executados como root não é suficiente. A verificação também considera as credenciais, as capacidades, o atributo dumpable do destino e os módulos de segurança. Um valor de dumpable diferente de 1 bloqueia o acesso, exceto quando o autor da chamada tem CAP_SYS_PTRACE no namespace de utilizadores do destino. O Docker não concede SYS_PTRACE por predefinição. Adicionar --cap-add SYS_PTRACE à linha docker run resolve as verificações de credenciais e dumpability, mas os módulos de segurança ainda podem negar o acesso.

Quando o serviço não estiver em execução, use docker compose run --rm

exec precisa de um container em execução. Se for apontado para um serviço parado, falha:

service "web" is not running

Ele não inicia nada por si só. docker compose run fará isso:

docker compose run --rm web bash

run cria um novo container a partir da definição do serviço web, usando a mesma imagem, o mesmo ambiente, os mesmos volumes e as mesmas redes, e substitui o comando do serviço pelo que você digitou. --rm elimina esse container quando você sai. Se omitir --rm, os containers restantes acumulam-se com nomes como myproject-web-run-4f1c2b. docker compose ps -a mostra esses containers, e docker compose rm remove-os juntamente com os outros containers parados do serviço.

Dois comportamentos de run surpreendem muitos utilizadores. Ele não publica as portas do serviço, a menos que você adicione --service-ports ou faça o mapeamento manualmente com -p. Isso é intencional: um segundo container que tente associar a porta 8080 do host enquanto o primeiro ainda a utiliza falharia com bind: address already in use. run também inicia tudo o que o serviço lista em depends_on antes de apresentar a sua shell. Uma verificação rápida pode, portanto, iniciar uma base de dados e uma cache. --no-deps evita esse comportamento.

run passa pelo ENTRYPOINT da imagem, mas exec não. exec inicia o seu comando diretamente no container existente, por isso o script de entrypoint nunca o recebe. Com run, o seu bash é passado como argumento para esse script. Muitas imagens oficiais terminam o entrypoint com exec "$@", que encaminha o comando diretamente e lhe fornece a shell. Um script que interprete os próprios argumentos terá outro comportamento. Nesse caso, substitua o entrypoint apenas nessa execução:

docker compose run --rm --entrypoint sh web

Esta é a razão mais comum para um comando que funciona com exec comportar-se de forma diferente com run. A separação entre comando e entrypoint explica qual das duas partes da configuração da imagem você está a substituir em cada caso.

exec ou run: como escolher

  • exec exige um container em execução. run não exige e pode iniciar dependências.
  • exec vê a lista de processos em execução e os ficheiros no estado atual, incluindo tudo o que a aplicação escreveu desde que arrancou. run obtém uma camada gravável limpa a partir da imagem, mas os volumes nomeados e os bind mounts continuam a expor os dados existentes do serviço.
  • exec ignora o entrypoint. run executa-o.
  • run deixa um container para trás, exceto se passar --rm.

Use exec para verificar o que está realmente a acontecer. Use run --rm para uma cópia descartável do mesmo ambiente, para executar um comando de migração pontual ou quando o serviço real não permanece ativo tempo suficiente para permitir o uso de exec.

Sinalizadores úteis de exec: utilizador, diretório de trabalho e réplicas

A maioria das imagens muda para um utilizador que não é root. Por isso, a instalação de uma ferramenta de diagnóstico dentro da shell de execução para neste ponto:

E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)

-u root fornece uma shell root no mesmo contentor:

docker compose exec -u root web sh

-w /srv/app define o diretório de trabalho apenas para esse comando. -e KEY=value adiciona uma variável de ambiente à sua sessão, mas não ao serviço. Quando um serviço tem mais do que uma réplica, --index 2 determina em que contentor entra. Se estiver a investigar a propriedade dos ficheiros num diretório montado, PUID e PGID em imagens de contentores explica por que motivo são os IDs numéricos, e não os nomes dos utilizadores, que determinam quem pode escrever nesse diretório.

Obter um shell psql ou mysql dentro do contentor da base de dados

O cliente já está incluído na imagem da base de dados. Por isso, não precisa de o instalar no host nem de publicar a porta:

docker compose exec db psql -U postgres -d app
docker compose exec db mariadb -u root -p

As imagens Postgres incluem psql, as imagens MySQL incluem mysql e as imagens MariaDB incluem mariadb. A ligação é feita a partir de dentro do contentor. Por isso, funciona mesmo quando o ficheiro Compose não publica nenhuma porta da base de dados. Esta é a configuração mais segura na rede bridge predefinida do Docker: os hosts externos não conseguem aceder diretamente a uma porta da base de dados que não foi publicada, embora o host Docker e os contentores na mesma rede ainda consigam aceder-lhe.

Há uma armadilha que pode consumir uma tarde. O shell expande as variáveis no host antes de o Docker receber o comando. Por isso, -U "$POSTGRES_USER" envia uma string vazia quando essa variável só existe dentro do contentor. As aspas simples e um shell dentro do contentor fazem a expansão no local correto:

docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

Não use docker compose run --rm db sem um comando. Isso inicia um segundo servidor Postgres com o mesmo volume de dados e o servidor recusa iniciar:

FATAL:  lock file "postmaster.pid" already exists

O ficheiro de bloqueio está a funcionar corretamente, porque dois servidores a escrever no mesmo diretório de dados poderiam corrompê-lo. Enquanto a base de dados estiver em execução, use exec para entrar no contentor. A decisão sobre incluir ou não a base de dados no Compose é independente. executar a base de dados no Docker ou no host apresenta as vantagens e desvantagens.

Serviços que precisam de uma consola no arranque: stdin_open e tty

exec e run abrangem as shells que abre manualmente. Um serviço cujo processo principal é interativo por natureza precisa de duas chaves no ficheiro compose:

services:
  console:
    image: python:3.12-slim
    command: python
    stdin_open: true
    tty: true

stdin_open: true é docker run -i e tty: true é docker run -t. Sem estas chaves, o contentor inicia e termina imediatamente com o código 0, e docker compose ps -a mostra Exited (0). Não ocorreu nenhuma falha. python sem um terminal em stdin lê imediatamente o fim do ficheiro e termina normalmente. Esse é o comportamento correto para um programa com o qual ninguém está a interagir.

Com ambas as chaves definidas, ligue-se ao processo em execução:

docker attach $(docker compose ps -q console)

Saia com Ctrl-P e depois Ctrl-Q. O processo continua em execução. Essa sequência só funciona quando o contentor tem um TTY e stdin aberto. Ctrl-C envia uma interrupção (SIGINT) para o PID 1. Isso só para o serviço se o programa estiver escrito para terminar com SIGINT, porque o Linux não fornece ao PID 1 o tratamento de sinais predefinido. Por isso, não use Ctrl-C para se desligar.

Deixe ambas as chaves desativadas nos serviços comuns. Um servidor web nunca lê stdin, e tty: true faz com que muitos programas mudem para a saída a cores e o armazenamento em buffer por linhas, porque assumem que uma pessoa está a observar a saída. Isso preenche docker compose logs com códigos de escape.

Por que a execução de scripts falha no cron e na CI: a flag -T

Um comando exec que funciona no seu terminal pode falhar quando um script o executa, num cron job, num runner de integração contínua (CI) ou num pipe:

the input device is not a TTY

O Compose solicita um terminal pseudo sempre que a própria saída é enviada para um terminal. O pedido falha antes de o seu comando ser executado se stdin também não for um terminal. O código-fonte recente da Docker CLI apresenta a mesma falha como cannot attach stdin to a TTY-enabled container because stdin is not a terminal. O Compose atual ignora automaticamente o pedido quando a saída é redirecionada ou enviada por pipe, como normalmente acontece no cron. Algumas versões anteriores faziam o pedido em qualquer situação, e cat dump.sql | docker compose exec db psql introduzido na própria linha de comandos ainda o ativa atualmente. -T desativa o pedido em todos os casos. Por isso, use-o nos scripts em vez de depender da deteção automática:

0 3 * * * docker compose -f /srv/app/compose.yaml exec -T db pg_dump -U postgres -Fc app > /srv/backups/app.dump

-T é importante por outro motivo. Um TTY reescreve o fluxo de bytes antes de o enviar. Por isso, um dump comprimido que passe por um TTY chega danificado. Passe -T explicitamente para qualquer saída redirecionada ou enviada por pipe.

Há mais dois detalhes relacionados com o cron. Passe -f com um caminho absoluto, porque o cron executa o job a partir do diretório home, onde não existe um ficheiro compose. Nesse caso, o Compose termina com no configuration file provided: not found. Além disso, exec devolve o código de saída do comando que executou. Assim, um pg_dump com falha faz o seu script falhar com set -e, em vez de criar uma cópia de segurança vazia e indicar sucesso. Os restantes comandos usados no dia a dia estão reunidos numa folha de referência dos comandos do Compose que vale a pena manter junto desses scripts.

Por que as alterações feitas dentro de um container desaparecem

Você instala uma ferramenta com exec, edita um ficheiro de configuração, corrige o problema e, uma semana depois, a correção desaparece. Isso é o funcionamento esperado da camada gravável do container. docker compose up -d, depois de qualquer alteração na tag da imagem ou na definição do serviço, destrói o container antigo e cria um novo a partir da imagem. Todas as alterações manuais desaparecem com o container antigo.

docker compose restart é diferente. Para e inicia o mesmo container, por isso as alterações manuais permanecem. É por isso que uma correção manual pode parecer válida durante semanas e depois desaparecer durante uma atualização não relacionada. Named volumes e bind mounts sobrevivem a ambas as operações, porque os respetivos dados ficam fora do container. bind mounts e named volumes explica qual escolher para os dados que pretende manter.

Trate, portanto, uma shell exec como um local para consultar e testar. Depois de identificar a correção, escreva-a num local onde possa persistir: um pacote no Dockerfile, uma definição no ficheiro compose. Em seguida, docker compose up -d para a aplicar e confirme com outro exec que o novo container realmente a contém.

FAQ

Qual é a diferença entre docker compose exec e docker compose run?

exec executa um comando dentro de um container que já está em execução, além do processo principal, e ignora o entrypoint da imagem. run cria um novo container a partir da mesma definição de serviço, usando a mesma imagem, o mesmo ambiente, os mesmos volumes e as mesmas redes. O comando é passado pelo entrypoint, e todos os serviços depends_on são iniciados primeiro. run também mantém as portas do serviço não publicadas, exceto se adicionar --service-ports ou um mapeamento -p. Use exec para inspecionar o serviço em execução. Use run --rm quando o serviço estiver parado ou quando precisar de um container separado, mas lembre-se de que os volumes nomeados e os bind mounts são partilhados.

Porque é que docker compose exec indica que o serviço não está em execução?

exec liga-se a um container existente e não pode criar um novo. Por isso, um serviço parado ou terminado inesperadamente produz service "web" is not running. Verifique docker compose ps -a, que lista os containers terminados com um estado como Exited (1), e consulte docker compose logs web para saber porque parou. Para obter uma shell mesmo assim, execute docker compose run --rm --entrypoint sh web. Esse comando cria um container novo a partir da mesma definição de serviço sem executar o comando de arranque com problemas.

Como abro uma shell quando a imagem não tem bash?

A falha de docker compose exec web bash com exec: "bash": executable file not found in $PATH significa que não foi encontrado nenhum bash nos diretórios indicados pelo PATH do container. Quase sempre, isso significa que a imagem não o inclui. Isto é normal em qualquer imagem baseada em Alpine. Use docker compose exec web sh, porque o BusyBox fornece /bin/sh. Numa imagem sem shell, exec não consegue abrir uma shell, mas continua a executar os binários existentes na imagem. Mude para a tag :debug da imagem, se o publicador disponibilizar uma, ou inicie um container de depuração nos namespaces do destino com docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot, onde $CID vem de docker compose ps -q web.

Porque é que o meu comando exec falha com "the input device is not a TTY" no cron?

docker compose exec solicita um terminal pseudo quando a saída é enviada para um terminal, e a solicitação falha se o stdin também não for um terminal. As versões atuais do Compose ignoram automaticamente a solicitação quando a saída é redirecionada, como normalmente acontece no cron. No entanto, algumas versões anteriores faziam a solicitação sempre, e encaminhar dados para o stdin de exec a partir de uma shell interativa também a ativa. Adicione -T para a desativar: docker compose exec -T db pg_dump -U postgres app. Use também -T para qualquer saída redirecionada ou encaminhada, porque um TTY altera o fluxo de bytes e danifica um dump binário. No cron, passe também -f com o caminho absoluto para o seu ficheiro Compose. Caso contrário, o Compose termina com no configuration file provided: not found.

As alterações que faço dentro de um container com exec sobrevivem a um reinício?

Elas sobrevivem a docker compose restart, que reutiliza o mesmo container. Perdem-se em docker compose up -d depois de qualquer alteração na imagem ou na configuração, porque essa operação recria o container a partir da imagem e elimina a sua camada gravável. Os dados escritos em volumes nomeados ou bind mounts sobrevivem a ambas as operações, porque ficam fora do container. Faça alterações de diagnóstico com exec e coloque depois a versão permanente no Dockerfile ou no ficheiro Compose.

Este artigo foi útil?