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

```yaml
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**:
```bash
# 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**:
```bash
#!/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):
```bash
make fix-perms
```

**Lösung 2** (Dauerhaft - Container verwenden):
```bash
./bin/console  # Statt: php console.php
```

---

### Problem: Console-Command vom Host aus

**❌ Falsch**:
```bash
php console.php  # Verwendet Host-PHP, hat keine Container-Permissions
console          # Alias existiert nicht
```

**✅ Richtig**:
```bash
./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):
   ```bash
   # In /etc/sudoers.d/storage-permissions
   michael ALL=(ALL) NOPASSWD: /usr/bin/chown -R * /home/michael/dev/michaelschiemer/storage
   ```

---

## Best Practices

### Development Workflow

```bash
# 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

```bash
# Check storage permissions
ls -la storage/

# Find root-owned files
find storage -user root

# Fix all at once
make fix-perms
```

### Git Hooks Update

```bash
# 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`)