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

CI/CD Pipeline

Übersicht über den Deployment-Prozess für Breakpilot.

Übersicht

Komponente	Build-Tool	Deployment
Frontend (Next.js)	Docker	Mac Mini
Backend (FastAPI)	Docker	Mac Mini
Go Services	Docker (Multi-stage)	Mac Mini
Documentation	MkDocs	Docker (Nginx)

Deployment-Architektur

┌─────────────────────────────────────────────────────────────────┐
│                      Entwickler-MacBook                          │
│                                                                   │
│   breakpilot-core/                                               │
│   ├── admin-core/         (Next.js Admin, Port 3008)            │
│   ├── backend-core/       (Python FastAPI, Port 8000)           │
│   ├── consent-service/    (Go Service, Port 8081)               │
│   ├── billing-service/    (Go Service, Port 8083)               │
│   └── docs-src/           (MkDocs)                              │
│                                                                   │
│   git push → Gitea Actions (automatisch)                        │
│   oder manuell: git push && ssh macmini docker compose build    │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                │ git push origin main
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Mac Mini Server (bp-core-*)              │
│                                                                   │
│   Docker Compose                                                 │
│   ├── admin-core (Port 3008)                                    │
│   ├── backend-core (Port 8000)                                  │
│   ├── consent-service (Port 8081)                               │
│   ├── billing-service (Port 8083)                               │
│   ├── gitea (Port 3003) + gitea-runner (Gitea Actions)         │
│   ├── docs (Port 8011)                                          │
│   ├── postgres, valkey, qdrant, minio                           │
│   └── vault, nginx, night-scheduler, health                     │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Sync & Deploy Workflow

1. Dateien synchronisieren

# Sync aller relevanten Verzeichnisse zum Mac Mini
rsync -avz --delete \
  --exclude 'node_modules' \
  --exclude '.next' \
  --exclude '.git' \
  --exclude '__pycache__' \
  --exclude 'venv' \
  --exclude '.pytest_cache' \
  /Users/benjaminadmin/Projekte/breakpilot-core/ \
  macmini:/Users/benjaminadmin/Projekte/breakpilot-core/

2. Container bauen

# Einzelnen Service bauen
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  build --no-cache <service-name>"

# Beispiele:
# studio-v2, admin-v2, website, backend, klausur-service, docs

3. Container deployen

# Container neu starten
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d <service-name>"

4. Logs prüfen

# Container-Logs anzeigen
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  logs -f <service-name>"

Service-spezifische Deployments

Next.js Frontend (studio-v2, admin-v2, website)

# 1. Sync
rsync -avz --delete \
  --exclude 'node_modules' --exclude '.next' --exclude '.git' \
  /Users/benjaminadmin/Projekte/breakpilot-core/studio-v2/ \
  macmini:/Users/benjaminadmin/Projekte/breakpilot-core/studio-v2/

# 2. Build & Deploy
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  build --no-cache studio-v2 && \
  /usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d studio-v2"

Python Services (backend, klausur-service, voice-service)

# Build mit requirements.txt
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  build klausur-service && \
  /usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d klausur-service"

Go Services (consent-service, ai-compliance-sdk)

# Multi-stage Build (Go → Alpine)
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  build --no-cache consent-service && \
  /usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d consent-service"

MkDocs Dokumentation

# Build & Deploy
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  build --no-cache docs && \
  /usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d docs"

# Verfügbar unter: http://macmini:8009

Health Checks

Service-Status prüfen

# Alle Container-Status
ssh macmini "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"

# Health-Endpoints prüfen
curl -s http://macmini:8000/health
curl -s http://macmini:8081/health
curl -s http://macmini:8086/health
curl -s http://macmini:8090/health

Logs analysieren

# Letzte 100 Zeilen
ssh macmini "docker logs --tail 100 breakpilot-core-backend-1"

# Live-Logs folgen
ssh macmini "docker logs -f breakpilot-core-backend-1"

Rollback

Container auf vorherige Version zurücksetzen

# 1. Aktuelles Image taggen
ssh macmini "docker tag breakpilot-core-backend:latest breakpilot-core-backend:backup"

# 2. Altes Image deployen
ssh macmini "/usr/local/bin/docker compose \
  -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \
  up -d backend"

# 3. Bei Problemen: Backup wiederherstellen
ssh macmini "docker tag breakpilot-core-backend:backup breakpilot-core-backend:latest"

Troubleshooting

Container startet nicht

# 1. Logs prüfen
ssh macmini "docker logs breakpilot-core-<service>-1"

# 2. Container manuell starten für Debug-Output
ssh macmini "docker compose -f .../docker-compose.yml run --rm <service>"

# 3. In Container einloggen
ssh macmini "docker exec -it breakpilot-core-<service>-1 /bin/sh"

Port bereits belegt

# Port-Belegung prüfen
ssh macmini "lsof -i :8000"

# Container mit dem Port finden
ssh macmini "docker ps --filter publish=8000"

Build-Fehler

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

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

Monitoring

Resource-Nutzung

# CPU/Memory aller Container
ssh macmini "docker stats --no-stream"

# Disk-Nutzung
ssh macmini "docker system df"

Cleanup

# Ungenutzte Images/Container entfernen
ssh macmini "docker system prune -a --volumes"

# Nur dangling Images
ssh macmini "docker image prune"

Umgebungsvariablen

Umgebungsvariablen werden über .env Dateien und docker-compose.yml verwaltet:

# docker-compose.yml
services:
  backend:
    environment:
      - DATABASE_URL=postgresql://...
      - REDIS_URL=redis://valkey:6379
      - SECRET_KEY=${SECRET_KEY}

Wichtig: Sensible Werte niemals in Git committen. Stattdessen:

• .env Datei auf dem Server pflegen
• Secrets über HashiCorp Vault (siehe unten)

Gitea Actions

Überblick

BreakPilot Core nutzt Gitea Actions (GitHub Actions-kompatibel) als CI/CD-System. Der act_runner läuft als Container auf dem Mac Mini und führt Pipelines direkt bei Code-Push aus.

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

Pipeline-Konfiguration

Workflows liegen im Repo unter .gitea/workflows/:

# .gitea/workflows/main.yml
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build & Test
        run: docker compose build

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 prüfen

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

# Laufende Jobs
ssh macmini "/usr/local/bin/docker exec bp-core-gitea-runner act_runner list"