docs: update all docs to reflect Coolify deployment model

Replace Hetzner references with Coolify. Deployment is now: - Core + Compliance: Push gitea → Coolify auto-deploys - Lehrer: stays local on Mac Mini Updated: CLAUDE.md, MkDocs CI/CD pipeline, MkDocs index, environments. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-13 12:18:25 +01:00
parent 65177d3ff7
commit d1632fca17
4 changed files with 273 additions and 469 deletions
--- a/docs-src/development/ci-cd-pipeline.md
+++ b/docs-src/development/ci-cd-pipeline.md
@@ -1,15 +1,14 @@
 # CI/CD Pipeline

-Übersicht über den Deployment-Prozess für Breakpilot.
+Uebersicht ueber den Deployment-Prozess fuer BreakPilot.

-## Übersicht
+## Uebersicht

-| 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) |
+| 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

@@ -17,287 +16,146 @@
 ┌─────────────────────────────────────────────────────────────────┐
 │                      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)                              │
+│   breakpilot-core/         → git push gitea coolify              │
+│   breakpilot-compliance/   → git push gitea main                 │
+│   breakpilot-lehrer/       → git push + ssh macmini docker ...   │
 │                                                                   │
-│   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                     │
-│                                                                   │
-└─────────────────────────────────────────────────────────────────┘
+                    ┌───────────┴───────────┐
+                    │                       │
+                    ▼                       ▼
+┌───────────────────────────┐  ┌───────────────────────────┐
+│   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    │  │                           │
+└───────────────────────────┘  └───────────────────────────┘
 ```

-## Sync & Deploy Workflow
+## breakpilot-core → Coolify

-### 1. Dateien synchronisieren
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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)
-
-```bash
-# 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)
-
-```bash
-# 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)
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# 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
-
-```bash
-# Port-Belegung prüfen
-ssh macmini "lsof -i :8000"
-
-# Container mit dem Port finden
-ssh macmini "docker ps --filter publish=8000"
-```
-
-### Build-Fehler
-
-```bash
-# Cache komplett leeren
-ssh macmini "docker builder prune -a"
-
-# Ohne Cache bauen
-ssh macmini "docker compose build --no-cache <service>"
-```
-
-## Monitoring
-
-### Resource-Nutzung
-
-```bash
-# CPU/Memory aller Container
-ssh macmini "docker stats --no-stream"
-
-# Disk-Nutzung
-ssh macmini "docker system df"
-```
-
-### Cleanup
-
-```bash
-# 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:
+### Pipeline

 ```yaml
-# docker-compose.yml
-services:
-  backend:
-    environment:
-      - DATABASE_URL=postgresql://...
-      - REDIS_URL=redis://valkey:6379
-      - SECRET_KEY=${SECRET_KEY}
+# .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
 ```

-**Wichtig**: Sensible Werte niemals in Git committen. Stattdessen:
- `.env` Datei auf dem Server pflegen
- Secrets über HashiCorp Vault (siehe unten)
+### Workflow
+
+```bash
+# 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
+
+```yaml
+# .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
+
+```bash
+# 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
+
+```bash
+# 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

-### Überblick
+### Ueberblick

-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.
+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` | Führt Actions-Workflows aus |
+| Gitea Runner | `bp-core-gitea-runner` | Fuehrt Actions-Workflows aus |

 ### Pipeline-Konfiguration

-Workflows liegen im Repo unter `.gitea/workflows/`:
+Workflows liegen in jedem Repo unter `.gitea/workflows/`:

-```yaml
-# .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
-```
+| Repo | Workflow | Branch | Aktion |
+|------|----------|--------|--------|
+| breakpilot-core | `deploy-coolify.yml` | `coolify` | Coolify API Deploy |
+| breakpilot-compliance | `ci.yaml` | `main` | Tests + Coolify Deploy |

 ### Runner-Token erneuern

@@ -314,12 +172,79 @@ ssh macmini "/usr/local/bin/docker compose \
  up -d --force-recreate gitea-runner"
 ```

-### Pipeline-Status prüfen
+### Pipeline-Status pruefen

 ```bash
 # 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"
+```
+
+## Health Checks
+
+### Production (Coolify)
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# Branch auf vorherigen Commit zuruecksetzen und pushen
+git reset --hard <previous-commit>
+git push gitea coolify --force
+```
+
+### Lokal (Mac Mini)
+
+```bash
+# 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"
 ```