docker compose run

O comando docker compose run é utilizado para executar um único comando em um contêiner baseado em um dos serviços definidos no arquivo docker-compose.yml. Ele permite que você execute comandos de forma interativa ou em segundo plano, útil para tarefas de administração, debugging ou execução de scripts específicos.

Sintaxe

docker compose run [OPÇÕES] [SERVIÇO] [COMANDO] [ARGUMENTOS...]

Parâmetros

• SERVIÇO: Nome do serviço definido no arquivo docker-compose.yml no qual o comando será executado.

• COMANDO: O comando que você deseja executar dentro do contêiner.

• ARGUMENTOS: (Opcional) Argumentos adicionais que serão passados ao comando.

Opções

• --name NOME: Define um nome específico para o contêiner criado para a execução do comando.

• -d, --detach: Executa o contêiner em segundo plano (modo "detached"), permitindo que você continue utilizando o terminal para outras tarefas enquanto o contêiner executa o comando.

• --rm: Remove automaticamente o contêiner após a execução do comando. Isso é útil para manter o ambiente limpo, evitando o acúmulo de contêineres temporários.

• -e, --env VAR=VAL: Define variáveis de ambiente para o contêiner no momento da execução do comando.

• --service-ports: Faz com que as portas definidas no arquivo docker-compose.yml sejam expostas. Sem essa opção, as portas não são expostas por padrão no modo "run".

• -T: Desativa o alocamento de um pseudo-TTY. Útil em scripts onde não há necessidade de uma interface interativa.

• --volume, -v: Monta volumes adicionais no contêiner durante a execução do comando.

• --entrypoint: Sobrescreve o ENTRYPOINT definido no Dockerfile ou no docker-compose.yml, permitindo que você especifique um comando inicial diferente para o contêiner.

Exemplo de Uso

1. Executar um Comando em um Serviço: Para executar o comando bash em um serviço chamado web, permitindo uma sessão interativa:

   docker compose run web bash

2. Executar em Segundo Plano: Para executar um comando em segundo plano no serviço web:

   docker compose run -d web your_command_here

3. Executar e Remover Contêiner Automaticamente: Para executar o comando ls no serviço web e remover o contêiner automaticamente após a execução:

   docker compose run --rm web ls

4. Passar Variáveis de Ambiente: Para executar um comando no serviço web com uma variável de ambiente específica:

   docker compose run -e "ENV_VAR=value" web your_command_here

5. Expor Portas do Serviço: Para expor as portas definidas no docker-compose.yml ao executar o comando:

   docker compose run --service-ports web your_command_here

6. Montar Volumes Adicionais: Para montar um volume adicional durante a execução do comando:

   docker compose run -v /host/path:/container/path web your_command_here

7. Sobrescrever o EntryPoint: Para sobrescrever o ENTRYPOINT e especificar um comando diferente:

   docker compose run --entrypoint /bin/sh web

Considerações

• Diferença entre run e exec: Enquanto o docker compose run cria um novo contêiner para executar o comando, o docker compose exec executa o comando em um contêiner já em execução. Use run quando precisar de um contêiner temporário ou quando o serviço ainda não estiver em execução.

• Persistência do Contêiner: A menos que você utilize a opção --rm, o contêiner criado pelo docker compose run permanecerá no sistema após a execução do comando. Isso pode ser útil para debugging, mas também pode levar ao acúmulo de contêineres desnecessários.

• Portas e Redes: Por padrão, o docker compose run não expõe as portas definidas no docker-compose.yml, a menos que você utilize a opção --service-ports. Se você precisa que o contêiner interaja com outros serviços por meio de portas expostas, certifique-se de usar essa opção.

• Isolamento do Contêiner: O contêiner iniciado com docker compose run é isolado dos outros serviços definidos no arquivo docker-compose.yml, a menos que seja configurado para compartilhar redes e volumes explicitamente.

O comando docker compose run é uma ferramenta versátil para executar comandos únicos em ambientes de contêiner, permitindo flexibilidade no desenvolvimento, teste, e operações de manutenção de serviços baseados em Docker.