Se você ainda usa comandos docker run longos e difíceis de manter, converter para um arquivo docker-compose.yml organiza a infraestrutura e facilita o compartilhamento com a equipe. A ferramenta Docker run → Compose automatiza essa tradução, mapeando flags como portas, volumes, variáveis de ambiente e políticas de reinício para serviços equivalentes no Compose. Neste artigo, você vai aprender as melhores práticas para realizar essa conversão, os erros mais comuns e como garantir segurança e privacidade no processo.

Por que substituir o docker run pelo Compose?

O comando docker run é prático para testes rápidos, mas à medida que o projeto cresce, a lista de argumentos se torna confusa e difícil de replicar. Com o Docker Compose, você declara toda a configuração em um arquivo YAML, permitindo versionamento, reuso e orquestração de múltiplos contêineres. Além disso, a ferramenta de conversão trata automaticamente de flags como -p, -v, -e, --restart, --network e --privileged, que são comuns em ambientes de desenvolvimento e produção.

Como funciona o conversor Docker run → Compose

A ferramenta analisa o comando docker run usando um tokenizer que identifica cada flag e seu valor. Em seguida, ela gera o bloco services equivalente no docker-compose.yml. Por exemplo:

  • -p 8080:80 vira ports: - "8080:80"
  • -v /meu/volume:/dados vira volumes: - /meu/volume:/dados
  • -e VAR=valor vira environment: VAR=valor
  • --restart always vira restart: always
  • --network minha-rede vira networks: - minha-rede
  • --privileged vira privileged: true

O resultado é um arquivo pronto para uso, que pode ser ajustado manualmente conforme a necessidade.

Boas práticas ao converter docker run para docker compose

1. Sempre revise o arquivo gerado

Nenhuma ferramenta automática é perfeita. Depois de usar o Docker run → Compose, leia cada linha do YAML gerado. Verifique se as portas mapeadas estão corretas, se os volumes apontam para diretórios existentes e se as variáveis de ambiente não contêm informações sensíveis que poderiam vazar no arquivo.

2. Prefira volumes nomeados a bind mounts

Quando você usa -v /caminho/local:/container, o conversor mantém o bind mount. Para ambientes compartilhados, prefira volumes nomeados (ex.: meu-volume:/container) e declare o volume no bloco volumes do Compose. Isso evita problemas de permissão e garante portabilidade entre máquinas.

```yaml services: app: image: nginx volumes:

  • dados-site:/usr/share/nginx/html

volumes: dados-site: ```

3. Agrupe variáveis de ambiente em arquivo .env

Flags -e podem poluir o serviço. No Compose, você pode usar env_file para carregar um arquivo .env. Se a ferramenta gerar várias variáveis, mova-as para um arquivo separado e referencie-o no serviço.

```yaml services: app: image: node:18 env_file:

  • .env

```

4. Defina redes explicitamente

Quando o comando original usa --network, o conversor cria a rede correspondente. É uma boa prática nomear a rede e, se houver comunicação entre serviços, garantir que todos estejam na mesma rede.

``yaml networks: frontend: driver: bridge ``

5. Aproveite o bloco depends_on para ordernar inicialização

O docker run não tem um mecanismo nativo para dependências. No Compose, você pode usar depends_on para garantir que um serviço espere outro iniciar, embora isso não aguarde a aplicação estar pronta. Combine com health checks para maior confiabilidade.

Erros comuns na conversão e como evitá-los

1. Ignorar o --rm e gerar contêineres que não se limpam

O --rm é frequentemente usado em docker run para remover o contêiner após a execução. No Compose, o comportamento é diferente: contêineres param, mas não são removidos automaticamente. Se você precisa de um contêiner descartável, considere usar profiles ou executar com docker compose run --rm.

2. Não mapear corretamente políticas de reinício

Flags como --restart on-failure:5 podem ser mal interpretadas pelo tokenizer. Sempre confira se o valor foi traduzido para restart: on-failure:5 e se essa sintaxe é suportada pela sua versão do Docker Compose.

3. Usar --privileged sem necessidade

--privileged concede privilégios elevados ao contêiner. Muitas vezes é usado por comodidade, mas no Compose é importante questionar se realmente precisa de acesso total. Prefira cap_add para adicionar apenas as capacidades necessárias.

```yaml services: app: image: myapp cap_add:

  • NET_ADMIN

```

4. Esquecer de declarar volumes no nível superior

Se a conversão gera um volume não nomeado no serviço, mas não o declara no bloco volumes do YAML, o Compose pode falhar. Verifique se todos os volumes que não são bind mounts estão listados corretamente.

5. Desconsiderar a versão do formato Compose

Comandos antigos podem usar flags que o conversor interpreta corretamente, mas o YAML gerado pode conter chaves obsoletas (ex.: version: '3'). Atualmente, recomenda-se omitir version para usar a sintaxe mais moderna.

Segurança e privacidade

A ferramenta Docker run → Compose foi planejada para ser executada diretamente no seu navegador. Isso significa que o comando docker run que você insere nunca é enviado para nenhum servidor externo. Todo o processamento é feito localmente via JavaScript, garantindo que dados de configuração, variáveis de ambiente ou caminhos de volume permaneçam apenas no seu computador. Nenhuma ferramenta oferece proteção absoluta contra todos os riscos, mas essa abordagem minimiza significativamente a exposição de informações sensíveis.

Alternativas ao uso da ferramenta

Caso prefira não usar o conversor online, existem outras formas de fazer a migração:

  • Manualmente: transcreva cada flag para o YAML seguindo a documentação do Compose. É trabalhoso, mas dá controle total.
  • Scripts shell ou alias: mantenha os comandos docker run em scripts .sh e execute-os via um arquivo Makefile. Isso não substitui o Compose, mas organiza melhor os comandos.
  • Compose Watch e Docker Init: ferramentas mais recentes do Docker ajudam a gerar arquivos iniciais a partir de projetos existentes, mas nem sempre cobrem todas as flags.

Para projetos com múltiplos contêineres, o Compose ainda é a opção mais madura e amplamente adotada.

Perguntas frequentes

1. A ferramenta funciona com comandos que usam --link?

O conversor trata as flags mais comuns. --link é uma flag legada e não é convertida. Recomenda-se substituir --link por redes personalizadas no Compose.

2. Posso converter um comando com argumentos posicionais?

A ferramenta espera um comando no formato docker run [flags] imagem [comando]. Argumentos posicionais são colocados no final e serão inseridos como command no serviço.

3. O que acontece se eu usar aspas no comando original?

O tokenizer consegue lidar com aspas simples e duplas, desde que o comando seja colado corretamente. Evite quebras de linha inesperadas.

4. Preciso instalar algo para usar a ferramenta?

Não. O Docker run → Compose roda no navegador, sem necessidade de instalação ou cadastro.

5. O arquivo gerado funciona com docker compose up?

Sim, o YAML gerado segue as especificações atuais do Compose. Basta salvar o conteúdo como docker-compose.yml ou compose.yaml e executar docker compose up.

Conclusão

Migrar de comandos docker run para arquivos Compose é um passo importante para profissionalizar o uso de contêineres. A ferramenta Docker run → Compose acelera esse processo, mas a revisão manual e a aplicação das boas práticas garantem que o resultado seja seguro, portátil e fácil de manter. Lembre-se de checar volumes, políticas de reinício e privilégios, e aproveite a categoria Dev do FerramentasGratis para explorar outras utilidades que simplificam o dia a dia de quem trabalha com tecnologia.