breakpilot-core/docs-src/development/ci-cd-pipeline.md

CI/CD Pipeline

Uebersicht ueber den Deployment-Prozess fuer BreakPilot.

Uebersicht

Repo	Deployment	Trigger	Compose File
breakpilot-core	Coolify (automatisch)	Push auf coolify Branch	docker-compose.coolify.yml
breakpilot-compliance	Coolify (automatisch)	Push auf main Branch	docker-compose.yml + docker-compose.coolify.yml
breakpilot-lehrer	Mac Mini (lokal)	Manuell docker compose	docker-compose.yml

Deployment-Architektur

┌─────────────────────────────────────────────────────────────────┐
│                      Entwickler-MacBook                          │
│                                                                   │
│   breakpilot-core/         → git push gitea coolify              │
│   breakpilot-compliance/   → git push gitea main                 │
│   breakpilot-lehrer/       → git push + ssh macmini docker ...   │
│                                                                   │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    │                       │
                    ▼                       ▼
┌───────────────────────────┐  ┌───────────────────────────┐
│   Coolify (Production)    │  │   Mac Mini (Lokal/Dev)    │
│                           │  │                           │
│   Gitea Actions           │  │   breakpilot-lehrer       │
│   ├── Tests               │  │   ├── studio-v2           │
│   └── Coolify API Deploy  │  │   ├── klausur-service     │
│                           │  │   ├── backend-lehrer      │
│   Core Services:          │  │   └── voice-service       │
│   ├── consent-service     │  │                           │
│   ├── rag-service         │  │   Core Services (lokal):  │
│   ├── embedding-service   │  │   ├── postgres            │
│   ├── paddleocr-service   │  │   ├── valkey, vault       │
│   └── health-aggregator   │  │   ├── nginx, gitea        │
│                           │  │   └── ...                  │
│   Compliance Services:    │  │                           │
│   ├── admin-compliance    │  │                           │
│   ├── backend-compliance  │  │                           │
│   ├── ai-compliance-sdk   │  │                           │
│   └── developer-portal    │  │                           │
└───────────────────────────┘  └───────────────────────────┘

breakpilot-core → Coolify

Pipeline

# .gitea/workflows/deploy-coolify.yml
on:
  push:
    branches: [coolify]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy via Coolify API
        # Triggert Coolify Build + Deploy ueber API
        # Secrets: COOLIFY_API_TOKEN, COOLIFY_RESOURCE_UUID, COOLIFY_BASE_URL

Workflow

# 1. Code auf MacBook bearbeiten
# 2. Committen und pushen:
git push origin main && git push gitea main

# 3. Fuer Production-Deploy:
git push gitea coolify

# 4. Status pruefen:
# https://gitea.meghsakha.com/Benjamin_Boenisch/breakpilot-core/actions

Coolify-deployed Services

Service	Container	Beschreibung
valkey	bp-core-valkey	Session-Cache
consent-service	bp-core-consent-service	Consent-Management (Go)
rag-service	bp-core-rag-service	Semantische Suche
embedding-service	bp-core-embedding-service	Text-Embeddings
paddleocr-service	bp-core-paddleocr	OCR Engine (x86_64)
health-aggregator	bp-core-health	Health-Check Aggregator

breakpilot-compliance → Coolify

Pipeline

# .gitea/workflows/ci.yaml
on:
  push:
    branches: [main, develop]

jobs:
  # Lint (nur PRs)
  # Tests (Go, Python, Node.js)
  # Validate Canonical Controls
  # Deploy (nur main, nach allen Tests)

Workflow

# Committen und pushen → Coolify deployt automatisch:
git push origin main && git push gitea main

# CI-Status pruefen:
# https://gitea.meghsakha.com/Benjamin_Boenisch/breakpilot-compliance/actions

# Health Checks:
curl -sf https://api-dev.breakpilot.ai/health
curl -sf https://sdk-dev.breakpilot.ai/health

breakpilot-lehrer → Mac Mini (lokal)

Workflow

# 1. Code auf MacBook bearbeiten
# 2. Committen und pushen:
git push origin main && git push gitea main

# 3. Auf Mac Mini pullen und Container neu bauen:
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-lehrer pull --no-rebase origin main"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml build --no-cache <service>"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml up -d <service>"

Gitea Actions

Ueberblick

BreakPilot nutzt Gitea Actions (GitHub Actions-kompatibel) als CI/CD-System. Der act_runner laeuft als Container auf dem Mac Mini und fuehrt Pipelines aus.

Komponente	Container	Beschreibung
Gitea	bp-core-gitea (Port 3003)	Git-Server + Actions-Trigger
Gitea Runner	bp-core-gitea-runner	Fuehrt Actions-Workflows aus

Pipeline-Konfiguration

Workflows liegen in jedem Repo unter .gitea/workflows/:

Repo	Workflow	Branch	Aktion
breakpilot-core	deploy-coolify.yml	coolify	Coolify API Deploy
breakpilot-compliance	ci.yaml	main	Tests + Coolify Deploy

Runner-Token erneuern

# Runner-Token in Gitea UI generieren:
# https://macmini:3003 → Settings → Actions → Runners → New Runner

# Token in .env setzen:
GITEA_RUNNER_TOKEN=<neues_token>

# Runner neu starten:
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d --force-recreate gitea-runner"

Pipeline-Status pruefen

# Runner-Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-gitea-runner"

Health Checks

Production (Coolify)

# Core PaddleOCR
curl -sf https://ocr.breakpilot.com/health

# Compliance
curl -sf https://api-dev.breakpilot.ai/health
curl -sf https://sdk-dev.breakpilot.ai/health

Lokal (Mac Mini)

# Core Health Aggregator
curl -sf http://macmini:8099/health

# Lehrer Backend
curl -sf https://macmini:8001/health

# Klausur-Service
curl -sf https://macmini:8086/health

Troubleshooting

Container startet nicht

# Logs pruefen (lokal)
ssh macmini "/usr/local/bin/docker logs bp-core-<service>"

# In Container einloggen
ssh macmini "/usr/local/bin/docker exec -it bp-core-<service> /bin/sh"

Build-Fehler

# Cache komplett leeren
ssh macmini "docker builder prune -a"

# Ohne Cache bauen
ssh macmini "docker compose build --no-cache <service>"

Rollback

Coolify

Ein Redeploy mit einem aelteren Commit kann durch Zuruecksetzen des Branches ausgeloest werden:

# Branch auf vorherigen Commit zuruecksetzen und pushen
git reset --hard <previous-commit>
git push gitea coolify --force

Lokal (Mac Mini)

# Image taggen als Backup
ssh macmini "docker tag breakpilot-lehrer-klausur-service:latest breakpilot-lehrer-klausur-service:backup"

# Bei Problemen: Backup wiederherstellen
ssh macmini "docker tag breakpilot-lehrer-klausur-service:backup breakpilot-lehrer-klausur-service:latest"