michaelschiemer/docs/deployment/cache-configuration.md

# Cache Configuration & Permissions

## ?bersicht

Diese Dokumentation beschreibt die Konfiguration und Berechtigungsverwaltung f?r das FileCache-System auf Staging und Production-Servern.

## Problem-Background

Das FileCache-System speichert Cache-Dateien in `/var/www/html/storage/cache`. In Multi-User/Process-Umgebungen k?nnen Permission-Probleme auftreten, wenn:

- Cache-Dateien von verschiedenen Prozessen/Usern erstellt werden
- Owner/Group-Mismatch zwischen erstellenden und l?schenden Prozessen
- Falsche Berechtigungen auf Cache-Dateien oder Verzeichnissen

### Gel?ste Probleme

? **Bug-Fix**: `FileStorage::delete()` pr?ft jetzt nur noch Verzeichnis-Rechte (nicht Datei-Rechte)  
? **Graceful Degradation**: FileCache f?ngt Permission-Exceptions und arbeitet weiter  
? **Robuste Fehlerbehandlung**: Cache funktioniert auch bei Permission-Problemen

## Berechtigungen

### Verzeichnis-Berechtigungen

Das Cache-Verzeichnis sollte folgende Berechtigungen haben:

```bash
# Verzeichnis: 775 (rwxrwxr-x)
# - Owner: rwx (read, write, execute)
# - Group: rwx (read, write, execute)
# - Others: r-x (read, execute)
chmod 775 /var/www/html/storage/cache
```

### Datei-Berechtigungen

Cache-Dateien werden mit folgenden Berechtigungen erstellt:

```php
// 0644 (rw-r--r--)
// - Owner: rw- (read, write)
// - Group: r-- (read)
// - Others: r-- (read)
```

**Wichtig**: F?r das L?schen von Dateien werden nur **Verzeichnis-Rechte** ben?tigt, nicht Datei-Rechte!

## Docker Entrypoint-Script

Das Entrypoint-Script (`docker/php/docker-entrypoint.sh`) setzt automatisch die korrekten Berechtigungen:

```bash
# Fix ownership for all storage directories (including mounted volumes)
if [ -d /var/www/html/storage ]; then
    chown -R appuser:appuser /var/www/html/storage 2>/dev/null || true
    chmod -R 775 /var/www/html/storage 2>/dev/null || true
fi
```

### Wichtig f?r Staging/Production

1. **Named Volumes**: Docker erstellt Named Volumes als root - das Entrypoint-Script fixiert Ownership nach dem Mount
2. **Wartezeit**: `sleep 1` stellt sicher, dass Docker Volumes gemountet hat
3. **Graceful Degradation**: `|| true` stellt sicher, dass das Script nicht bei Permission-Fehlern abbricht

## Manuelle Fixes

### Fix Berechtigungen auf Staging/Production

```bash
# Auf dem Server ausf?hren
docker exec -it staging-app chown -R appuser:appuser /var/www/html/storage/cache
docker exec -it staging-app chmod -R 775 /var/www/html/storage/cache
```

### Fix existierende Cache-Dateien

```bash
# Als root im Container - ermittle User automatisch
docker exec -it --user root staging-app bash -c '
  # Ermittle User aus PHP-FPM Config oder verwende www-data als Fallback
  USER=$(grep "^user = " /usr/local/etc/php-fpm.d/*.conf 2>/dev/null | head -1 | cut -d"=" -f2 | tr -d " ;")
  [ -z "$USER" ] && USER="www-data"
  echo "Using user: $USER"
  
  # Fix Permissions
  find /var/www/html/storage/cache -type f -exec chmod 644 {} \;
  find /var/www/html/storage/cache -type d -exec chmod 775 {} \;
  chown -R $USER:$USER /var/www/html/storage/cache
'
```

### Cleanup nicht l?schbarer Dateien

Falls nach dem Fix noch Dateien vorhanden sind, die nicht gel?scht werden k?nnen:

```bash
# Als root im Container
docker exec -it --user root staging-app bash
cd /var/www/html/storage/cache
chown -R appuser:appuser .
chmod -R 775 .
exit
```

## Ansible-Integration

F?r Ansible-Deployments k?nnen folgende Tasks hinzugef?gt werden:

```yaml
- name: Fix cache directory permissions
  file:
    path: "{{ app_storage_path }}/cache"
    owner: appuser
    group: appuser
    mode: '0775'
    recurse: yes
    state: directory
  become: yes
```

## Troubleshooting

### Problem: Permission denied beim L?schen

**Symptom**:
```
FilePermissionException: Permission denied for delete on file: ...cache.php (File is not writable)
```

**L?sung**:
1. Pr?fe Verzeichnis-Berechtigungen: `ls -ld /var/www/html/storage/cache`
2. Pr?fe Owner: `ls -l /var/www/html/storage/cache | head`
3. Fix Berechtigungen (siehe oben)

### Problem: Cache-Dateien werden von verschiedenen Usern erstellt

**Symptom**: Dateien haben unterschiedliche Owner

**L?sung**:
- Stelle sicher, dass alle PHP-Prozesse als `appuser` laufen
- Pr?fe PHP-FPM Pool-Konfiguration
- Stelle sicher, dass Entrypoint-Script korrekt l?uft

### Problem: Cache funktioniert nicht nach Deployment

**Symptom**: Cache-Operationen schlagen fehl

**Diagnose**:
```bash
# Pr?fe Verzeichnis existiert
docker exec staging-app ls -la /var/www/html/storage/cache

# Pr?fe Berechtigungen
docker exec staging-app stat /var/www/html/storage/cache

# Pr?fe Owner
docker exec staging-app whoami
```

**L?sung**: 
- Stelle sicher, dass Entrypoint-Script ausgef?hrt wurde
- Manuell Berechtigungen fixen (siehe oben)

## Best Practices

### 1. Verzeichnis-Berechtigungen

- **Verzeichnis**: 775 (rwxrwxr-x) - Group-writable f?r Multi-User
- **Dateien**: 644 (rw-r--r--) - Standard f?r Cache-Dateien

### 2. Owner/Group

- **Owner**: `appuser` (der User, der PHP-Prozesse ausf?hrt)
- **Group**: `appuser` (oder gemeinsame Gruppe f?r alle Prozesse)

### 3. Monitoring

?berwache Cache-Verzeichnis auf Permission-Probleme:

```bash
# Finde Dateien mit falschen Owner
find /var/www/html/storage/cache -not -user appuser

# Finde Dateien mit falschen Permissions
find /var/www/html/storage/cache -type f -not -perm 644
```

### 4. Cleanup

Regelm??iges Cleanup von abgelaufenen Cache-Dateien:

```bash
# Manueller Cleanup
docker exec staging-app php console.php cache:clear

# Oder via Cronjob
0 2 * * * docker exec staging-app php console.php cache:clear
```

## Code-?nderungen

### FileStorage::delete()

**Vorher**: Pr?fte `is_writable()` auf Datei (falsch!)  
**Nachher**: Pr?ft nur Verzeichnis-Rechte (korrekt!)

```php
// WICHTIG: F?r unlink() braucht man nur Schreibrechte im Verzeichnis!
$dir = dirname($resolvedPath);
if (! is_writable($dir)) {
    throw FilePermissionException::delete($path, 'Directory is not writable');
}
// ENTFERNT: is_writable() Pr?fung auf Datei
```

### FileCache Graceful Degradation

Alle `delete()` Aufrufe in FileCache fangen jetzt `FilePermissionException`:

```php
try {
    $this->fileSystem->delete($file);
} catch (\App\Framework\Filesystem\Exceptions\FilePermissionException $e) {
    // Permission denied - continue (graceful degradation)
    continue;
}
```

## Weitere Ressourcen

- `docs/FILECACHE_PERMISSION_FIX_PLAN.md` - Detaillierter Fix-Plan
- `docker/php/docker-entrypoint.sh` - Entrypoint-Script
- `src/Framework/Filesystem/FileStorage.php` - FileSystem-Implementierung
- `src/Framework/Cache/Driver/FileCache.php` - FileCache-Implementierung

## Support

Bei Permission-Problemen:

1. Pr?fe Logs: `docker logs staging-app | grep -i permission`
2. Pr?fe Berechtigungen: `docker exec staging-app ls -la /var/www/html/storage/cache`
3. Fix manuell: Siehe "Manuelle Fixes" oben
4. Pr?fe Code: Stelle sicher, dass neueste Version deployed ist