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

```yaml
# .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

```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

### 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

```bash
# 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

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

## 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"
```