# 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 (versoes, deploys)
• Log de fetches
• Estado de staging

# Aplicacoes

Cada app registrada.

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

Estrutura:

/apps/usuario_meu-app/
├── .deploy.yml      # Configuracao de deploy
├── .env             # Variaveis de ambiente
├── .secrets         # Credenciais (perm 600)
└── src/
    └── production/  # Instancia
        ├── v1.0.0/  # Versao
        ├── v1.0.1/  # Versao
        └── 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 teste
• Remove versoes antigas (mantendo keep_versions)

# 8. Notify

• Envia notificacao de sucesso/falha
• 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.