# runner env

Comandos para gerenciar variaveis de ambiente e secrets.

# Visao Geral

O Runner separa configuracao em dois arquivos:

• .env - Variaveis de configuracao (permissao 644)
• .secrets - Credenciais sensiveis (permissao 600)

Estes arquivos podem ser gerados automaticamente no primeiro deploy via Env Wizard, a partir das secoes environment: e secrets: do .deploy.yml.

# Deteccao Automatica de Secrets (v2.4.2)

O runner detecta automaticamente se uma variavel e sensivel pelo nome, usando Aho-Corasick multi-pattern matching com 3 niveis de confianca:

Falsos positivos conhecidos sao filtrados automaticamente: keyboard, primary_key, max_tokens, public_key, tokenizer, hash_map, cache_key, etc.

# Flags

# Auto-detecta: DB_PASSWORD → secret (alta confianca)
runner env set myapp --key DB_PASSWORD --value xxx
# → Com ckey: "Detectado como secret. Salvando em .secrets (encriptado)"
# → Sem ckey: "Salvando em .env (plaintext). Acessivel a qualquer usuario..."

# Forcar como secret (requer ckey)
runner env set myapp --key CUSTOM_FIELD --value xxx --secret
runner env set myapp --key CUSTOM_FIELD --value xxx --force

# Sem ckey + --secret = erro
runner env set myapp --key X --value Y --secret
# → "Secrets requerem encriptacao. Registre a app com --ckey"

# Comandos

# Status

runner env status --app <path>

Exemplo:

runner env status --app /data/apps/usuario_meu-app

Output:

Environment de meu-app:

.env:
  FLASK_ENV=production
  DEBUG=false
  LOG_LEVEL=info

.secrets:
  DB_PASSWORD=***
  REDIS_PASSWORD=***
  SECRET_KEY=***

# Definir Variavel

runner env set --app <path> --key <key> --value <value>

Exemplo:

runner env set --app /data/apps/meu-app --key LOG_LEVEL --value debug

# Definir Secret

runner env set --app <path> --key <key> --value <value> --secret

Exemplo:

runner env set --app /data/apps/meu-app --key API_KEY --value sk_live_xxx --secret

# Regenerar Secret

runner env regenerate --app <path> --key <key>

Gera novo valor aleatorio para o secret.

Exemplo:

runner env regenerate --app /data/apps/meu-app --key SECRET_KEY

# Validar Variaveis

runner env validate --app <path> --required "VAR1,VAR2,VAR3"

Verifica se todas as variaveis obrigatorias estao definidas.

Exemplo:

runner env validate --app /data/apps/meu-app --required "DB_HOST,DB_USER,DB_PASSWORD"

Output (sucesso):

All required variables are set.

Output (falha):

Missing required variables:
  - DB_PASSWORD

# Arquivos

# .env

Variaveis de configuracao (nao sensiveis):

FLASK_ENV=production
DEBUG=false
LOG_LEVEL=info
BASE_URL=https://app.meusite.com.br

# .secrets

Credenciais sensiveis (encriptadas em repouso com --ckey):

DB_PASSWORD=senha_secreta
REDIS_PASSWORD=outra_senha
SECRET_KEY=chave_muito_secreta_gerada
API_KEY=sk_live_xxxxxxxxxxxx

Permissoes: chmod 600 .secrets

Comportamento por versao:

runner env set --secret e runner env regenerate continuam gravando no .secrets se ele existir. Se a app nao tem .secrets (registrada sem ckey), estes comandos gravam no .env.

# Templates

O Runner processa templates em .env.template:

# Sintaxe

# Valor fixo
FLASK_ENV=production

# Gerar automaticamente
SECRET_KEY=${GENERATE:secret:64}
DB_PASSWORD=${GENERATE:password:32}

# Valor manual (prompt no primeiro deploy)
EXTERNAL_API_KEY=${MANUAL:API key do servico externo}

# Referencia a contexto
PROJECT_NAME=${CONTEXT:PROJECT}
DOMAIN=${CONTEXT:DOMAIN}

# Tipos de GENERATE

# Variaveis de CONTEXT

# Docker Compose

O Runner configura env_file automaticamente:

services:
  app:
    env_file:
      - .env
      - .secrets

# Provisionamento GENERATE (v1.3.2)

No primeiro deploy, o Runner le .env.template e gera valores para variaveis com ${GENERATE:...}. Os valores gerados sao gravados em .env e .secrets.

Em deploys seguintes, o Runner nao sobrescreve valores ja resolvidos. Variaveis com padrao GENERATE no template sao ignoradas nas flags -e do container, garantindo que o valor gerado no primeiro deploy seja preservado.

Antes da v1.3.2, valores contendo ${GENERATE:...} eram injetados como -e flags no docker run, sobrescrevendo os valores ja resolvidos em .env/.secrets.

# Seguranca

• .secrets tem permissao 600
• Dollar signs ($) sao escapados para $$
• Secrets nao aparecem em logs
• env status mostra *** para secrets

# Encriptacao e Recovery

Se a app foi registrada com runner add --ckey, os arquivos .env e .secrets sao encriptados e persistidos no repositorio como .runner/secrets.enc apos cada deploy.

Em caso de perda do servidor, runner add --ckey restaura automaticamente os secrets a partir do repo.

Consulte o guia Secrets e Encriptacao para detalhes completos.