# Primeiro Deploy

Este guia mostra como fazer seu primeiro deploy completo usando o Runner.

# Pre-requisitos

• Runner instalado e configurado (runner init executado)
• Repositorio Git com seu codigo
• Docker e Traefik rodando no servidor

# Passo 1: Preparar Repositorio

# Criar Branch dist

cd /caminho/do/projeto
git checkout -b dist
git push -u origin dist
git checkout dev  # Voltar para desenvolvimento

# Criar .deploy.yml

Crie o arquivo .deploy.yml na raiz:

project: meu-app
port: 8000
networks:
  - public

environment:
  APP_ENV: production
  DB_HOST: "{{::MySQL Host?mysql}}"
  DB_NAME: "{{::Database name}}"

secrets:
  DB_PASSWORD: "{RANDOM}"
  JWT_SECRET: "${GENERATE:hex:64}"

healthcheck:
  path: /health           # endpoint a ser implementado pela app (HTTP 2xx)
  interval: 10s
  timeout: 5s
  retries: 3

# Para imagens onde generator detecta tipo (nginx/caddy → /, php-fpm → tcp:9000),
# o default é type-aware desde v2.18.2. Override aqui se sua app usa outro path.

# v2.16.0+: o repo é resolvido automaticamente do state file
# (registrado via `runner add --repo`). O bloco `github:` no
# .deploy.yml foi DEPRECATED — não é mais necessário aqui.

version:
  source: file
  file: package.json
  field: version
# Desde v2.18.2, o generator default emite `source: git-commit`
# (deploys versionados via SHA, sem precisar `version` field em arquivo).
# Use `source: file` apenas se quer versão semântica explícita do package.json.

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

Adapte conforme seu projeto:

• project: Nome unico do projeto
• port: Porta que sua app escuta
• domain: Dominio de producao
• version.file: Arquivo com a versao (package.json, version.json, etc)
• environment/secrets: Variaveis de ambiente com suporte a prompts e valores gerados. Veja Env Wizard para detalhes

# Commit da Configuracao

git add .deploy.yml
git commit -m "chore: adiciona configuracao CI/CD"
git push origin dev

# Passo 2: Build do Projeto

# Frontend (React, Vue, etc)

npm run build

# Backend (Flask, Node, etc)

# Para Python com src/
# Nao precisa build, apenas organize o codigo em src/

# Para Node
npm run build  # Se necessario

# Passo 3: Preparar Branch dist

# Mudar para dist
git checkout dist

# Limpar conteudo antigo
rm -rf dist/ src/ package.json version.json

# Copiar artefatos
# Para frontend:
cp -r /caminho/build/dist ./dist/

# Para backend Python:
cp -r /caminho/src ./src/
cp requirements.txt ./
cp version.json ./  # Se usar

# Copiar configuracao
cp /caminho/.deploy.yml ./

# Commit
git add .
git commit -m "deploy: v1.0.0"
git push origin dist

# Passo 4: Registrar App no Runner

No servidor de producao:

runner add --repo seu-usuario/meu-app --branch dist --token ghp_xxx --ckey "minha-chave-secreta"

Nota v2.12.0+: --branch e obrigatorio. --repo aceita URLs (ex: https://github.com/seu-usuario/meu-app). --ckey sem valor gera random automaticamente.

Este comando:

1. Clona o repositorio em /data/apps/meu-app/
2. Faz checkout da branch indicada em --branch
3. Registra a app no estado do Runner
4. Se secrets.enc existe no repo, restaura .env/.secrets usando a ckey

A flag --ckey permite recuperacao zero-touch dos secrets em caso de perda do servidor. Guarde a ckey em um password manager.

# Passo 5: Executar Deploy

# Deploy Manual (Primeiro)

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

# Acompanhar o Deploy

# Ver logs em tempo real
runner logs tail --app /data/apps/seu-usuario_meu-app

# Ver status
runner health --app /data/apps/seu-usuario_meu-app

# Passo 6: Verificar

# Testar Acesso

curl https://app.meusite.com.br/health

# Verificar Container

docker ps | grep meu-app

# Verificar Traefik

ls /etc/traefik/dynamic/ | grep meu-app

# Passo 7: Configurar Cron

Para deploys automaticos, adicione ao crontab:

crontab -e

*/5 * * * * /opt/runner/runner fetch --deploy --json >> /var/log/runner-fetch.json 2>&1

# Proximo Deploy

Para deployar novas versoes:

# 1. Desenvolver em dev
git checkout dev
# ... fazer alteracoes ...
git commit -m "feat: nova funcionalidade"
git push origin dev

# 2. Release para main
git checkout main
git merge dev --no-ff -m "release: v1.1.0"
git tag -a v1.1.0 -m "Release v1.1.0"
git push origin main --tags

# 3. Build e deploy
npm run build
git checkout dist
rm -rf dist/ && cp -r /build/dist ./dist/
git add . && git commit -m "deploy: v1.1.0"
git push origin dist

# Runner detecta e deploya automaticamente (via cron)
# Ou force manualmente:
runner fetch --deploy

# Troubleshooting

# Deploy nao inicia

# Verificar se app esta registrada
runner list

# Verificar configuracao
runner validate --file /data/apps/seu-usuario_meu-app/.deploy.yml

# Health check falha

# Ver logs do container
docker logs seu-usuario_meu-app_production

# Verificar endpoint
curl http://localhost:8000/health  # Dentro do container

# Rollback

Se algo der errado:

runner rollback --app /data/apps/seu-usuario_meu-app

# Estrutura Final

Apos o deploy, a estrutura sera:

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

# Proximos Passos

• Secrets e Encriptacao - Recuperacao zero-touch
• Canary Deployment - Deploy gradual
• Staging de PRs - Ambientes de teste
• Configurando Notificacoes - Telegram/Discord