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:

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

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

# 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

# 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

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

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

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

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

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

# 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!)

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

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