2498b0eb1f
- CLAUDE.md: Comprehensive documentation for core infrastructure - docs-src: Cleaned 316MB junk, kept only markdown docs - mkdocs.yml: Updated nav for core-only content - nginx: Docs proxy targets split (3002->lehrer, 3007->compliance) - docker-compose: Fixed docs port mapping (8009:80), added INSTALL_LOCK - .claude/rules: testing, documentation, open-source-policy, night-scheduler Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
8.7 KiB
8.7 KiB
BreakPilot Core - Shared Infrastructure
Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)
Zwei-Rechner-Setup
| Geraet | Rolle | Aufgaben |
|---|---|---|
| MacBook | Client | Claude Terminal, Browser (Frontend-Tests) |
| Mac Mini | Server | Docker, alle Services, Code-Ausfuehrung, Tests, Git |
WICHTIG: Die Entwicklung findet vollstaendig auf dem Mac Mini statt!
SSH-Verbindung
ssh macmini
# Projektverzeichnis:
cd /Users/benjaminadmin/Projekte/breakpilot-core
# Einzelbefehle (BEVORZUGT):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && <cmd>"
Projekt-Kontext
breakpilot-core ist das Infrastruktur-Fundament der BreakPilot-Plattform. Es stellt alle gemeinsamen Services bereit, die von breakpilot-lehrer und breakpilot-compliance genutzt werden.
3-Projekt-Architektur
breakpilot-core (dieses Repo — MUSS ZUERST starten)
├── breakpilot-lehrer (haengt von Core ab)
└── breakpilot-compliance (haengt von Core ab)
Alle 3 Projekte teilen sich ein Docker-Netzwerk:
networks:
breakpilot-network:
driver: bridge
name: breakpilot-network # Fixer Name, kein Auto-Prefix!
Haupt-URLs (via Nginx Reverse Proxy)
Core-eigene Services
| URL | Service | Beschreibung |
|---|---|---|
| https://macmini:8000/ | backend-core | Shared APIs (Auth, RBAC, Notifications) |
| https://macmini:8097/ | rag-service | Semantische Suche, Dokument-Upload |
| https://macmini:8443/ | Jitsi Meet | Videokonferenzen |
| http://macmini:8099/ | health-aggregator | Health-Check aller Services |
Interne Dienste (kein HTTPS)
| URL | Service | Beschreibung |
|---|---|---|
| http://macmini:3003/ | Gitea | Git-Server (User: pilotadmin) |
| http://macmini:8090/ | Woodpecker CI | CI/CD Server |
| http://macmini:8200/ | Vault | Secrets Management |
| http://macmini:8025/ | Mailpit | E-Mail (Dev) |
| http://macmini:9001/ | MinIO Console | S3 Storage UI |
| http://macmini:8096/ | Night Scheduler | Auto-Shutdown/Startup |
| http://macmini:8089/ | Camunda | BPMN Engine |
Nginx-Proxy fuer Lehrer/Compliance (durchgereicht)
| URL | Projekt | Service |
|---|---|---|
| https://macmini/ | Lehrer | Studio v2 |
| https://macmini:3000/ | Lehrer | Website |
| https://macmini:3002/ | Lehrer | Admin Lehrer |
| https://macmini:3007/ | Compliance | Admin Compliance |
| https://macmini:8001/ | Lehrer | Backend Lehrer |
| https://macmini:8002/ | Compliance | Backend Compliance |
| https://macmini:8086/ | Lehrer | Klausur-Service |
| https://macmini:8093/ | Compliance | AI Compliance SDK |
Services (~28 Container)
Infrastruktur
| Service | Tech | Port | Container |
|---|---|---|---|
| nginx | Nginx | 80/443 + viele | bp-core-nginx |
| postgres | PostGIS 16 | 5432 | bp-core-postgres |
| valkey | Valkey 8 | 6379 | bp-core-valkey |
| vault | HashiCorp Vault | 8200 | bp-core-vault |
| vault-agent | Vault | - | bp-core-vault-agent |
| qdrant | Qdrant | 6333/6334 | bp-core-qdrant |
| minio | MinIO | 9000/9001 | bp-core-minio |
| mailpit | Mailpit | 8025/1025 | bp-core-mailpit |
Shared Backend-Services
| Service | Tech | Port | Container |
|---|---|---|---|
| backend-core | Python/FastAPI | 8000 | bp-core-backend |
| rag-service | Python/FastAPI | 8097 | bp-core-rag-service |
| embedding-service | Python/FastAPI | 8087 | bp-core-embedding-service |
| consent-service | Go/Gin | 8081 | bp-core-consent-service |
| billing-service | Go | 8083 | bp-core-billing-service |
| health-aggregator | Python/FastAPI | 8099 | bp-core-health |
| night-scheduler | Python/FastAPI | 8096 | bp-core-night-scheduler |
Kommunikation
| Service | Tech | Container |
|---|---|---|
| jitsi-web | Jitsi | bp-core-jitsi-web |
| jitsi-xmpp | Prosody | bp-core-jitsi-xmpp |
| jitsi-jicofo | Jicofo | bp-core-jitsi-jicofo |
| jitsi-jvb | JVB | bp-core-jitsi-jvb |
| synapse + synapse-db | Matrix | bp-core-synapse (Profil: chat) |
DevOps
| Service | Tech | Port | Container |
|---|---|---|---|
| gitea | Gitea | 3003 | bp-core-gitea |
| gitea-runner | Gitea Actions | - | bp-core-gitea-runner |
| woodpecker-server | Woodpecker | 8090 | bp-core-woodpecker-server |
| woodpecker-agent | Woodpecker | - | bp-core-woodpecker-agent |
| camunda | Camunda | 8089 | bp-core-camunda (Profil: bpmn) |
Profile (nur bei Bedarf starten)
| Profil | Services | Start mit |
|---|---|---|
| chat | synapse, synapse-db | --profile chat |
| erp | erpnext-* (7 Container) | --profile erp |
| bpmn | camunda | --profile bpmn |
| docs | docs (MkDocs) | --profile docs |
| backup | pg-backup | --profile backup |
Datenbank
3 Schemas (shared PostgreSQL)
| Schema | Projekt | Tabellen |
|---|---|---|
core |
Core | users, sessions, auth, rbac, notifications, email_templates, billing |
lehrer |
Lehrer | classroom, units, klausuren, vocab, game, meetings, messenger |
compliance |
Compliance | compliance_*, dsr, gdpr, sdk_tenants, consent_admin |
# DB-Zugang
ssh macmini "docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"
Verzeichnisstruktur
breakpilot-core/
├── .claude/
│ ├── CLAUDE.md # Diese Datei
│ └── rules/ # Automatische Regeln
├── backend-core/ # Python/FastAPI (Auth, RBAC, Notifications)
├── rag-service/ # Python/FastAPI (Qdrant, MinIO, Embeddings)
├── embedding-service/ # Python/FastAPI (Sentence-Transformers)
├── consent-service/ # Go/Gin (Consent-Management)
├── billing-service/ # Go (Abrechnungsservice)
├── night-scheduler/ # Python/FastAPI (Auto-Shutdown)
├── nginx/conf.d/ # Nginx Reverse Proxy Config
├── vault/ # Vault Config + TLS Certs
├── gitea/ # Gitea Config
├── docs-src/ # MkDocs Quellen
├── mkdocs.yml # MkDocs Config
├── scripts/ # Helper Scripts
└── docker-compose.yml # Haupt-Compose (28+ Services)
Haeufige Befehle
Docker
# Alle Core-Services starten
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"
# Einzelnen Service neu bauen
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service>"
# Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-<service>"
# Status
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
# 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
# Zu BEIDEN Remotes pushen (PFLICHT!):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && git push all main"
# Remotes:
# origin: lokale Gitea (macmini:3003)
# gitea: gitea.meghsakha.com
# all: beide gleichzeitig
Kernprinzipien
1. Open Source Policy
- NUR Open Source mit kommerziell nutzbarer Lizenz
- Erlaubt: MIT, Apache-2.0, BSD, ISC, MPL-2.0, LGPL
- VERBOTEN: GPL (ausser LGPL), AGPL, proprietaer
2. Testing & Dokumentation
- Tests sind Pflicht bei jeder Aenderung
- MkDocs aktualisieren:
--profile docsstarten
3. Sensitive Dateien
NIEMALS aendern oder committen:
.env,.env.local, Vault-Tokens, SSL-Zertifikate*.pdf,*.docx, kompilierte Binaries, grosse Medien
Nginx Port-Zuordnung (Uebersicht)
| Port | Ziel-Container | Projekt |
|---|---|---|
| 443 | bp-lehrer-studio-v2 | Lehrer |
| 3000 | bp-lehrer-website | Lehrer |
| 3002 | bp-lehrer-admin | Lehrer |
| 3006 | bp-compliance-developer-portal | Compliance |
| 3007 | bp-compliance-admin | Compliance |
| 8000 | bp-core-backend | Core |
| 8001 | bp-lehrer-backend | Lehrer |
| 8002 | bp-compliance-backend | Compliance |
| 8086 | bp-lehrer-klausur-service | Lehrer |
| 8087 | bp-core-embedding-service | Core |
| 8089 | bp-core-camunda | Core |
| 8091 | bp-lehrer-voice-service | Lehrer |
| 8093 | bp-compliance-ai-sdk | Compliance |
| 8097 | bp-core-rag-service | Core |
| 8443 | bp-core-jitsi-web | Core |