# Multi-Ambiente (v1.5.0)

Como deployar a mesma aplicacao em maquinas diferentes (producao, staging, homologacao) com ambientes isolados.

# Conceito

Cada maquina roda seu proprio Runner e deploya uma instancia da aplicacao. As instancias sao definidas no .deploy.yml do repositorio, com dominio, variaveis e secrets proprios.

Repositorio (unico)
├── .deploy.yml          # Define todas as instancias
├── .env.template        # Template de variaveis
└── .secrets.template    # Template de secrets

Maquina Producao         Maquina Staging         Maquina Homolog
├── Runner               ├── Runner               ├── Runner
├── instance: production ├── instance: staging    ├── instance: homolog
├── src/production/      ├── src/staging/         ├── src/homolog/
│   └── v1.0.0/          │   └── v1.0.0/          │   └── v1.0.0/
│       ├── .env         │       ├── .env          │       ├── .env
│       └── .secrets     │       └── .secrets      │       └── .secrets

# Configuracao

# 1. Definir instancias no .deploy.yml

project: meu-app
system: sys
port: 8000

environment:
  DB_HOST: mysql
  LOG_LEVEL: info
  APP_ENV: production

instances:
  production:
    domain: app.meusite.com.br
    source:
      type: dist
    environment_overrides:
      DB_HOST: mysql-prod
      DB_NAME: app_prod
      LOG_LEVEL: warn

  staging:
    domain: staging.meusite.com.br
    source:
      type: dist
    environment_overrides:
      APP_ENV: staging
      DB_HOST: mysql-staging
      DB_NAME: app_staging
      LOG_LEVEL: debug

  homolog:
    domain: homolog.meusite.com.br
    source:
      type: branch
      branch: dev
    environment_overrides:
      APP_ENV: homolog
      DB_HOST: mysql-homolog
      DB_NAME: app_homolog
      LOG_LEVEL: debug

# 2. Registrar em cada maquina

# Na maquina de producao (--branch obrigatorio v2.12.0+)
runner add --repo usuario/meu-app --branch main --instance production

# Na maquina de staging
runner add --repo usuario/meu-app --branch dev --instance staging

# Na maquina de homologacao
runner add --repo usuario/meu-app --branch homolog --instance homolog

# 3. Verificar configuracao

runner edit meu-app --show

App Configuration: meu-app/sys
─────────────────────────────
  Path:     /data/apps/meu-app
  Branch:   dist
  Instance: staging
  Type:     sys
  Version:  -
  Token:    not set
  Status:   registered

# 4. Alterar instancia (se necessario)

runner edit meu-app --instance homolog

O comando valida se a instancia existe no .deploy.yml antes de salvar.

# Variaveis de Ambiente

# Hierarquia de Prioridade

.env.template          # Base (do repositorio)
    ↓
environment:           # Global (do .deploy.yml)
    ↓
environment_overrides: # Por instancia (maior prioridade)

# Exemplo pratico

Com o .deploy.yml acima, cada maquina recebe:

Producao (.env):

DB_HOST=mysql-prod
DB_NAME=app_prod
LOG_LEVEL=warn
APP_ENV=production

Staging (.env):

DB_HOST=mysql-staging
DB_NAME=app_staging
LOG_LEVEL=debug
APP_ENV=staging

Homolog (.env):

DB_HOST=mysql-homolog
DB_NAME=app_homolog
LOG_LEVEL=debug
APP_ENV=homolog

# Secrets

# Geracao automatica

Secrets sao gerados automaticamente na primeira vez (bootstrap) usando patterns no .secrets.template:

DB_PASSWORD=${GENERATE:password:32}
JWT_SECRET=${GENERATE:hex:64}
API_KEY=${GENERATE:base64:32}
INTERNAL_TOKEN=${GENERATE:uuid}

Cada maquina gera seus proprios valores — producao tera passwords diferentes de staging.

# Comportamento em deploys subsequentes

• Valores existentes nunca sao sobrescritos
• Novas variaveis adicionadas ao template sao geradas automaticamente
• Variaveis removidas do template continuam no .secrets ate serem removidas manualmente

# Classificacao automatica

Variaveis com PASSWORD, SECRET, _KEY ou TOKEN no nome vao automaticamente para .secrets (permissao 600).

# Auto-Deploy (fetch --deploy)

O cron de cada maquina executa runner fetch --deploy normalmente. O Runner sabe qual instancia deployar pela configuracao no state:

# Cron (igual em todas as maquinas)
*/5 * * * * /opt/runner/runner fetch --deploy --json >> /var/log/runner-fetch.json 2>&1

A resolucao da instancia segue a prioridade:

1. state.instance (definido via --instance no add/edit)
2. default_instance_name() do .deploy.yml
3. "production" (fallback)

# Fluxo de Deploy

Desenvolvedor faz push na dist
        │
        ▼
Maquina Prod                    Maquina Staging
  fetch detecta update            fetch detecta update
  instance = production           instance = staging
  deploy production               deploy staging
  gera .env com overrides prod    gera .env com overrides staging
  container: app_production_v2    container: app_staging_v2
  dominio: app.meusite.com.br    dominio: staging.meusite.com.br

# Branches Diferentes por Instancia

Cada instancia pode acompanhar uma branch diferente:

instances:
  production:
    source:
      type: dist            # Acompanha branch dist
  homolog:
    source:
      type: branch
      branch: dev           # Acompanha branch dev

Nesse caso, homolog recebe updates a cada push em dev, enquanto producao so recebe quando a dist e atualizada.