fix: Gitea Traefik routing and connection pool optimization

- Remove middleware reference from Gitea Traefik labels (caused routing issues)
- Optimize Gitea connection pool settings (MAX_IDLE_CONNS=30, authentication_timeout=180s)
- Add explicit service reference in Traefik labels
- Fix intermittent 504 timeouts by improving PostgreSQL connection handling

Fixes Gitea unreachability via git.michaelschiemer.de

docs/guides/configuration.md

@@ -0,0 +1,297 @@
+# Configuration Best Practices
+
+Leitlinien für effektives Configuration Management im Custom PHP Framework.
+
+## Problem: .env Bloat
+
+**Symptom**: Zunehmende Anzahl von Environment-Variablen in `.env.example`
+
+**Negative Auswirkungen**:
+- Schwer zu überschauen, welche Variablen wirklich wichtig sind
+- Viele Parameter, die Entwickler nie ändern werden
+- Unklare Defaults für optionale Parameter
+- Erhöhter Wartungsaufwand
+
+## Lösung: Sensible Defaults + Minimal Configuration
+
+### Prinzip 1: "Convention over Configuration"
+
+**Regel**: Nur Werte, die Entwickler WIRKLICH ändern müssen oder wollen, gehören in `.env`
+
+**Gute .env Kandidaten**:
+- ✅ Credentials (DB_PASSWORD, API_KEYS)
+- ✅ Umgebungs-spezifische Werte (APP_ENV, APP_URL)
+- ✅ Infrastruktur-Konfiguration (DB_HOST, REDIS_HOST)
+- ✅ Feature Toggles für Production (APP_DEBUG)
+
+**Schlechte .env Kandidaten**:
+- ❌ Performance Tuning Parameter (CACHE_TTL=60)
+- ❌ Interne Framework-Defaults (CACHE_SIZE=100)
+- ❌ Rarely Changed Feature Flags (FEATURE_ENABLED=true)
+- ❌ Debug-only Flags (VERBOSE_LOGGING=false)
+
+### Prinzip 2: Sensible Defaults im Code
+
+**Vor der Refaktorierung** (4 .env Variablen):
+```env
+FILESYSTEM_VALIDATOR_CACHE=true          # Rarely disabled
+FILESYSTEM_VALIDATOR_CACHE_TTL=60       # Never changed
+FILESYSTEM_VALIDATOR_CACHE_SIZE=100     # Never changed
+FILESYSTEM_STORAGE_CACHE=true           # Rarely disabled
+```
+
+**Nach der Refaktorierung** (1 .env Variable):
+```env
+# Filesystem Performance (caching enabled by default)
+# Set to true only for debugging performance issues
+# FILESYSTEM_DISABLE_CACHE=false
+```
+
+**Im Code** (FilesystemInitializer.php):
+```php
+// Sensible defaults hardcoded
+$disableCache = filter_var($_ENV['FILESYSTEM_DISABLE_CACHE'] ?? 'false', FILTER_VALIDATE_BOOLEAN);
+
+if ($disableCache) {
+    return $validator;
+}
+
+return new CachedFileValidator(
+    validator: $validator,
+    cacheTtl: 60,        // Sensible default: 1 minute
+    maxCacheSize: 100    // Sensible default: 100 entries
+);
+```
+
+**Vorteile**:
+- ✅ 75% weniger .env Variablen (4 → 1)
+- ✅ Klarere Intention: "disable only for debugging"
+- ✅ Production-optimized by default
+- ✅ Einfacher für neue Entwickler
+
+### Prinzip 3: Opt-Out statt Opt-In für Performance
+
+**Schlechtes Pattern** (Opt-In):
+```env
+FEATURE_CACHE=false  # Muss explizit aktiviert werden
+```
+→ Entwickler vergessen es zu aktivieren → Performance-Probleme
+
+**Gutes Pattern** (Opt-Out):
+```env
+# FEATURE_DISABLE_CACHE=false  # Caching standardmäßig aktiv
+```
+→ Production-optimiert by default → Explizit deaktivieren nur für Debugging
+
+### Prinzip 4: Gruppierung und Kommentare
+
+**Schlechtes Beispiel**:
+```env
+CACHE_ENABLED=true
+CACHE_TTL=60
+CACHE_SIZE=100
+DB_CACHE=true
+FILE_CACHE=true
+API_CACHE=true
+```
+
+**Gutes Beispiel**:
+```env
+# Cache System (optimized by default)
+# Disable only for debugging: DISABLE_ALL_CACHES=true
+# DISABLE_ALL_CACHES=false
+
+# Database-specific cache tuning (advanced)
+# DB_CACHE_TTL=3600
+```
+
+## Refactoring-Strategie
+
+### Schritt 1: Identifiziere "Never Changed" Parameter
+
+Prüfe in der Codebase:
+```bash
+# Suche nach $_ENV usage
+grep -r "ENV\['" src/
+
+# Identifiziere Parameter, die nie geändert werden
+# Kandidaten für Hardcoding
+```
+
+### Schritt 2: Extrahiere Sensible Defaults
+
+**Vor**:
+```php
+$ttl = (int) ($_ENV['CACHE_TTL'] ?? 60);
+$size = (int) ($_ENV['CACHE_SIZE'] ?? 100);
+```
+
+**Nach**:
+```php
+// Sensible defaults based on production experience
+const DEFAULT_CACHE_TTL = 60;    // 1 minute
+const DEFAULT_CACHE_SIZE = 100;  // 100 entries
+
+$ttl = self::DEFAULT_CACHE_TTL;
+$size = self::DEFAULT_CACHE_SIZE;
+```
+
+### Schritt 3: Konsolidiere Related Flags
+
+**Vor** (3 separate flags):
+```env
+FILESYSTEM_VALIDATOR_CACHE=true
+FILESYSTEM_STORAGE_CACHE=true
+FILESYSTEM_CACHE_CLEARSTATCACHE=true
+```
+
+**Nach** (1 master flag):
+```env
+# FILESYSTEM_DISABLE_CACHE=false
+```
+
+**Im Code**:
+```php
+$disableCache = filter_var($_ENV['FILESYSTEM_DISABLE_CACHE'] ?? 'false', FILTER_VALIDATE_BOOLEAN);
+
+// Affects all filesystem caching
+$useValidatorCache = !$disableCache;
+$useStorageCache = !$disableCache;
+$optimizeClearstatcache = !$disableCache;
+```
+
+### Schritt 4: Dokumentiere Advanced Tuning
+
+Für Experten, die wirklich tunen wollen:
+
+```php
+// Advanced tuning (usually not needed)
+$ttl = (int) ($_ENV['FILESYSTEM_VALIDATOR_CACHE_TTL'] ?? 60);
+$size = (int) ($_ENV['FILESYSTEM_VALIDATOR_CACHE_SIZE'] ?? 100);
+```
+
+**In Dokumentation** (nicht in .env.example):
+```markdown
+## Advanced Configuration
+
+For expert performance tuning, these environment variables can be used:
+
+- `FILESYSTEM_VALIDATOR_CACHE_TTL`: Cache TTL in seconds (default: 60)
+- `FILESYSTEM_VALIDATOR_CACHE_SIZE`: Max cache entries (default: 100)
+
+⚠️ **Warning**: Only change these if you have measured performance issues.
+```
+
+## Entscheidungsbaum
+
+```
+Braucht diese Variable in .env?
+│
+├─ Ist es eine Credential? → ✅ JA
+├─ Ist es umgebungs-spezifisch (dev/prod)? → ✅ JA
+├─ Muss es für Production geändert werden? → ✅ JA
+├─ Wird es von Entwicklern oft geändert? → ✅ JA
+│
+└─ Ansonsten:
+   ├─ Ist es ein Performance Tuning Parameter? → ❌ NEIN (Sensible Default im Code)
+   ├─ Ist es ein internes Detail? → ❌ NEIN (Hardcode im Code)
+   ├─ Ist es ein Debug Flag? → ⚠️ MAYBE (Opt-Out Pattern erwägen)
+   └─ Ist es ein Feature Toggle? → ⚠️ MAYBE (Convention over Configuration)
+```
+
+## .env Organisation
+
+### Empfohlene Struktur
+
+```env
+# ============================================================
+# CORE APPLICATION
+# ============================================================
+APP_ENV=development
+APP_DEBUG=true
+APP_URL=https://localhost
+
+# ============================================================
+# DATABASE
+# ============================================================
+DB_HOST=db
+DB_PORT=5432
+DB_DATABASE=michaelschiemer
+DB_USERNAME=postgres
+DB_PASSWORD=your_secure_password
+
+# ============================================================
+# EXTERNAL SERVICES
+# ============================================================
+SPOTIFY_CLIENT_ID=your_client_id
+SPOTIFY_CLIENT_SECRET=your_client_secret
+
+# ============================================================
+# PERFORMANCE & DEBUGGING (optimized by default)
+# ============================================================
+# Uncomment only for debugging:
+# FILESYSTEM_DISABLE_CACHE=false
+# DISABLE_QUERY_LOG=false
+# VERBOSE_ERROR_PAGES=false
+```
+
+## Beispiele aus dem Framework
+
+### ✅ Gutes Beispiel: Filesystem Performance
+
+**Vorher** (4 Variablen):
+```env
+FILESYSTEM_VALIDATOR_CACHE=true
+FILESYSTEM_VALIDATOR_CACHE_TTL=60
+FILESYSTEM_VALIDATOR_CACHE_SIZE=100
+FILESYSTEM_STORAGE_CACHE=true
+```
+
+**Nachher** (1 Variable):
+```env
+# FILESYSTEM_DISABLE_CACHE=false
+```
+
+**Einsparung**: 75% weniger Variablen, gleiche Funktionalität
+
+### ❌ Anti-Pattern: Zu granulare Konfiguration
+
+```env
+# DON'T DO THIS
+ENABLE_USER_CACHE=true
+USER_CACHE_TTL=60
+USER_CACHE_SIZE=100
+ENABLE_POST_CACHE=true
+POST_CACHE_TTL=120
+POST_CACHE_SIZE=200
+ENABLE_COMMENT_CACHE=true
+COMMENT_CACHE_TTL=30
+COMMENT_CACHE_SIZE=50
+```
+
+**Besser**:
+```env
+# Cache System (enabled by default with sensible defaults)
+# DISABLE_ALL_CACHES=false
+```
+
+**Im Code** (wenn wirklich Tuning nötig):
+```php
+// Expert tuning available via environment, but not advertised
+$userCacheTtl = (int) ($_ENV['USER_CACHE_TTL'] ?? 60);
+$postCacheTtl = (int) ($_ENV['POST_CACHE_TTL'] ?? 120);
+```
+
+## Zusammenfassung
+
+**Goldene Regel**: Jede .env Variable muss rechtfertigen, warum sie NICHT ein Sensible Default im Code sein kann.
+
+**Checklist für neue .env Variablen**:
+- [ ] Ist es eine Credential oder Secret? → .env
+- [ ] Ist es umgebungs-spezifisch? → .env
+- [ ] Ändern Entwickler es regelmäßig? → .env
+- [ ] Ist es ein Performance Parameter? → Sensible Default im Code
+- [ ] Ist es ein Debug Flag? → Opt-Out Pattern (commented out in .env.example)
+- [ ] Ist es ein internes Detail? → Hardcode im Code, nicht konfigurierbar
+
+**Ergebnis**: Übersichtliche .env.example, production-optimized by default, trotzdem flexibel für Experten.