# Deploy de App de Cliente

Segunda fase do onboarding: publicar as aplicações que nós desenvolvemos (front, sys, api, worker) no servidor já provisionado pelo Implant. O Runner faz deploy blue-green com rollback automático, acionado pela branch dist.

Pré-requisito: servidor já provisionado (Docker + rede public). Ver o guia de provisionamento do Implant.

# Como o Runner deploya

1. A app publica artefatos buildados + um .deploy.yml na branch dist.
2. Um agendamento verifica a dist a cada 5 minutos e deploya o que mudou — então após o push o deploy leva até 5 minutos para começar (é o esperado).
3. O Runner sobe um container de teste, valida o healthcheck, e só então promove para produção (blue-green). Se algo falha, faz rollback sozinho.

# Registrar e deployar

# 1. Registrar a app (clona o repositório e lê o .deploy.yml)
runner add --repo devborlot/<app> --branch dist --token <GITHUB_TOKEN> --ckey "<CHAVE_SECRETA>"

# 2. Deployar agora (ou deixar o ciclo automático de 5 min agir)
runner deploy <projeto>/<sistema> --output json

# 3. Acompanhar
runner status <projeto>/<sistema> --json
runner logs history <projeto>/<sistema>    # coluna ORIGIN: cron (automático) | cli (manual)
runner logs tail <projeto>/<sistema>       # em tempo real

Outros comandos úteis: runner list, runner rollback <projeto>/<sistema>, runner deploy <projeto>/<sistema> --version v1.2.4 (versão específica).

# A chave de conteúdo (`--ckey`)

A --ckey criptografa os secrets da aplicação (variáveis sensíveis como senhas e tokens). Todo deploy de produção exige uma ckey.

• Escolha uma chave forte e guarde-a no seu gerenciador de senhas. Sem ela, os secrets não podem ser recuperados em outro servidor.
• Apps do mesmo repositório podem compartilhar a mesma ckey.
• O token do GitHub (--token) é usado apenas para clonar repositórios privados e fica protegido — nunca aparece em texto puro.

# O arquivo `.deploy.yml`

Fica na branch dist e descreve como a app roda. Campos principais:

project: meu-projeto
system: sys
type: sys                # front-static | front-ssr | sys | api | worker-python | docker-build | custom
image: python:3.12-slim  # imagem pronta; ou use build: para buildar um Dockerfile
port: 8000

healthcheck:
  path: /health          # HTTP (padrão) | tcp: 3306 | cmd: [...] | mode: exit
  interval: 30s
  timeout: 10s
  retries: 3

environment:
  APP_ENV: production
  JWT_SECRET: "${GENERATE:hex:64}"     # geradores automáticos disponíveis

instances:
  production:
    domain: app.cliente.com.br
    keep_versions: 3

# Tipos de deploy

# Healthcheck

path: /health (HTTP, padrão) · tcp: <porta> (serviços sem HTTP) · cmd: [...] (comando próprio) · mode: exit (ferramentas one-shot que rodam e saem).

# Notificações

Cada deploy envia status por Telegram/Discord (iniciado, sucesso, falha, rollback), com um identificador único por deploy para correlação. Em caso de falha, o log completo é anexado à notificação.

Boa prática: confie no ciclo automático (os 5 min) em vez de forçar deploy manual por impaciência. Confira a origem em runner logs history (ORIGIN cron = automático, cli = manual).