# DPL - Deploy Pipeline Language

Linguagem de templates usada pelo Runner para gerar configuracoes dinamicas.

# Visao Geral

A DPL permite usar variaveis e geradores em arquivos de configuracao:

• .deploy.yml - Configuracao de deploy
• .env.template - Template de variaveis de ambiente
• Hooks - Comandos pos-deploy

# Sintaxe

${TIPO:parametro:valor}

# Categorias

# GENERATE - Geracao Automatica

Gera valores aleatorios no primeiro deploy.

# Sintaxe
${GENERATE:tipo:tamanho}

Tipos disponiveis:

Exemplos:

# .env.template
SECRET_KEY=${GENERATE:secret:64}
DB_PASSWORD=${GENERATE:password:32}
SESSION_ID=${GENERATE:uuid}
API_TOKEN=${GENERATE:hex:32}

Comportamento:

• Valores sao gerados apenas no primeiro deploy
• Deploys subsequentes preservam o valor existente
• Use runner env regenerate para forcar nova geracao

# CONTEXT - Variaveis de Contexto

Referencia valores do contexto de deploy.

# Sintaxe
${CONTEXT:variavel}

Variaveis disponiveis:

Exemplos:

# .env.template
PROJECT_NAME=${CONTEXT:PROJECT}
BASE_URL=https://${CONTEXT:DOMAIN}
DEPLOYED_VERSION=${CONTEXT:VERSION}

# MANUAL - Entrada Manual

Solicita valor ao operador no primeiro deploy.

# Sintaxe
${MANUAL:descricao}

Exemplos:

# .env.template
EXTERNAL_API_KEY=${MANUAL:API key do servico externo}
SMTP_PASSWORD=${MANUAL:Senha do servidor SMTP}
LICENSE_KEY=${MANUAL:Chave de licenca do produto}

Comportamento:

• Runner exibe prompt durante o deploy
• Valor e salvo em .secrets (permissao 600)
• Deploys subsequentes preservam o valor

# Templates de Staging

Variaveis especificas para ambientes de staging/PR.

# Em .deploy.yml

staging:
  enabled: true
  domain_template: "pr-${PR_NUMBER}.staging.${DOMAIN}"
  container_template: "staging_${PROJECT}_pr${PR_NUMBER}"

# Variaveis de Staging

Exemplo de resolucao:

# Template
domain_template: "pr-${PR_NUMBER}.staging.${DOMAIN}"

# PR #42 do projeto com dominio meusite.com.br
# Resultado: pr-42.staging.meusite.com.br

# Variaveis de Hook

Variaveis disponiveis em comandos de hook.

# Em .deploy.yml

hooks:
  post_healthy:
    - "echo Deploy ${VERSION} em ${CONTAINER}"
    - "curl -X POST ${WEBHOOK_URL}/deploy?v=${VERSION}"

# Variaveis de Hook

# Arquivos e Uso

# .env.template

Template para gerar .env e .secrets.

# Variaveis fixas
FLASK_ENV=production
DEBUG=false
LOG_LEVEL=info

# Geracao automatica (vai para .secrets)
SECRET_KEY=${GENERATE:secret:64}
DB_PASSWORD=${GENERATE:password:32}
REDIS_PASSWORD=${GENERATE:password:24}

# Entrada manual (vai para .secrets)
EXTERNAL_API_KEY=${MANUAL:API key do servico externo}

# Contexto (vai para .env)
PROJECT_NAME=${CONTEXT:PROJECT}
BASE_URL=https://${CONTEXT:DOMAIN}

Separacao automatica:

• Valores com GENERATE ou MANUAL → .secrets
• Valores fixos e CONTEXT → .env

# .deploy.yml

Templates em configuracoes de staging e hooks.

project: meu-app

instances:
  production:
    domain: app.meusite.com.br
    source:
      type: dist

staging:
  enabled: true
  domain_template: "pr-${PR_NUMBER}.staging.${DOMAIN}"
  container_template: "staging_${PROJECT}_pr${PR_NUMBER}"

hooks:
  post_healthy:
    - "echo Deploy ${VERSION} concluido"

# Exemplos Completos

# Backend Flask

# .env.template
FLASK_ENV=production
DEBUG=false
LOG_LEVEL=info

# Database
DB_HOST=mysql
DB_PORT=3306
DB_NAME=app_${CONTEXT:PROJECT}
DB_USER=app_${CONTEXT:PROJECT}
DB_PASSWORD=${GENERATE:password:32}

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=${GENERATE:password:24}

# Seguranca
SECRET_KEY=${GENERATE:secret:64}
JWT_SECRET=${GENERATE:secret:48}

# Aplicacao
BASE_URL=https://${CONTEXT:DOMAIN}
PROJECT_NAME=${CONTEXT:PROJECT}

# Servicos externos
SMTP_PASSWORD=${MANUAL:Senha do servidor SMTP}
STRIPE_KEY=${MANUAL:Stripe API key (sk_live_...)}

# Frontend com Staging

# .deploy.yml
project: meu-frontend
image: registry.local/front-static:1.0
port: 80

networks:
  - public

instances:
  production:
    domain: app.meusite.com.br
    source:
      type: dist
    keep_versions: 3

  staging:
    domain_pattern: "pr-*.staging.meusite.com.br"
    source:
      type: pr
    ephemeral: true
    ttl_hours: 48

staging:
  enabled: true
  domain_template: "pr-${PR_NUMBER}.staging.${DOMAIN}"
  container_template: "staging_${PROJECT}_pr${PR_NUMBER}"
  max_instances: 5
  ttl_hours: 48

hooks:
  post_healthy:
    - "curl -X POST https://api.slack.com/webhook -d '{\"text\":\"Deploy ${VERSION} em ${DOMAIN}\"}'"

# Precedencia e Resolucao

# Ordem de Resolucao

1. Variaveis de ambiente do sistema
2. Valores em .env existente
3. Valores em .secrets existente
4. Templates (GENERATE, CONTEXT, MANUAL)

# Escapando Variaveis

Para usar $ literal, escape com $$:

# .env.template
BASH_COMMAND=echo $$HOME
REGEX_PATTERN=^\$$[0-9]+

# Comandos Relacionados

# Ver variaveis atuais
runner env status --app /data/apps/meu-app

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

# Regenerar secret
runner env regenerate --app /data/apps/meu-app --key SECRET_KEY

# Validar variaveis obrigatorias
runner env validate --app /data/apps/meu-app --required "DB_HOST,DB_USER,DB_PASSWORD"

# Boas Praticas

1. Nunca commitar secrets - Use GENERATE ou MANUAL
2. Prefira GENERATE - Evita erros humanos na criacao de senhas
3. Use CONTEXT para consistencia - Dominio e projeto sempre sincronizados
4. Documente MANUAL - Descricoes claras do que e esperado
5. Tamanhos adequados - Secrets: 64+, Passwords: 32+, Tokens: 48+