Dominando o Docker Run: Opções Essenciais de Comando Explicadas

docker run cria um novo contêiner a partir de uma imagem e o inicia. O comando parece simples à primeira vista, mas as opções decidem como seu contêiner se conecta à rede, armazena dados, recebe configuração e se comporta após uma reinicialização.

Use este guia quando você souber a imagem que deseja executar, mas precisar dos flags certos para uma configuração prática.

Sintaxe Básica

docker run [OPÇÕES] IMAGEM [COMANDO] [ARG...]

IMAGEM é o nome da imagem, como nginx ou postgres:16. COMANDO e ARG... são opcionais e substituem ou estendem o comando padrão da imagem.

Para um teste rápido em primeiro plano:

docker run hello-world

Para serviços reais, você geralmente adiciona opções.

Executar em Segundo Plano com -d

Por padrão, o Docker anexa seu terminal à saída do contêiner. O modo detached executa o contêiner em segundo plano:

docker run -d nginx

O Docker imprime o ID do novo contêiner e retorna seu prompt. Verifique com:

docker ps

Leia os logs de um contêiner detached com:

docker logs <id_ou_nome_do_contêiner>

Publicar Portas com -p

Os contêineres têm seu próprio namespace de rede. Se um serviço escuta dentro do contêiner, publique a porta para alcançá-lo a partir do seu host:

docker run -d -p 8080:80 nginx

Isso mapeia a porta do host 8080 para a porta do contêiner 80, então http://localhost:8080 alcança o Nginx.

Você pode publicar mais de uma porta:

docker run -d -p 8080:80 -p 8443:443 nginx

Para vincular apenas ao localhost no host, inclua o IP do host:

docker run -d -p 127.0.0.1:8080:80 nginx

Isso é útil para ferramentas locais que você não deseja expor em todas as interfaces do host.

Persistir Dados com Volumes

As camadas graváveis do contêiner não são um bom lugar para dados duráveis. Use um bind mount quando quiser um caminho específico do host montado no contêiner:

docker run -d -p 8080:80 -v "$PWD/html:/usr/share/nginx/html:ro" nginx

Isso serve arquivos do seu diretório html local. O sufixo :ro torna a montagem somente leitura dentro do contêiner.

Use um volume nomeado quando o Docker deve gerenciar o local de armazenamento:

docker run -d --name postgres -v pgdata:/var/lib/postgresql/data postgres:16

Se pgdata não existir, o Docker o cria. Inspecione volumes com:

docker volume ls

Para novos trabalhos, a sintaxe --mount do Docker é mais detalhada, mas mais clara:

docker run -d --mount type=volume,src=pgdata,dst=/var/lib/postgresql/data postgres:16

Passar Configuração com -e e --env-file

Variáveis de ambiente são uma maneira comum de configurar aplicativos em contêineres:

docker run -d -e APP_ENV=production my-custom-app:latest

Use -e mais de uma vez para múltiplas variáveis:

docker run -d -e DB_HOST=database.example.com -e DB_USER=app my-app:latest

Para muitas variáveis, use um arquivo env:

docker run -d --env-file ./app.env my-app:latest

Mantenha segredos fora de arquivos .env commitados. Variáveis de ambiente são fáceis de inspecionar a partir do host e de processos com acesso suficiente, então use o gerenciador de segredos da sua plataforma para valores sensíveis de produção.

Nomear Contêineres com --name

O Docker pode gerar um nome, mas um nome claro torna comandos posteriores mais fáceis:

docker run -d --name web -p 8080:80 nginx

Então você pode usar:

docker logs web
docker stop web
docker exec -it web sh

Os nomes dos contêineres devem ser únicos. Se web já existir, remova ou renomeie o contêiner antigo antes de reutilizar o nome.

Usar Modo Interativo com -it

Para shells e sessões de solução de problemas, combine o modo interativo e um pseudo-TTY:

docker run -it ubuntu bash

Quando você sai do shell, o contêiner para. Adicione --rm para sessões descartáveis:

docker run --rm -it alpine sh

Escolher uma Política de Reinicialização

As políticas de reinicialização informam ao Docker o que fazer quando um contêiner sai:

docker run -d --name web --restart unless-stopped -p 8080:80 nginx

Políticas comuns são:

• no: não reiniciar automaticamente. Este é o padrão.
• on-failure[:max-retries]: reiniciar apenas após um código de saída diferente de zero.
• always: reiniciar sempre que o contêiner parar, inclusive após reinicializações do daemon Docker.
• unless-stopped: reiniciar a menos que você tenha parado explicitamente o contêiner.

Para serviços locais de longa execução, unless-stopped geralmente é uma escolha melhor do que always porque uma parada manual permanece respeitada.

Remover Contêineres Descartáveis com --rm

Contêineres parados permanecem no disco até que você os remova. Para comandos únicos, --rm limpa o contêiner após sua saída:

docker run --rm ubuntu echo "Olá de um contêiner temporário"

Não use --rm para contêineres cujo estado parado você precisa inspecionar posteriormente.

Exemplo Prático

Este comando executa um aplicativo web com um nome estável, uma porta publicada, um diretório de logs montado por bind, uma variável de ambiente e uma política de reinicialização:

docker run -d \
  --name my-app \
  --restart on-failure \
  -p 3000:80 \
  -v "$PWD/logs:/app/logs" \
  -e NODE_ENV=production \
  my-node-app:1.0

Após iniciar, verifique o contêiner e confira os logs:

docker ps
docker logs my-app

Conclusão

Comece com o menor comando docker run que funciona, depois adicione opções para o comportamento que você precisa: -d para serviços em segundo plano, -p para acesso, -v ou --mount para dados, -e para configuração, --name para operações, --restart para resiliência e --rm para execuções temporárias.