feat: add comprehensive framework features and deployment improvements
Major additions: - Storage abstraction layer with filesystem and in-memory implementations - Gitea API integration with MCP tools for repository management - Console dialog mode with interactive command execution - WireGuard VPN DNS fix implementation and documentation - HTTP client streaming response support - Router generic result type - Parameter type validator for framework core Framework enhancements: - Console command registry improvements - Console dialog components - Method signature analyzer updates - Route mapper refinements - MCP server and tool mapper updates - Queue job chain and dependency commands - Discovery tokenizer improvements Infrastructure: - Deployment architecture documentation - Ansible playbook updates for WireGuard client regeneration - Production environment configuration updates - Docker Compose local configuration updates - Remove obsolete docker-compose.yml (replaced by environment-specific configs) Documentation: - PERMISSIONS.md for access control guidelines - WireGuard DNS fix implementation details - Console dialog mode usage guide - Deployment architecture overview Testing: - Multi-purpose attribute tests - Gitea Actions integration tests (typed and untyped)
This commit is contained in:
226
docs/PERMISSIONS.md
Normal file
226
docs/PERMISSIONS.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 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`)
|
||||
Reference in New Issue
Block a user