Setting Container Environment Variables with `docker run --env`

Por Que Usar Variáveis de Ambiente?

Em desenvolvimento de software moderno, um princípio fundamental é a separação entre configuração e código. Você já aplica este conceito em seus projetos .NET, onde o appsettings.json define configurações padrão, mas estas são frequentemente sobrescritas por variáveis de ambiente em ambientes de produção para maior flexibilidade e segurança.

Containerizar uma aplicação eleva a importância desse princípio. Uma imagem Docker deve ser um artefato imutável e portátil, capaz de ser executado em qualquer ambiente (desenvolvimento, testes, produção) sem modificações. As variáveis de ambiente são a ponte que permite que essa imagem única se adapte a cada ambiente específico.

Para solidificar o conceito fundamental de variáveis de ambiente, a primeira seção do artigo a seguir oferece uma excelente explicação.

Em resumo, ao usar variáveis de ambiente com Docker, você pode:

• Promover a portabilidade: A mesma imagem meu-app-api:1.0 pode se conectar a um banco de dados local em sua máquina ou a um banco de dados de produção na AWS, apenas mudando o valor de uma variável CONNECTION_STRING.
• Aumentar a segurança: Você evita que informações sensíveis, como senhas e chaves de API, sejam gravadas permanentemente na imagem do contêiner e, consequentemente, submetidas ao controle de versão.

Injetando Variáveis com docker run

O Docker torna extremamente simples passar variáveis de ambiente para um contêiner no momento de sua execução usando a flag --env ou sua forma abreviada -e.

A sintaxe é direta: --env NOME_DA_VARIAVEL=valor.

Exemplo Básico

Vamos usar uma imagem alpine (uma distribuição Linux mínima) para demonstrar isso. O comando a seguir inicia um contêiner, define uma variável de ambiente chamada GREETING e, em seguida, executa um comando sh -c 'echo ...' que imprime o valor da variável no terminal.

docker run --rm -e GREETING="Olá do mundo exterior" alpine sh -c 'echo "A mensagem recebida foi: $GREETING"'

• --rm: Garante que o contêiner seja removido automaticamente após a execução, mantendo seu sistema limpo.
• -e GREETING="...": Define a variável de ambiente GREETING dentro do contêiner.
• alpine sh -c '...': A imagem e o comando a ser executado. Note que $GREETING é acessado dentro do ambiente do contêiner.

O resultado esperado será:

A mensagem recebida foi: Olá do mundo exterior

O artigo da Spacelift, que você consultou antes, detalha essa sintaxe e outras variações úteis.

Exemplo do Mundo Real: Configurando um Banco de Dados

Um caso de uso muito comum é configurar um serviço, como um banco de dados PostgreSQL. A imagem oficial do postgres usa variáveis de ambiente para configurar o superusuário e a senha na primeira inicialização.

Vamos iniciar um contêiner PostgreSQL definindo a senha:

docker run -d --name meu-banco-pg -e POSTGRES_PASSWORD=minhasenhasupersecreta postgres

• -d: Executa em modo detached.
• --name meu-banco-pg: Dá um nome fácil de lembrar ao nosso contêiner.
• -e POSTGRES_PASSWORD=...: A imagem postgres foi projetada para ler essa variável e configurar o banco de dados com a senha fornecida.

O contêiner agora está rodando e configurado. Se você tentasse iniciar sem essa variável, a inicialização falharia e os logs indicariam a ausência dela.

Verificando as Variáveis de Ambiente em um Contêiner

Depois de iniciar um contêiner, como você pode verificar se as variáveis foram definidas corretamente? A maneira mais direta é executar um comando dentro do contêiner em execução usando docker exec.

O comando printenv no Linux lista todas as variáveis de ambiente.

docker exec meu-banco-pg printenv | grep POSTGRES_PASSWORD

Este comando executa printenv dentro do contêiner meu-banco-pg e filtra (grep) a saída para mostrar apenas a linha que contém POSTGRES_PASSWORD, confirmando que ela foi definida.

docker run -d --name minha-aplicacao -e CACHE_HOST=redis.local -e CACHE_PORT=6379 minha-app:latest

Gerenciando Múltiplas Variáveis com --env-file

Passar muitas variáveis de ambiente na linha de comando pode se tornar complicado e propenso a erros. Uma abordagem mais limpa é agrupá-las em um arquivo. Docker permite isso com a flag --env-file.

1. Crie um arquivo de ambiente: Crie um arquivo chamado, por exemplo, database.env. Cada linha deve estar no formato CHAVE=VALOR.

   # Conteúdo de database.env
   POSTGRES_USER=admin
   POSTGRES_DB=meuappdb
   

   Comentários (linhas que começam com #) são ignorados.

2. Use --env-file no docker run: Agora, você pode passar a senha na linha de comando (pois é mais sensível) e o restante das configurações via arquivo.

   # Primeiro, pare e remova o contêiner anterior para evitar conflito de nome
   docker stop meu-banco-pg
   docker rm meu-banco-pg
   
   # Inicie um novo contêiner usando o arquivo .env
   docker run -d --name meu-banco-pg \
     -e POSTGRES_PASSWORD=minhasenhasupersecreta \
     --env-file ./database.env \
     postgres
   

Este método é muito mais organizado e escalável.

O recurso a seguir, um gist do GitHub, oferece uma visão concisa e direta sobre o uso tanto de -e quanto de --env-file.

Uma nota crucial sobre segurança: Arquivos .env frequentemente contêm informações sensíveis. É uma prática de segurança essencial adicionar esses arquivos ao seu .gitignore para garantir que eles nunca sejam enviados para um repositório Git.

# Exemplo de .gitignore
*.env

Conclusão

Nesta lição, você aprendeu a técnica fundamental para configurar contêineres em tempo de execução. Desacoplar a configuração da imagem do contêiner é uma prática que você usará em todos os seus projetos futuros com Docker, especialmente ao preparar suas aplicações .NET para diferentes ambientes de implantação.

Principais pontos a reter:

• Variáveis de ambiente são o método padrão para passar configurações (como credenciais, URLs de API, etc.) para um contêiner.
• Use docker run -e CHAVE=VALOR ou docker run --env CHAVE=VALOR para definir uma única variável.
• Para gerenciar várias variáveis de forma organizada, agrupe-as em um arquivo e use docker run --env-file ./caminho/do/arquivo.env.
• Sempre adicione arquivos .env que contêm segredos ao seu .gitignore.
• Você pode verificar as variáveis dentro de um contêiner em execução com docker exec <container> printenv.

Até agora, aprendemos a executar contêineres, gerenciar seu ciclo de vida e configurá-los com variáveis de ambiente. No entanto, um contêiner possui muito mais metadados e detalhes de configuração do que apenas variáveis de ambiente. Na próxima lição, exploraremos o comando docker inspect, uma ferramenta poderosa que permite obter uma visão completa e detalhada de toda a configuração de um contêiner, o que é indispensável para depuração e diagnóstico.