michaelschiemer/docs/PERMISSIONS.md

Storage Permissions Management

Problem

Docker containers laufen standardmäßig als root und erstellen Files/Directories mit root-Ownership. Beim Zugriff vom Host aus (z.B. console.php direkt) gibt es dann Permission-Probleme.

Implementierte Lösungen

1. Docker-Wrapper Script ⭐ (EMPFOHLEN)

Location: ./bin/console

Usage:

# Direkt ausführen
./bin/console
./bin/console routes:list
./bin/console db:migrate

# Optional: In PATH aufnehmen
export PATH="$PATH:/home/michael/dev/michaelschiemer/bin"
console routes:list  # Jetzt direkt aufrufbar

Features:

• ✅ Läuft automatisch im PHP-Container
• ✅ TTY-Detection (interaktiv/non-interaktiv)
• ✅ Keine Permission-Probleme
• ✅ Funktioniert in WSL, Linux, macOS

Implementation:

#!/usr/bin/env bash
# Auto-detect TTY und nutze entsprechende docker exec Flags
if [ -t 0 ]; then
    docker exec -it php php console.php "$@"
else
    docker exec php php console.php "$@"
fi

---

2. Container User Configuration ⭐

Status: ✅ Konfiguriert in docker-compose.local.yml

php:
  user: "1000:1000"  # Läuft als Host-User

queue-worker:
  user: "1000:1000"  # Konsistent

php-test:
  user: "1000:1000"  # Konsistent

Vorteile:

• Container erstellt keine root-Files mehr
• Konsistente Permissions über alle Services
• Keine sudo-Rechte für Storage-Zugriffe nötig

Einmalige Permissions-Korrektur:

# Via Makefile (empfohlen)
make fix-perms

# Oder manuell
sudo chown -R $(id -u):$(id -g) storage/

---

3. Git Hooks (Automatisch) ⭐

Location:

• .git/hooks/post-checkout
• .git/hooks/post-merge

Funktion: Automatische Permissions-Korrektur nach git checkout oder git pull

Implementation:

#!/usr/bin/env bash
# Prüfe ob storage-Directories root gehören
if find storage -user root 2>/dev/null | grep -q .; then
    echo "🔧 Fixing storage permissions..."
    sudo chown -R $(id -u):$(id -g) storage/
fi

Wann ausgeführt:

• Nach git checkout <branch>
• Nach git pull
• Nach git merge

---

Troubleshooting

Problem: "Permission denied for create directory"

Symptom:

Fehler: Permission denied for create directory on file: /home/michael/dev/michaelschiemer/storage/queue/priority
Parent directory: /home/michael/dev/michaelschiemer/storage/queue (owner: root, group: root, writable: no)

Lösung 1 (Sofort):

make fix-perms

Lösung 2 (Dauerhaft - Container verwenden):

./bin/console  # Statt: php console.php

---

Problem: Console-Command vom Host aus

❌ Falsch:

php console.php  # Verwendet Host-PHP, hat keine Container-Permissions
console          # Alias existiert nicht

✅ Richtig:

./bin/console           # Docker-Wrapper Script
docker exec php php console.php  # Direkt im Container
make console ARGS="command"      # Via Makefile

---

Problem: Git Hook fragt nach sudo-Password

Erklärung: Hook versucht automatisch permissions zu fixen, benötigt sudo für chown.

Optionen:

1. Password eingeben - Hook korrigiert automatisch
2. Abbrechen - Später manuell make fix-perms ausführen
3. Sudo-less chown (advanced):

   # In /etc/sudoers.d/storage-permissions
   michael ALL=(ALL) NOPASSWD: /usr/bin/chown -R * /home/michael/dev/michaelschiemer/storage
   

---

Best Practices

Development Workflow

# 1. Container starten
make up

# 2. Console Commands im Container ausführen
./bin/console routes:list
./bin/console db:migrate

# 3. Bei Permission-Problemen
make fix-perms

# 4. Container neu starten (bei Config-Änderungen)
make restart

Production Deployment

• KEINE Container-User-Config in Production
• Storage-Directories gehören www-data User
• Container laufen als www-data (uid/gid in Dockerfile gesetzt)
• Keine Host-Mounts (nur Docker Volumes)

---

Maintenance

Permissions Check

# Check storage permissions
ls -la storage/

# Find root-owned files
find storage -user root

# Fix all at once
make fix-perms

Git Hooks Update

# Check if hooks are installed
ls -la .git/hooks/post-*

# Test hook manually
.git/hooks/post-checkout

# Remove hooks (disable auto-fix)
rm .git/hooks/post-checkout .git/hooks/post-merge

---

Summary

Empfohlener Workflow:

1. ✅ Verwende ./bin/console für Console-Commands
2. ✅ Container laufen als User 1000:1000 (development)
3. ✅ Git Hooks korrigieren automatisch nach pull/checkout
4. ✅ Bei Problemen: make fix-perms

Vermeiden:

• ❌ php console.php vom Host aus
• ❌ Console-Commands außerhalb des Containers
• ❌ Manuelle chown-Befehle (verwende make fix-perms)