# Arquitetura

O Runner e um sistema de deploy automatizado baseado em Git e Docker.

# Visao Geral

┌─────────────────────────────────────────────────────────────────┐
│                     DESENVOLVIMENTO                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Desenvolvedor                                                   │
│       |                                                          │
│       | git push                                                 │
│       v                                                          │
│    GitHub (branch dist)                                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              |
                              | cron: runner fetch --deploy
                              v
┌─────────────────────────────────────────────────────────────────┐
│                     SERVIDOR PRODUCAO                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Runner CLI (/opt/runner/runner)                                 │
│       |                                                          │
│       | Pipeline de Deploy                                       │
│       v                                                          │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. Fetch - Detecta mudancas no Git                      │    │
│  │  2. Prepare - Extrai versao, cria diretorios            │    │
│  │  3. Artifacts - Copia artefatos buildados               │    │
│  │  4. Environment - Processa .env e .secrets              │    │
│  │  5. Test - Container blue-green, health check           │    │
│  │  6. Promote - Atualiza Traefik, roteia trafego          │    │
│  │  7. Cleanup - Remove versoes antigas                    │    │
│  │  8. Notify - Telegram/Discord                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│       |                                                          │
│       v                                                          │
│  Docker + Traefik                                                │
│       |                                                          │
│       v                                                          │
│  Aplicacao rodando                                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

# Componentes

# Runner CLI

Binario Rust que orquestra todo o pipeline.

Localizacao: /opt/runner/runner

Responsabilidades:

• Gerenciar apps registradas
• Detectar mudancas no Git
• Executar pipeline de deploy
• Gerenciar canary deployments
• Criar ambientes de staging
• Enviar notificacoes

# Configuracao Global

Arquivo YAML com configuracoes do servidor.

Localizacao: /opt/runner/config.yml

Conteudo:

• Paths de apps, logs, estado
• Configuracao do Traefik
• Credenciais de notificacao
• Configuracao de staging

# Estado

Persistencia de estado das apps.

Localizacao: /opt/runner/state/

Conteudo:

• Estado por app: {app}.yml (instancia default)
• Estado de PRs: {app}@pr-42.yml (qualificados com @, v2.0.0)
• Log de fetches
• Estado de staging e canary

# Aplicacoes

Cada app registrada.

Localizacao: /data/apps/{usuario}_{repo}/

Estrutura:

/data/apps/usuario_meu-app/
├── .deploy.yml          # Configuracao de deploy
├── .env                 # Variaveis de ambiente
├── .secrets             # Credenciais (600, apenas com --ckey)
├── values.local.yaml    # Override local de config templates (v2.0.0)
└── src/
    └── production/      # Instancia
        ├── v1.0.0/      # Versao
        ├── v1.0.1/      # Versao ativa
        ├── pr-42/       # PR deploy (v2.0.0)
        └── current      # Symlink para versao ativa

# Traefik Dynamic Config

Configuracao de routing gerada pelo Runner.

Localizacao: /etc/traefik/dynamic/{projeto}.yml

Conteudo:

• Routers (dominio → servico)
• Services (container targets)
• Weighted services (para canary)

# Hierarquia

Projeto
    └── Instancia
            └── Versao

Exemplo:

meu-app (projeto)
├── production (instancia)
│   ├── v1.0.0 (versao)
│   └── v1.0.1 (versao)
└── staging (instancia)
    └── develop-abc123 (versao)

# Fluxo de Deploy

# 1. Deteccao

# Cron executa a cada 5 minutos
runner fetch --deploy

O Runner:

1. Lista apps registradas
2. Para cada app, executa git fetch origin dist
3. Compara HEAD local com remoto
4. Se houver diferenca, aciona deploy

# 2. Prepare

• Extrai versao do arquivo configurado (package.json, etc)
• Cria diretorio de versao: src/{instance}/{version}/
• Valida configuracao

# 3. Artifacts

• Copia artefatos da branch dist para diretorio de versao
• Limpa arquivos desnecessarios (docs, testes)

# 4. Environment

• Processa .env.template
• Gera .env e .secrets
• Substitui variaveis ${GENERATE:...}, ${CONTEXT:...}

# 5. Test (Blue-Green)

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

# 6. Promote

• Atualiza symlink current
• Gera Traefik dynamic config
• Traefik faz hot-reload (~5s)

# 7. Cleanup

• Remove containers de versoes antigas
• Remove imagens Docker das versoes removidas (v2.4.0)
• Mantém keep_versions mais recentes

# 8. Notify

• Envia notificacao de sucesso/falha (com deploy_id para correlacao, v2.0.7)
• Segunda mensagem com erro completo em caso de falha (v2.0.7)
• Telegram ou Discord

# Integracao com Docker

O Runner usa docker run (nao docker-compose em producao).

Container config gerado:

• Labels para Traefik routing
• Labels CCS para identificacao
• Health check configurado
• Networks conectadas
• Volumes montados

Labels CCS:

ccs.systems/project: meu-app
ccs.systems/instance: production
ccs.systems/version: v1.0.1

# Integracao com Traefik

# Routing Dinamico

O Runner gera arquivos YAML em /etc/traefik/dynamic/:

# /etc/traefik/dynamic/meu-app.yml
http:
  routers:
    meu-app-production:
      rule: Host(`app.meusite.com.br`)
      service: meu-app-production
      entryPoints:
        - websecure
      tls:
        certResolver: myresolver

  services:
    meu-app-production:
      loadBalancer:
        servers:
          - url: "http://meu-app_production_v1-0-1:8000"

# Canary com Weighted Services

services:
  meu-app-production:
    weighted:
      services:
        - name: meu-app-production-v1-0-0
          weight: 90
        - name: meu-app-production-v1-0-1-rc1
          weight: 10

# MCP Server

Servidor MCP integrado para Claude Code.

Comunicacao: stdio (JSON-RPC 2.0)

Arquitetura:

Claude Code
    |
    | stdio
    v
Runner MCP Server
    |
    | subprocess
    v
Runner CLI

O MCP Server traduz requests para comandos CLI do Runner.

# Deploy sem Traefik (v2.0.1)

Para servidores backend sem Traefik local (acessiveis via proxy externo pela VPC):

• Instancia sem domain → Runner pula geracao de Traefik config
• ports: no .deploy.yml mapeia portas diretamente (-p ip:host:container)
• Blue-green com downtime minimo: para container antigo antes de iniciar novo (v2.0.8)

# Config Templates (v2.0.0)

Renderizacao Helm-style de arquivos de configuracao:

config/values.yaml              → base
config/values.production.yaml   → override por instancia
values.local.yaml               → override do operador
environment_overrides           → do .deploy.yml
built-ins                       → project, instance, version, domain, system

Templates em templates/*.tpl sao renderizados automaticamente (Phase 1.3 do pipeline).

# Seguranca de Tokens (v2.0.5)

Tokens do GitHub sao transmitidos via GIT_ASKPASS — nunca aparecem em ps aux ou .git/config. Script askpass temporario (chmod 700) criado e deletado automaticamente.

# Image Cleanup (v2.4.0)

O pipeline remove automaticamente imagens Docker de versoes que excedem keep_versions. Comando manual: runner cleanup --images --build-cache 72h.