Benjamin_Boenisch/breakpilot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all docs to reflect Coolify deployment model

Browse Source 
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>
This commit is contained in:
Benjamin Admin
2026-03-13 12:18:25 +01:00
parent 65177d3ff7
commit d1632fca17
4 changed files with 273 additions and 469 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
.claude/CLAUDE.md
View File

@@ -2,28 +2,38 @@
## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)
### Zwei-Rechner-Setup
### Zwei-Rechner-Setup + Coolify
| Geraet | Rolle | Aufgaben |
|--------|-------|----------|
| **MacBook** | Entwicklung | Claude Terminal, Code-Entwicklung, Browser (Frontend-Tests) |
| **Mac Mini** | Server | Docker, alle Services, Tests, Builds, Deployment |
| **Mac Mini** | Lokaler Server | Docker fuer lokale Dev/Tests (NICHT fuer Production!) |
| **Coolify** | Production | Automatisches Build + Deploy bei Push auf gitea |
**WICHTIG:** Code wird direkt auf dem MacBook in diesem Repo bearbeitet. Docker und Services laufen auf dem Mac Mini.
**WICHTIG:** Code wird direkt auf dem MacBook in diesem Repo bearbeitet. Production-Deployment laeuft automatisch ueber Coolify.
### Entwicklungsworkflow
### Entwicklungsworkflow (CI/CD — Coolify)
```bash
# 1. Code auf MacBook bearbeiten (dieses Verzeichnis)
# 2. Committen und pushen:
# 2. Committen und zu BEIDEN Remotes pushen:
git push origin main && git push gitea main
# 3. Auf Mac Mini pullen und Container neu bauen:
# 3. FERTIG! Push auf gitea triggert automatisch:
# - Gitea Actions: Tests
# - Coolify: Build → Deploy
```
**NIEMALS** manuell in Coolify auf "Redeploy" klicken — Gitea Actions triggert Coolify automatisch.
### Lokale Entwicklung (Mac Mini — optional, nur Dev/Tests)
```bash
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && git pull --no-rebase origin main"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service> && /usr/local/bin/docker compose up -d <service>"
```
### SSH-Verbindung (fuer Docker/Tests)
### SSH-Verbindung (fuer lokale Docker/Tests)
```bash
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && <cmd>"
@@ -51,6 +61,14 @@ networks:
name: breakpilot-network # Fixer Name, kein Auto-Prefix!
```
### Deployment-Modell
| Repo | Deployment | Trigger |
|------|-----------|---------|
| **breakpilot-core** | Coolify (automatisch) | Push auf gitea main |
| **breakpilot-compliance** | Coolify (automatisch) | Push auf gitea main |
| **breakpilot-lehrer** | Mac Mini (lokal) | Manuell docker compose |
---
## Haupt-URLs (via Nginx Reverse Proxy)
@@ -161,7 +179,7 @@ networks:
| `compliance` | Compliance | compliance_*, dsr, gdpr, sdk_tenants, consent_admin |
```bash
# DB-Zugang
# DB-Zugang (lokal)
ssh macmini "docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"
```
@@ -193,7 +211,14 @@ breakpilot-core/
## Haeufige Befehle
### Docker
### Deployment (CI/CD — Standardweg)
```bash
# Committen und pushen → Coolify deployt automatisch:
git push origin main && git push gitea main
```
### Lokale Docker-Befehle (Mac Mini — nur Dev/Tests)
```bash
# Alle Core-Services starten
@@ -211,31 +236,15 @@ ssh macmini "/usr/local/bin/docker ps --filter name=bp-core"
**WICHTIG:** Docker-Pfad auf Mac Mini ist `/usr/local/bin/docker` (nicht im Standard-SSH-PATH).
### Alle 3 Projekte starten
```bash
# 1. Core (MUSS zuerst!)
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"
# Warten auf Health:
ssh macmini "curl -sf http://127.0.0.1:8099/health"
# 2. Lehrer
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-lehrer && /usr/local/bin/docker compose up -d"
# 3. Compliance
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && /usr/local/bin/docker compose up -d"
```
### Git
```bash
# Zu BEIDEN Remotes pushen (PFLICHT!):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && git push all main"
git push origin main && git push gitea main
# Remotes:
# origin: lokale Gitea (macmini:3003)
# gitea: gitea.meghsakha.com
# all: beide gleichzeitig
```
---

185
docs-src/architecture/environments.md
View File

@@ -1,194 +1,77 @@
# Umgebungs-Architektur
## Übersicht
## Uebersicht
BreakPilot verwendet eine 3-Umgebungs-Strategie für sichere Entwicklung und Deployment:
BreakPilot verwendet zwei Umgebungen:
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Development │────▶│ Staging │────▶│ Production │
│ (develop) │ │ (staging) │ │ (main) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Tägliche Getesteter Code Produktionsreif
Entwicklung
┌─────────────────┐ ┌─────────────────┐
│ Development │───── git push ────▶│ Production │
│ (Mac Mini) │ │ (Coolify) │
└─────────────────┘ └─────────────────┘
Lokale Automatisch
Entwicklung via Coolify
```
## Umgebungen
### Development (Dev)
### Development (Lokal — Mac Mini)
**Zweck:** Tägliche Entwicklungsarbeit
**Zweck:** Lokale Entwicklung und Tests
| Eigenschaft | Wert |
|-------------|------|
| Git Branch | `develop` |
| Compose File | `docker-compose.yml` + `docker-compose.override.yml` (auto) |
| Env File | `.env.dev` |
| Database | `breakpilot_dev` |
| Git Branch | `main` |
| Compose File | `docker-compose.yml` |
| Database | Lokale PostgreSQL |
| Debug | Aktiviert |
| Hot-Reload | Aktiviert |
**Start:**
```bash
./scripts/start.sh dev
# oder einfach:
docker compose up -d
ssh macmini "cd ~/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"
```
### Staging
### Production (Coolify)
**Zweck:** Getesteter, freigegebener Code vor Produktion
| Eigenschaft | Wert |
|-------------|------|
| Git Branch | `staging` |
| Compose File | `docker-compose.yml` + `docker-compose.staging.yml` |
| Env File | `.env.staging` |
| Database | `breakpilot_staging` (separates Volume) |
| Debug | Deaktiviert |
| Hot-Reload | Deaktiviert |
**Start:**
```bash
./scripts/start.sh staging
# oder:
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d
```
### Production (Prod)
**Zweck:** Live-System für Endbenutzer (ab Launch)
**Zweck:** Live-System
| Eigenschaft | Wert |
|-------------|------|
| Git Branch | `main` |
| Compose File | `docker-compose.yml` + `docker-compose.prod.yml` |
| Env File | `.env.prod` (NICHT im Repository!) |
| Database | `breakpilot_prod` (separates Volume) |
| Deployment | Coolify (automatisch bei Push auf gitea) |
| Database | Externe PostgreSQL (TLS) |
| Debug | Deaktiviert |
| Vault | Pflicht (keine Env-Fallbacks) |
## Datenbank-Trennung
Jede Umgebung verwendet separate Docker Volumes für vollständige Datenisolierung:
```
┌─────────────────────────────────────────────────────────────┐
│ PostgreSQL Volumes │
├─────────────────────────────────────────────────────────────┤
│ breakpilot-dev_postgres_data │ Development Database │
│ breakpilot_staging_postgres │ Staging Database │
│ breakpilot_prod_postgres │ Production Database │
└─────────────────────────────────────────────────────────────┘
```
## Port-Mapping
Um mehrere Umgebungen gleichzeitig laufen zu lassen, verwenden sie unterschiedliche Ports:
| Service | Dev Port | Staging Port | Prod Port |
|---------|----------|--------------|-----------|
| Backend | 8000 | 8001 | 8000 |
| PostgreSQL | 5432 | 5433 | - (intern) |
| MinIO | 9000/9001 | 9002/9003 | - (intern) |
| Qdrant | 6333/6334 | 6335/6336 | - (intern) |
| Mailpit | 8025/1025 | 8026/1026 | - (deaktiviert) |
## Git Branching Strategie
```
main (Prod) ← Nur Release-Merges, geschützt
│
▼
staging ← Getesteter Code, Review erforderlich
│
▼
develop (Dev) ← Tägliche Arbeit, Default-Branch
│
▼
feature/* ← Feature-Branches (optional)
```
### Workflow
1. **Entwicklung:** Arbeite auf `develop`
2. **Code-Review:** Erstelle PR von Feature-Branch → `develop`
3. **Staging:** Promote `develop` → `staging` mit Tests
4. **Release:** Promote `staging` → `main` nach Freigabe
### Promotion-Befehle
**Deploy:**
```bash
# develop → staging
./scripts/promote.sh dev-to-staging
# staging → main (Production)
./scripts/promote.sh staging-to-prod
git push origin main && git push gitea main
# Coolify baut und deployt automatisch
```
## Secrets Management
### Development
- `.env.dev` enthält Entwicklungs-Credentials
- Vault optional (Dev-Token)
- Mailpit für E-Mail-Tests
### Staging
- `.env.staging` enthält Test-Credentials
- Vault empfohlen
- Mailpit für E-Mail-Sicherheit
### Production
- `.env.prod` NICHT im Repository
- Vault PFLICHT
- Echte SMTP-Konfiguration
Siehe auch: [Secrets Management](./secrets-management.md)
## Docker Compose Architektur
```
docker-compose.yml ← Basis-Konfiguration
docker-compose.yml ← Basis-Konfiguration (lokal, arm64)
│
├── docker-compose.override.yml ← Dev (auto-geladen)
│
├── docker-compose.staging.yml ← Staging (explizit)
│
└── docker-compose.prod.yml ← Production (explizit)
└── docker-compose.coolify.yml ← Production Override (amd64)
```
### Automatisches Laden
Coolify verwendet automatisch beide Compose-Files fuer den Production-Build.
Docker Compose lädt automatisch:
1. `docker-compose.yml`
2. `docker-compose.override.yml` (falls vorhanden)
## Secrets Management
Daher startet `docker compose up` automatisch die Dev-Umgebung.
### Development
- `.env` enthält Entwicklungs-Credentials
- Vault optional (Dev-Token)
- Mailpit für E-Mail-Tests
## Helper Scripts
### Production
- `.env` auf dem Server (nicht im Repository)
- Vault PFLICHT
- Echte SMTP-Konfiguration
| Script | Beschreibung |
|--------|--------------|
| `scripts/env-switch.sh` | Wechselt zwischen Umgebungen |
| `scripts/start.sh` | Startet Services für Umgebung |
| `scripts/stop.sh` | Stoppt Services |
| `scripts/promote.sh` | Promotet Code zwischen Branches |
| `scripts/status.sh` | Zeigt aktuellen Status |
## Verifikation
Nach Setup prüfen:
```bash
# Status anzeigen
./scripts/status.sh
# Branches prüfen
git branch -v
# Volumes prüfen
docker volume ls | grep breakpilot
```
Siehe auch: [Secrets Management](./secrets-management.md)
## Verwandte Dokumentation

467
docs-src/development/ci-cd-pipeline.md
View File

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

29
docs-src/index.md
View File

@@ -12,6 +12,14 @@ BreakPilot besteht aus drei unabhaengigen Projekten:
| **breakpilot-lehrer** | Bildungs-Stack (Team A) | `bp-lehrer-*` | Blau |
| **breakpilot-compliance** | DSGVO/Compliance-Stack (Team B) | `bp-compliance-*` | Lila |
### Deployment-Modell
| Repo | Deployment | Trigger |
|------|-----------|---------|
| **breakpilot-core** | Coolify (automatisch) | Push auf gitea main |
| **breakpilot-compliance** | Coolify (automatisch) | Push auf gitea main |
| **breakpilot-lehrer** | Mac Mini (lokal) | Manuell docker compose |
## Core Services
| Service | Container | Port | Beschreibung |
@@ -30,32 +38,11 @@ BreakPilot besteht aus drei unabhaengigen Projekten:
| Admin Core | bp-core-admin | 3008 | Admin-Dashboard (Next.js) |
| Health Aggregator | bp-core-health | 8099 | Service-Health Monitoring |
| Night Scheduler | bp-core-night-scheduler | 8096 | Nachtabschaltung |
| Pitch Deck | bp-core-pitch-deck | 3012 | Investor-Praesentation |
| Mailpit | bp-core-mailpit | 8025 | E-Mail (Entwicklung) |
| Gitea | bp-core-gitea | 3003 | Git-Server |
| Gitea Runner | bp-core-gitea-runner | - | CI/CD (Gitea Actions) |
| Jitsi (5 Container) | bp-core-jitsi-* | 8443 | Videokonferenzen |
## Nginx Routing-Tabelle
| Port | Upstream | Projekt |
|------|----------|---------|
| 443 | bp-lehrer-studio-v2:3001 | Lehrer |
| 3000 | bp-lehrer-website:3000 | Lehrer |
| 3002 | bp-lehrer-admin:3000 | Lehrer |
| 3006 | bp-compliance-developer-portal:3000 | Compliance |
| 3007 | bp-compliance-admin:3000 | Compliance |
| 3008 | bp-core-admin:3000 | Core |
| 8000 | bp-core-backend:8000 | Core |
| 8001 | bp-lehrer-backend:8001 | Lehrer |
| 8002 | bp-compliance-backend:8002 | Compliance |
| 8086 | bp-lehrer-klausur-service:8086 | Lehrer |
| 8087 | bp-core-embedding-service:8087 | Core |
| 8091 | bp-lehrer-voice-service:8091 | Lehrer |
| 8093 | bp-compliance-ai-sdk:8090 | Compliance |
| 8097 | bp-core-rag-service:8097 | Core |
| 8443 | bp-core-jitsi-web:80 | Core |
## Architektur
- [System-Architektur](architecture/system-architecture.md)