breakpilot-pwa/docs/guides/environment-setup.md

Entwickler-Guide: Umgebungs-Setup

Dieser Guide erklärt das tägliche Arbeiten mit den Dev/Staging/Prod-Umgebungen.

Schnellstart

# 1. Wechsle in das Projektverzeichnis
cd /Users/benjaminadmin/Projekte/breakpilot-pwa

# 2. Starte die Entwicklungsumgebung
./scripts/start.sh dev

# 3. Prüfe den Status
./scripts/status.sh

Täglicher Workflow

Morgens: Entwicklung starten

# Auf develop-Branch wechseln
git checkout develop

# Neueste Änderungen holen (falls Remote konfiguriert)
git pull origin develop

# Umgebung starten
./scripts/start.sh dev

Während der Arbeit

# Logs eines Services anzeigen
docker compose logs -f backend

# Service neustarten
docker compose restart backend

# Status prüfen
./scripts/status.sh

Änderungen committen

# Änderungen anzeigen
git status

# Dateien hinzufügen
git add .

# Commit erstellen
git commit -m "Feature: Beschreibung der Änderung"

Abends: Umgebung stoppen

./scripts/stop.sh dev

Umgebung wechseln

Von Dev zu Staging

# Stoppe Dev
./scripts/stop.sh dev

# Starte Staging
./scripts/start.sh staging

Zurück zu Dev

./scripts/stop.sh staging
./scripts/start.sh dev

Code promoten

Dev → Staging (nach erfolgreichem Test)

# Stelle sicher, dass alle Änderungen committet sind
git status

# Promote zu Staging
./scripts/promote.sh dev-to-staging

# Push zu Remote (falls konfiguriert)
git push origin staging

Staging → Production (Release)

# Nur nach vollständigem Test auf Staging!
./scripts/promote.sh staging-to-prod

# Push zu Remote
git push origin main

Nützliche Befehle

Docker

# Alle Container anzeigen
docker compose ps

# Logs folgen
docker compose logs -f [service]

# In Container einsteigen
docker compose exec backend bash
docker compose exec postgres psql -U breakpilot -d breakpilot_dev

# Container neustarten
docker compose restart [service]

# Alle Container stoppen und entfernen
docker compose down

# Mit Volumes löschen (VORSICHT!)
docker compose down -v

Git

# Aktuellen Branch anzeigen
git branch --show-current

# Alle Branches anzeigen
git branch -v

# Änderungen zwischen Branches anzeigen
git diff develop..staging

Datenbank

# Direkt mit PostgreSQL verbinden (Dev)
docker compose exec postgres psql -U breakpilot -d breakpilot_dev

# Backup erstellen
./scripts/backup.sh

# Backup wiederherstellen
./scripts/restore.sh backup-file.sql.gz

Häufige Probleme

"Port already in use"

Ein anderer Prozess oder Container verwendet den Port.

# Laufende Container prüfen
docker ps

# Alte Container stoppen
docker compose down

# Prozess auf Port finden (z.B. 8000)
lsof -i :8000

Container startet nicht

# Logs prüfen
docker compose logs backend

# Container neu bauen
docker compose build backend
docker compose up -d backend

Datenbank-Verbindungsfehler

# Prüfen ob PostgreSQL läuft
docker compose ps postgres

# PostgreSQL-Logs prüfen
docker compose logs postgres

# Neustart
docker compose restart postgres

Falsche Umgebung aktiv

# Status prüfen
./scripts/status.sh

# Auf richtige Umgebung wechseln
./scripts/env-switch.sh dev

Umgebungs-Dateien

Datei	Beschreibung	Im Git?
.env	Aktive Umgebung	Nein
.env.dev	Development Werte	Ja
.env.staging	Staging Werte	Ja
.env.prod	Production Werte	NEIN
.env.example	Template	Ja

Ports Übersicht

Development

Service	Port	URL
Backend	8000	http://localhost:8000
Website	3000	http://localhost:3000
Consent Service	8081	http://localhost:8081
PostgreSQL	5432	localhost:5432
Mailpit UI	8025	http://localhost:8025
MinIO Console	9001	http://localhost:9001

Staging

Service	Port	URL
Backend	8001	http://localhost:8001
PostgreSQL	5433	localhost:5433
Mailpit UI	8026	http://localhost:8026
MinIO Console	9003	http://localhost:9003

Hilfe

# Status und Übersicht
./scripts/status.sh

# Script-Hilfe
./scripts/env-switch.sh --help
./scripts/promote.sh --help

Verwandte Dokumentation

• Architektur: Umgebungen
• Secrets Management
• System-Architektur