# Plan: Umstrukturierung der lokalen Entwicklungsumgebung nach Stack-Pattern

**Datum**: 2025-11-04  
**Ziel**: Lokale Entwicklungsumgebung in `deployment/stacks/local/` strukturieren, konsistent mit `application` und `staging` Stacks

## Aktuelle Struktur

### Root-Level (aktuell)
```
Repository Root/
??? docker-compose.base.yml      # Gemeinsame Basis
??? docker-compose.local.yml     # Local Override
??? docker-compose.staging.yml   # Staging Override (im Root)
??? docker-compose.production.yml # Production Override (im Root)
??? secrets/                     # (neu, f?r lokale Secrets)
```

### Stacks-Struktur (aktuell)
```
deployment/stacks/
??? application/                 # Production Stack
?   ??? docker-compose.yml       # Vollst?ndige Definition
?   ??? README.md
??? staging/                     # Staging Stack (nur nginx config)
?   ??? nginx/conf.d/
?   ??? README.md
??? postgresql/                  # PostgreSQL Stack
    ??? docker-compose.yml
```

## Zielstruktur

### Root-Level (nach Migration)
```
Repository Root/
??? docker-compose.base.yml      # Gemeinsame Basis (bleibt)
??? docker-compose.staging.yml   # Staging Override (bleibt im Root)
??? docker-compose.production.yml # Production Override (bleibt im Root)
??? docker-compose.postgres-override.yml # (bleibt)
```

### Stacks-Struktur (nach Migration)
```
deployment/stacks/
??? application/                 # Production Stack
?   ??? docker-compose.yml
?   ??? README.md
??? staging/                     # Staging Stack
?   ??? nginx/conf.d/
?   ??? README.md
??? local/                       # Local Development Stack (NEU)
?   ??? docker-compose.yml      # Vollst?ndige Local-Konfiguration
?   ??? secrets/                 # Lokale Secrets
?   ?   ??? redis_password.txt.example
?   ?   ??? db_user_password.txt.example
?   ?   ??? app_key.txt.example
?   ??? scripts/                 # Helper-Scripts
?   ?   ??? setup-secrets.sh
?   ?   ??? migrate-env-to-secrets.sh
?   ??? README.md                # Local Development Dokumentation
??? postgresql/
    ??? docker-compose.yml
```

## Vorteile der Umstrukturierung

### 1. Konsistenz
- ? **Gleiche Struktur** wie `application` und andere Stacks
- ? **Klare Trennung** der Umgebungen
- ? **Einheitliches Pattern** f?r alle Stacks

### 2. Organisation
- ? **Lokale Konfiguration** klar als "Stack" erkennbar
- ? **Secrets lokal** verwaltet (nicht im Root)
- ? **Helper-Scripts** am richtigen Ort

### 3. Wartbarkeit
- ? **Einheitliche Struktur** erleichtert Wartung
- ? **Klare Verantwortlichkeiten** pro Stack
- ? **Einfachere Navigation** f?r Entwickler

### 4. Deployment-Konsistenz
- ? **Gleiche Kommandos** f?r alle Stacks
- ? **Einheitliche Dokumentation**
- ? **Konsistente Pfade**

## Implementierungsplan

### Phase 1: Verzeichnisstruktur erstellen

```bash
mkdir -p deployment/stacks/local/secrets
mkdir -p deployment/stacks/local/scripts
chmod 700 deployment/stacks/local/secrets
```

### Phase 2: docker-compose.yml migrieren

**Von**: `docker-compose.base.yml + docker-compose.local.yml` (Root)  
**Nach**: `deployment/stacks/local/docker-compose.yml` (vollst?ndige Definition)

**Struktur**:
```yaml
# deployment/stacks/local/docker-compose.yml
# Local Development Stack
# Usage: docker compose -f deployment/stacks/local/docker-compose.yml up

services:
  web:
    # ... (aus base.yml + local.yml kombiniert)
  
  php:
    # ... mit Secrets und *_FILE Pattern
  
  redis:
    # ... mit Passwort (Docker Secrets)
  
  # ... weitere Services

secrets:
  # ... lokale Secrets

networks:
  # ... lokale Netzwerke
```

### Phase 3: Secrets-Verwaltung

**Struktur**:
```
deployment/stacks/local/
??? secrets/
?   ??? redis_password.txt.example    # Beispiel
?   ??? db_user_password.txt.example  # Beispiel
?   ??? app_key.txt.example           # Beispiel
??? .gitignore                        # secrets/*.txt
```

**Secrets-Pfade in docker-compose.yml**:
```yaml
secrets:
  redis_password:
    file: ./secrets/redis_password.txt
    external: false
```

### Phase 4: Helper-Scripts

**scripts/setup-secrets.sh**:
```bash
#!/bin/bash
# Setup local development secrets
cd "$(dirname "$0")/.."  # Zu deployment/stacks/local/
# ... Secrets generieren
```

**scripts/migrate-env-to-secrets.sh**:
```bash
#!/bin/bash
# Migriert Secrets aus .env.local zu secrets/
cd "$(dirname "$0")/.."  # Zu deployment/stacks/local/
# ... Migration durchf?hren
```

### Phase 5: Dokumentation

**deployment/stacks/local/README.md**:
- Setup-Anleitung
- Secrets-Verwaltung
- Verwendung
- Troubleshooting

## Vergleich der Ans?tze

### Ansatz A: Vollst?ndige docker-compose.yml (empfohlen)

**Struktur**:
```yaml
# deployment/stacks/local/docker-compose.yml
# Vollst?ndige Definition (wie application Stack)
services:
  web: ...
  php: ...
  redis: ...
```

**Vorteile**:
- ? Konsistent mit `application` Stack
- ? Vollst?ndige Kontrolle
- ? Keine Abh?ngigkeit von Root-Level base.yml

**Nachteile**:
- ?? Etwas mehr Code-Duplikation (aber klar getrennt)

### Ansatz B: Base + Override Pattern (wie Staging)

**Struktur**:
```yaml
# deployment/stacks/local/docker-compose.base.yml (oder Link)
# deployment/stacks/local/docker-compose.local.yml
```

**Vorteile**:
- ? Weniger Duplikation
- ? Konsistent mit Staging-Pattern

**Nachteile**:
- ?? Pfad-Abh?ngigkeiten (base.yml muss relativ erreichbar sein)
- ?? Komplexer bei verschiedenen Pfaden

## Empfehlung: Ansatz A (Vollst?ndige Definition)

**Begr?ndung**:
1. **Konsistenz**: Gleiche Struktur wie `application` Stack
2. **Autonomie**: Local Stack ist vollst?ndig unabh?ngig
3. **Klarheit**: Alles in einem Verzeichnis
4. **Einfachheit**: Keine Pfad-Abh?ngigkeiten

## Detaillierte Struktur

### deployment/stacks/local/docker-compose.yml

**Enth?lt**:
- Alle Services aus `docker-compose.base.yml` + `docker-compose.local.yml`
- Redis mit Passwort (Docker Secrets)
- `*_FILE` Pattern f?r alle Secrets
- Lokale Ports (8888:80, 443:443, 5433:5432)
- Host-Mounts f?r Entwicklung
- Debug-Flags

**Services**:
- `web` (Nginx)
- `php` (PHP-FPM)
- `db` (PostgreSQL)
- `redis` (mit Passwort)
- `queue-worker`
- `minio` (optional)

### deployment/stacks/local/secrets/

**Dateien**:
- `redis_password.txt` (gitignored)
- `db_user_password.txt` (gitignored)
- `app_key.txt` (gitignored)
- `*.example` (versioniert, als Beispiele)

### deployment/stacks/local/scripts/

**Scripts**:
- `setup-secrets.sh` - Generiert Secrets f?r neue Entwickler
- `migrate-env-to-secrets.sh` - Migriert bestehende .env.local
- `redis-cli.sh` - Helper f?r Redis-CLI mit Passwort

## Migration

### Schritt 1: Neue Struktur erstellen
```bash
mkdir -p deployment/stacks/local/{secrets,scripts}
```

### Schritt 2: docker-compose.yml erstellen
- Kombiniere `docker-compose.base.yml` + `docker-compose.local.yml`
- F?ge Secrets-Konfiguration hinzu
- F?ge Redis-Passwort hinzu

### Schritt 3: Secrets migrieren
- Erstelle `secrets/` Verzeichnis
- Generiere oder migriere Secrets
- Erstelle Beispiel-Dateien

### Schritt 4: Scripts erstellen
- Setup-Script
- Migration-Script
- Helper-Scripts

### Schritt 5: Dokumentation
- README.md erstellen
- ENV_SETUP.md aktualisieren
- Haupt-README aktualisieren

### Schritt 6: Alte Dateien entfernen
- `docker-compose.local.yml` im Root (nach Migration)
- Root-Level `secrets/` (falls vorhanden)

## Verwendung nach Migration

### Vorher (aktuell)
```bash
docker compose -f docker-compose.base.yml -f docker-compose.local.yml up
```

### Nachher (neu)
```bash
cd deployment/stacks/local
docker compose up -d
```

**Oder vom Root**:
```bash
docker compose -f deployment/stacks/local/docker-compose.yml up -d
```

## Vorteile dieser Struktur

1. ? **Konsistenz**: Gleiche Struktur wie `application` Stack
2. ? **Autonomie**: Local Stack ist vollst?ndig unabh?ngig
3. ? **Organisation**: Alles Local-Development in einem Verzeichnis
4. ? **Klarheit**: Klare Trennung der Umgebungen
5. ? **Wartbarkeit**: Einfacher zu warten und zu erweitern

## Nachteile / ?berlegungen

### 1. Pfad-Abh?ngigkeiten
- ?? **Build-Kontexte**: M?ssen relativ zum Repository-Root sein
- **L?sung**: Absolute Pfade oder `context: ../..` verwenden

### 2. Migration
- ?? **Bestehende Entwickler** m?ssen umstellen
- **L?sung**: Migration-Script und Dokumentation

### 3. Docker Compose Befehle
- ?? **Andere Pfade** als bisher
- **L?sung**: Helper-Script oder Makefile-Target

## Alternative: Makefile-Targets

**Makefile hinzuf?gen**:
```makefile
local-up:
	cd deployment/stacks/local && docker compose up -d

local-down:
	cd deployment/stacks/local && docker compose down

local-logs:
	cd deployment/stacks/local && docker compose logs -f

local-ps:
	cd deployment/stacks/local && docker compose ps
```

**Verwendung**:
```bash
make local-up
make local-logs
make local-ps
```

## N?chste Schritte

1. ? Plan erstellt
2. ? Diskussion: Ist Stack-Struktur gew?nscht?
3. ? Implementierung: Verzeichnisstruktur erstellen
4. ? docker-compose.yml migrieren und anpassen
5. ? Secrets-System implementieren
6. ? Scripts erstellen
7. ? Dokumentation
8. ? Testing
9. ? Alte Dateien entfernen