From 4245e24980b02b23c2f552f403d07bb9dcd43091 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Thu, 5 Mar 2026 23:27:00 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20Woodpecker=20CI=20aus=20MkDocs=20entfer?= =?UTF-8?q?nt=20=E2=80=94=20Gitea=20Actions=20dokumentiert?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- docs-src/architecture/system-architecture.md | 4 +- docs-src/development/ci-cd-pipeline.md | 223 ++++++------------- docs-src/index.md | 2 +- 3 files changed, 76 insertions(+), 153 deletions(-) diff --git a/docs-src/architecture/system-architecture.md b/docs-src/architecture/system-architecture.md index b3fdbea..e28032c 100644 --- a/docs-src/architecture/system-architecture.md +++ b/docs-src/architecture/system-architecture.md @@ -38,7 +38,7 @@ BreakPilot ist eine modulare Bildungs- und Compliance-Plattform, aufgeteilt in d │ Jitsi (5x) │ │ BreakPilot Drive│ │ │ │ Night Scheduler │ │ │ │ │ │ Health Agg. │ │ │ │ │ -│ Gitea/Woodpecker│ │ │ │ │ +│ Gitea Actions │ │ │ │ │ │ ERP (optional) │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ @@ -67,7 +67,7 @@ Stellt gemeinsam genutzte Infrastruktur bereit. Beide Teams (Lehrer + Compliance | Frontend | Admin Core (Next.js, Port 3008) | | Networking | Nginx (Reverse Proxy + TLS) | | Monitoring | Health Aggregator | -| DevOps | Gitea, Woodpecker CI/CD, Night Scheduler, Mailpit | +| DevOps | Gitea, Gitea Actions (act_runner), Night Scheduler, Mailpit | | Kommunikation | Jitsi Meet (5 Container), Synapse (Matrix Chat) | | ERP | ERPNext (optional, 9 Container) | diff --git a/docs-src/development/ci-cd-pipeline.md b/docs-src/development/ci-cd-pipeline.md index b6d991e..193578d 100644 --- a/docs-src/development/ci-cd-pipeline.md +++ b/docs-src/development/ci-cd-pipeline.md @@ -17,39 +17,32 @@ ┌─────────────────────────────────────────────────────────────────┐ │ Entwickler-MacBook │ │ │ -│ breakpilot-pwa/ │ -│ ├── studio-v2/ (Next.js Frontend) │ -│ ├── admin-v2/ (Next.js Admin) │ -│ ├── backend/ (Python FastAPI) │ -│ ├── consent-service/ (Go Service) │ -│ ├── klausur-service/ (Python FastAPI) │ -│ ├── voice-service/ (Python FastAPI) │ -│ ├── ai-compliance-sdk/ (Go Service) │ +│ 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) │ │ │ -│ $ ./sync-and-deploy.sh │ +│ git push → Gitea Actions (automatisch) │ +│ oder manuell: git push && ssh macmini docker compose build │ └───────────────────────────────┬─────────────────────────────────┘ │ - │ rsync + SSH + │ git push origin main │ ▼ ┌─────────────────────────────────────────────────────────────────┐ -│ Mac Mini Server │ +│ Mac Mini Server (bp-core-*) │ │ │ │ Docker Compose │ -│ ├── website (Port 3000) │ -│ ├── studio-v2 (Port 3001) │ -│ ├── admin-v2 (Port 3002) │ -│ ├── backend (Port 8000) │ +│ ├── admin-core (Port 3008) │ +│ ├── backend-core (Port 8000) │ │ ├── consent-service (Port 8081) │ -│ ├── klausur-service (Port 8086) │ -│ ├── voice-service (Port 8082) │ -│ ├── ai-compliance-sdk (Port 8090) │ -│ ├── docs (Port 8009) │ -│ ├── postgres │ -│ ├── valkey (Redis) │ -│ ├── qdrant │ -│ └── minio │ +│ ├── billing-service (Port 8083) │ +│ ├── gitea (Port 3003) + gitea-runner (Gitea Actions) │ +│ ├── docs (Port 8011) │ +│ ├── postgres, valkey, qdrant, minio │ +│ └── vault, nginx, night-scheduler, health │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` @@ -67,8 +60,8 @@ rsync -avz --delete \ --exclude '__pycache__' \ --exclude 'venv' \ --exclude '.pytest_cache' \ - /Users/benjaminadmin/Projekte/breakpilot-pwa/ \ - macmini:/Users/benjaminadmin/Projekte/breakpilot-pwa/ + /Users/benjaminadmin/Projekte/breakpilot-core/ \ + macmini:/Users/benjaminadmin/Projekte/breakpilot-core/ ``` ### 2. Container bauen @@ -76,7 +69,7 @@ rsync -avz --delete \ ```bash # Einzelnen Service bauen ssh macmini "/usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ build --no-cache " # Beispiele: @@ -88,7 +81,7 @@ ssh macmini "/usr/local/bin/docker compose \ ```bash # Container neu starten ssh macmini "/usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ up -d " ``` @@ -97,7 +90,7 @@ ssh macmini "/usr/local/bin/docker compose \ ```bash # Container-Logs anzeigen ssh macmini "/usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ logs -f " ``` @@ -109,15 +102,15 @@ ssh macmini "/usr/local/bin/docker compose \ # 1. Sync rsync -avz --delete \ --exclude 'node_modules' --exclude '.next' --exclude '.git' \ - /Users/benjaminadmin/Projekte/breakpilot-pwa/studio-v2/ \ - macmini:/Users/benjaminadmin/Projekte/breakpilot-pwa/studio-v2/ + /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-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ build --no-cache studio-v2 && \ /usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ up -d studio-v2" ``` @@ -126,10 +119,10 @@ ssh macmini "/usr/local/bin/docker compose \ ```bash # Build mit requirements.txt ssh macmini "/usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ build klausur-service && \ /usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ up -d klausur-service" ``` @@ -138,10 +131,10 @@ ssh macmini "/usr/local/bin/docker compose \ ```bash # Multi-stage Build (Go → Alpine) ssh macmini "/usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ build --no-cache consent-service && \ /usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ up -d consent-service" ``` @@ -150,10 +143,10 @@ ssh macmini "/usr/local/bin/docker compose \ ```bash # Build & Deploy ssh macmini "/usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ build --no-cache docs && \ /usr/local/bin/docker compose \ - -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ up -d docs" # Verfügbar unter: http://macmini:8009 @@ -178,10 +171,10 @@ curl -s http://macmini:8090/health ```bash # Letzte 100 Zeilen -ssh macmini "docker logs --tail 100 breakpilot-pwa-backend-1" +ssh macmini "docker logs --tail 100 breakpilot-core-backend-1" # Live-Logs folgen -ssh macmini "docker logs -f breakpilot-pwa-backend-1" +ssh macmini "docker logs -f breakpilot-core-backend-1" ``` ## Rollback @@ -190,15 +183,15 @@ ssh macmini "docker logs -f breakpilot-pwa-backend-1" ```bash # 1. Aktuelles Image taggen -ssh macmini "docker tag breakpilot-pwa-backend:latest breakpilot-pwa-backend:backup" +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-pwa/docker-compose.yml \ + -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml \ up -d backend" # 3. Bei Problemen: Backup wiederherstellen -ssh macmini "docker tag breakpilot-pwa-backend:backup breakpilot-pwa-backend:latest" +ssh macmini "docker tag breakpilot-core-backend:backup breakpilot-core-backend:latest" ``` ## Troubleshooting @@ -207,13 +200,13 @@ ssh macmini "docker tag breakpilot-pwa-backend:backup breakpilot-pwa-backend:lat ```bash # 1. Logs prüfen -ssh macmini "docker logs breakpilot-pwa--1" +ssh macmini "docker logs breakpilot-core--1" # 2. Container manuell starten für Debug-Output ssh macmini "docker compose -f .../docker-compose.yml run --rm " # 3. In Container einloggen -ssh macmini "docker exec -it breakpilot-pwa--1 /bin/sh" +ssh macmini "docker exec -it breakpilot-core--1 /bin/sh" ``` ### Port bereits belegt @@ -276,127 +269,57 @@ services: - `.env` Datei auf dem Server pflegen - Secrets über HashiCorp Vault (siehe unten) -## Woodpecker CI - Automatisierte OAuth Integration +## Gitea Actions ### Überblick -Die OAuth-Integration zwischen Woodpecker CI und Gitea ist **vollständig automatisiert**. Credentials werden in HashiCorp Vault gespeichert und bei Bedarf automatisch regeneriert. +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. -!!! info "Warum automatisiert?" - Diese Automatisierung ist eine DevSecOps Best Practice: +| Komponente | Container | Beschreibung | +|------------|-----------|--------------| +| Gitea | `bp-core-gitea` (Port 3003) | Git-Server + Actions-Trigger | +| Gitea Runner | `bp-core-gitea-runner` | Führt Actions-Workflows aus | - - **Infrastructure-as-Code**: Alles ist reproduzierbar - - **Disaster Recovery**: Verlorene Credentials können automatisch regeneriert werden - - **Security**: Secrets werden zentral in Vault verwaltet - - **Onboarding**: Neue Entwickler müssen nichts manuell konfigurieren +### Pipeline-Konfiguration -### Architektur +Workflows liegen im Repo unter `.gitea/workflows/`: -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Mac Mini Server │ -│ │ -│ ┌───────────────┐ OAuth 2.0 ┌───────────────┐ │ -│ │ Gitea │ ←─────────────────────────→│ Woodpecker │ │ -│ │ (Port 3003) │ Client ID + Secret │ (Port 8090) │ │ -│ └───────────────┘ └───────────────┘ │ -│ │ │ │ -│ │ OAuth App │ Env Vars│ -│ │ (DB: oauth2_application) │ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌───────────────────────────────────────────────────────────┐ │ -│ │ HashiCorp Vault (Port 8200) │ │ -│ │ │ │ -│ │ secret/cicd/woodpecker: │ │ -│ │ - gitea_client_id │ │ -│ │ - gitea_client_secret │ │ -│ │ │ │ -│ │ secret/cicd/api-tokens: │ │ -│ │ - gitea_token (für API-Zugriff) │ │ -│ │ - woodpecker_token (für Pipeline-Trigger) │ │ -│ └───────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ +```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 ``` -### Credentials-Speicherorte - -| Ort | Pfad | Inhalt | -|-----|------|--------| -| **HashiCorp Vault** | `secret/cicd/woodpecker` | Client ID + Secret (Quelle der Wahrheit) | -| **.env Datei** | `WOODPECKER_GITEA_CLIENT/SECRET` | Für Docker Compose (aus Vault geladen) | -| **Gitea PostgreSQL** | `oauth2_application` Tabelle | OAuth App Registration (gehashtes Secret) | - -### Troubleshooting: OAuth Fehler - -Falls der Fehler "Client ID not registered" oder "user does not exist [uid: 0]" auftritt: +### Runner-Token erneuern ```bash -# Option 1: Automatisches Regenerieren (empfohlen) -./scripts/sync-woodpecker-credentials.sh --regenerate +# Runner-Token in Gitea UI generieren: +# https://macmini:3003 → Settings → Actions → Runners → New Runner -# Option 2: Manuelles Vorgehen -# 1. Credentials aus Vault laden -vault kv get secret/cicd/woodpecker +# Token in .env setzen: +GITEA_RUNNER_TOKEN= -# 2. .env aktualisieren -WOODPECKER_GITEA_CLIENT= -WOODPECKER_GITEA_SECRET= - -# 3. Zu Mac Mini synchronisieren -rsync .env macmini:~/Projekte/breakpilot-pwa/ - -# 4. Woodpecker neu starten -ssh macmini "cd ~/Projekte/breakpilot-pwa && \ - docker compose up -d --force-recreate woodpecker-server" +# 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" ``` -### Das Sync-Script - -Das Script `scripts/sync-woodpecker-credentials.sh` automatisiert den gesamten Prozess: +### Pipeline-Status prüfen ```bash -# Credentials aus Vault laden und .env aktualisieren -./scripts/sync-woodpecker-credentials.sh +# Runner-Logs +ssh macmini "/usr/local/bin/docker logs -f bp-core-gitea-runner" -# Neue Credentials generieren (OAuth App in Gitea + Vault + .env) -./scripts/sync-woodpecker-credentials.sh --regenerate -``` - -Was das Script macht: - -1. **Liest** die aktuellen Credentials aus Vault -2. **Aktualisiert** die .env Datei automatisch -3. **Bei `--regenerate`**: - - Löscht alte OAuth Apps in Gitea - - Erstellt neue OAuth App mit neuem Client ID/Secret - - Speichert Credentials in Vault - - Aktualisiert .env - -### Vault-Zugriff - -```bash -# Vault Token (Development) -export VAULT_TOKEN=breakpilot-dev-token - -# Credentials lesen -docker exec -e VAULT_TOKEN=$VAULT_TOKEN breakpilot-pwa-vault \ - vault kv get secret/cicd/woodpecker - -# Credentials setzen -docker exec -e VAULT_TOKEN=$VAULT_TOKEN breakpilot-pwa-vault \ - vault kv put secret/cicd/woodpecker \ - gitea_client_id="..." \ - gitea_client_secret="..." -``` - -### Services neustarten nach Credentials-Änderung - -```bash -# Wichtig: --force-recreate um neue Env Vars zu laden -cd /Users/benjaminadmin/Projekte/breakpilot-pwa -docker compose up -d --force-recreate woodpecker-server - -# Logs prüfen -docker logs breakpilot-pwa-woodpecker-server --tail 50 +# Laufende Jobs +ssh macmini "/usr/local/bin/docker exec bp-core-gitea-runner act_runner list" ``` diff --git a/docs-src/index.md b/docs-src/index.md index 4a0411e..441b2a9 100644 --- a/docs-src/index.md +++ b/docs-src/index.md @@ -33,7 +33,7 @@ BreakPilot besteht aus drei unabhaengigen Projekten: | Pitch Deck | bp-core-pitch-deck | 3012 | Investor-Praesentation | | Mailpit | bp-core-mailpit | 8025 | E-Mail (Entwicklung) | | Gitea | bp-core-gitea | 3003 | Git-Server | -| Woodpecker | bp-core-woodpecker-server | 8090 | CI/CD | +| Gitea Runner | bp-core-gitea-runner | - | CI/CD (Gitea Actions) | | Jitsi (5 Container) | bp-core-jitsi-* | 8443 | Videokonferenzen | ## Nginx Routing-Tabelle