# Inicio Rapido

Este guia mostra como instalar e configurar o Runner em seu servidor de producao.

# Requisitos

Antes de comecar, certifique-se de ter:

• Linux (Ubuntu 22.04+ ou Debian 12+)
• Docker 24.0+ instalado e rodando
• Traefik 3.0+ configurado com dynamic config
• Acesso SSH ao servidor de producao
• GitHub CLI (gh) instalado (opcional, para staging de PRs)

# Instalacao

# 1. Download do Binario

curl -L https://runner.ccs.systems/runner -o /opt/runner/runner
chmod +x /opt/runner/runner

# 2. Inicializar Ambiente

/opt/runner/runner init

Este comando cria:

• /opt/runner/config.yml - Configuracao global
• /opt/runner/state/ - Diretorio de estado
• /opt/runner/logs/ - Diretorio de logs

# 3. Configurar config.yml

Edite /opt/runner/config.yml:

# Caminhos
apps_path: /apps
traefik_dynamic_path: /etc/traefik/dynamic
state_path: /opt/runner/state
logs_path: /opt/runner/logs

# Docker
registry: registry.local
keep_versions: 3

# Traefik
traefik:
  entrypoints:
    - websecure
  cert_resolver: myresolver

# GitHub
github:
  default_user: seu-usuario-github

# Notificacoes (opcional)
telegram_bot_token: ""
telegram_chat_id: ""

# Staging (opcional)
staging:
  enabled: true
  base_path: /opt/runner/staging
  network: public
  default_ttl_hours: 48
  max_total_instances: 20

# 4. Registrar Aplicacao

/opt/runner/runner add --repo usuario/meu-app

Este comando:

• Clona o repositorio em /apps/usuario_meu-app/
• Registra a app no estado do Runner
• Faz checkout da branch dist

# 5. Configurar Cron

Adicione ao crontab (crontab -e):

# Fetch e deploy a cada 5 minutos
*/5 * * * * /opt/runner/runner fetch --deploy --json >> /var/log/runner-fetch.json 2>&1

# Cleanup de staging a cada hora (opcional)
0 * * * * /opt/runner/runner stage cleanup --json >> /var/log/runner-staging-cleanup.json 2>&1

# Cleanup de versoes antigas diario
0 3 * * * /opt/runner/runner cleanup >> /var/log/runner-cleanup.log 2>&1

# Preparar Repositorio

# 1. Criar Branch dist

No seu repositorio local:

git checkout -b dist
git push -u origin dist

# 2. Criar .deploy.yml

Crie o arquivo .deploy.yml na raiz do projeto:

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

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

# 3. Fazer Build e Push

# Build do projeto
npm run build  # ou seu comando de build

# Mudar para dist
git checkout dist

# Copiar artefatos
rm -rf dist/
cp -r ../build/dist ./dist/

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

# Verificar Deploy

# Verificar Status

/opt/runner/runner list --detailed

# Ver Logs

/opt/runner/runner logs tail --app /apps/usuario_meu-app

# Testar Health

/opt/runner/runner health --app /apps/usuario_meu-app

# Configurar Notificacoes (Opcional)

# Telegram

1. Crie um bot com @BotFather
2. Obtenha o chat ID enviando uma mensagem para o bot
3. Configure no config.yml:

telegram_bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
telegram_chat_id: "-1001234567890"

# Discord

1. Crie um webhook no canal desejado
2. Configure no config.yml:

discord_webhook: "https://discord.com/api/webhooks/..."

# Integrar com Claude Code (Opcional)

O Runner inclui um servidor MCP para integracao com Claude Code.

# Instalar Configuracao MCP

/opt/runner/runner mcp install

# Verificar Status

/opt/runner/runner mcp status

Apos instalar, reinicie o Claude Code. O Runner estara disponivel como ferramenta.

# Proximos Passos

• Primeiro Deploy - Guia completo do primeiro deploy
• Canary Deployment - Deploy gradual com controle de trafego
• Staging de PRs - Ambientes efemeros para Pull Requests
• Referencia CLI - Todos os comandos disponiveis

# Comandos Uteis

# Ver ajuda
runner --help

# Listar apps
runner list

# Deploy manual
runner deploy --app /apps/meu-app

# Rollback
runner rollback --app /apps/meu-app

# Ver versoes
runner versions meu-app -i production