breakpilot-core/docs-src/architecture/environments.md

Umgebungs-Architektur

Übersicht

BreakPilot verwendet eine 3-Umgebungs-Strategie für sichere Entwicklung und Deployment:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Development   │────▶│     Staging     │────▶│   Production    │
│   (develop)     │     │    (staging)    │     │     (main)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
     Tägliche            Getesteter Code         Produktionsreif
     Entwicklung

Umgebungen

Development (Dev)

Zweck: Tägliche Entwicklungsarbeit

Eigenschaft	Wert
Git Branch	develop
Compose File	docker-compose.yml + docker-compose.override.yml (auto)
Env File	.env.dev
Database	breakpilot_dev
Debug	Aktiviert
Hot-Reload	Aktiviert

Start:

./scripts/start.sh dev
# oder einfach:
docker compose up -d

Staging

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:

./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)

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

# develop → staging
./scripts/promote.sh dev-to-staging

# staging → main (Production)
./scripts/promote.sh staging-to-prod

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

Docker Compose Architektur

docker-compose.yml              ← Basis-Konfiguration
        │
        ├── docker-compose.override.yml  ← Dev (auto-geladen)
        │
        ├── docker-compose.staging.yml   ← Staging (explizit)
        │
        └── docker-compose.prod.yml      ← Production (explizit)

Automatisches Laden

Docker Compose lädt automatisch:

1. docker-compose.yml
2. docker-compose.override.yml (falls vorhanden)

Daher startet docker compose up automatisch die Dev-Umgebung.

Helper Scripts

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:

# Status anzeigen
./scripts/status.sh

# Branches prüfen
git branch -v

# Volumes prüfen
docker volume ls | grep breakpilot

Verwandte Dokumentation

• Secrets Management - Vault & Secrets
• DevSecOps - CI/CD & Security
• System-Architektur - Gesamtarchitektur