# runner deploy

Executa o pipeline de deploy completo para uma aplicacao ou todas as apps registradas.

# Sintaxe

runner deploy <app>
runner deploy <app> [--version <version>]
runner deploy --all

# Parametros

*Use <app> ou --all, nao ambos.

# Exemplos

# Deploy Padrao

runner deploy --app /data/apps/usuario_meu-app

# Deploy por Nome

runner deploy meu-app

# Deploy de Versao Especifica

runner deploy meu-app --version v1.2.3

# Deploy para Staging

runner deploy meu-app --instance staging

# Deploy sem Testes

runner deploy meu-app --skip-tests

# Deploy Forcado (Redeploy)

runner deploy meu-app --force

# Deploy com Output Detalhado

runner deploy meu-app --verbose

# Deploy de Todas as Apps

runner deploy --all

# Override de Porta (v2.19.0)

# Override permanente (persiste no state — re-deploys reusam)
runner deploy myapp --port 9000

# Sem port mapping (strategy=none, container so na rede docker)
runner deploy myapp --no-port

--port N sobrescreve qualquer alocacao sticky existente e persiste em state.network.published_port. Use isso pra "fixar" uma porta que voce quer permanente. As deploys subsequentes (manuais ou via fetch --deploy) vao reusar a mesma porta sem precisar --port de novo.

--no-port desabilita port mapping so desta deploy — nao persiste. Util pra debugging ou pra apps que so precisam estar na rede Docker (sem expor pro host).

Veja `runner ports` pra inspecionar/liberar/realocar portas alocadas.

# Pre-flight de secrets vazios (v2.19.0)

Antes do container subir, o runner valida que cada secret declarado em .deploy.yml::secrets: tem valor nao-vazio em .runner/secrets.enc (apos decifrar). Se algum esta vazio, o deploy aborta:

runner deploy middleware-241
# Error: deploy_blocked: secrets declared in .deploy.yml have empty values: ["APP_KEY"]
#        Bypass: rerun with --insecure (NOT recommended).
#        Or fill the values:
#          runner env set <app> --key APP_KEY --secret --value <value>

Resolução padrão:

runner env set middleware-241 --key APP_KEY --secret --value "base64:$(openssl rand -base64 32)"
runner deploy middleware-241  # agora passa

Bypass: runner deploy middleware-241 --insecure (so use conscientemente — geralmente significa que o app vai subir quebrado em runtime).

Resolve o caso onde Laravel /up retornava 200 mesmo com APP_KEY vazio, fazendo o runner declarar deploy bem-sucedido enquanto / retornava 500.

Util apos recovery do servidor. A partir da v2.1.0, o --all faz topological sort baseado no campo depends_on: do .deploy.yml de cada app. Apps sem dependencias sao deployadas primeiro; apps cujas dependencias falharam sao automaticamente puladas.

Ciclos de dependencia (a -> b -> a) sao detectados e abortam o --all com mensagem listando os projetos envolvidos.

# Forca redeploy de todas
runner deploy --all --force

# Com output detalhado
runner deploy --all --verbose

# Output do Deploy

# Formato Padrao

O deploy exibe progresso com badges indicando cada etapa:

[1/6] [PREPARE]   Preparando deploy...
[2/6] [ARTIFACT]  Copiando artefatos...
[3/6] [ENV]       Gerando ambiente...
[4/6] [SECURITY]  Verificando segurança...
[5/6] [CONTAINER] Subindo container de teste...
[6/6] [PROMOTE]   Promovendo versao...

═══════════════════════════════════════
  ✓ DEPLOY CONCLUIDO
  App:     meu-app/production
  Versao:  v1.2.0
  URL:     https://app.meusite.com.br
═══════════════════════════════════════

# Versao Ja Implantada

Se a versao ja esta implantada:

═══════════════════════════════════════
  ✓ JA IMPLANTADO
  App:     meu-app/production
  Versao:  v1.2.0

  Use --force para reimplantar
═══════════════════════════════════════

# Modo Verbose (-V)

O modo verbose exibe logs tecnicos detalhados:

runner deploy meu-app --verbose

Inclui:

• Versao do Runner
• Caminho do config
• Logs de nivel INFO
• Detalhes de cada operacao

# Pipeline de Deploy

O comando executa as seguintes etapas:

1. Prepare

   • Verifica configuracao (.deploy.yml)
   • Extrai versao do projeto
   • Cria diretorio de versao

2. Artifacts

   • Copia artefatos para diretorio de versao
   • Limpa workdir (remove arquivos desnecessarios)

3. Environment

   • Processa templates de ambiente
   • Gera .env e .secrets
   • Encripta e persiste secrets no repo (se ckey configurada)

4. Test (Blue-Green)

   • Sobe container de teste
   • Executa health check
   • Executa testes de seguranca
   • Executa Playwright (se configurado)

5. Promote

   • Atualiza symlink current
   • Gera Traefik dynamic config
   • Roteia trafego para nova versao

6. Cleanup

   • Remove containers de teste
   • Remove versoes antigas

7. Notify

   • Envia notificacao (Telegram/Discord)

# Comportamento

# Rollback Automatico (v1.4.1)

O Runner faz rollback automatico dependendo da fase em que o deploy falha:

Em todos os casos, a notificacao de falha indica qual versao ficou ativa.

# Protecao contra Retry Infinito (v1.4.1)

Quando o deploy automatico (fetch --deploy) falha, o Runner registra o commit que falhou no estado da app. Se o mesmo commit falhar novamente, o contador de retries incrementa. Ao atingir max_deploy_retries (padrao: 3), o Runner bloqueia o deploy automatico daquele commit.

Commit abc123 → deploy falhou (1/3)
Commit abc123 → deploy falhou (2/3)
Commit abc123 → deploy falhou (3/3)
Commit abc123 → bloqueado (aguardando novo push)
Commit def456 → novo commit, contador resetado → deploy executa

Para configurar o limite:

# /opt/runner/config.yml
max_deploy_retries: 3   # padrao: 3, 0 = ilimitado

O deploy manual (runner deploy meu-app) nao e afetado pelo limite — sempre executa.

# Health Check

O health check verifica:

• Container iniciou
• Endpoint /health retorna 200
• Container esta healthy

O timeout e calculado automaticamente com base nos parametros de healthcheck do .deploy.yml:

timeout = start_period + (interval + timeout) * retries + buffer

# Notificacoes

Mensagens enviadas:

• Deploy Iniciado — ao comecar o pipeline
• Deploy Concluido — ao finalizar com sucesso
• Deploy Falhou — em caso de erro (inclui versao anterior ativa e erro extraido)

A mensagem de falha extrai a linha de erro real de outputs verbosos (Docker BuildKit, npm, compilador Rust) em vez de mostrar o output truncado.

Exemplo de notificacao de falha:

❌ Deploy Falhou

📦 Projeto: meu-app
🌐 Instance: production
🏷️ Versão: abc1234
🔄 Rollback: v1.0.0 (versão anterior mantida)

⚠️ Erro:
docker build failed: ERROR: process "/bin/sh -c npm run build" did not complete successfully

# Exit Codes

# Logs

# Ver historico
runner logs history --app /data/apps/meu-app

# Ver log do ultimo deploy
runner logs tail --app /data/apps/meu-app

# Estrutura Apos Deploy

/data/apps/meu-app/
├── .deploy.yml
├── .env
├── .secrets
├── .runner/
│   └── secrets.enc       # Secrets encriptados (se ckey configurada)
└── src/
    └── production/
        ├── v1.0.0/
        ├── v1.0.1/
        └── current -> v1.0.1

# Secrets Encriptados

Se a app foi registrada com --ckey, o Runner encripta .env e .secrets apos cada deploy e persiste como .runner/secrets.enc no repositorio. Isso permite recuperacao zero-touch em caso de perda do servidor.

Consulte o guia Secrets e Encriptacao para detalhes completos.