michaelschiemer/docs/deployment/local-stack-restructure-plan.md

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

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:

# 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:

secrets:
  redis_password:
    file: ./secrets/redis_password.txt
    external: false

Phase 4: Helper-Scripts

scripts/setup-secrets.sh:

#!/bin/bash
# Setup local development secrets
cd "$(dirname "$0")/.."  # Zu deployment/stacks/local/
# ... Secrets generieren

scripts/migrate-env-to-secrets.sh:

#!/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:

# 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:

# 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

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)

docker compose -f docker-compose.base.yml -f docker-compose.local.yml up

Nachher (neu)

cd deployment/stacks/local
docker compose up -d

Oder vom Root:

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:

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:

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