# Laravel Sail DevContainer Setup

Diese Dokumentation beschreibt die Einrichtung und Verwendung des DevContainers für das Laravel Sail-Projekt.

## Übersicht

Der DevContainer ermöglicht es, das Laravel-Projekt in einer vollständig konfigurierten Docker-Umgebung zu entwickeln, ohne dass lokale PHP-, Node.js- oder andere Abhängigkeiten installiert werden müssen.

## Voraussetzungen

-   Docker Desktop installiert und laufend
-   Cursor.ai oder VS Code mit DevContainer-Erweiterung
-   Git (für Repository-Zugriff)

## Konfiguration

### 1. DevContainer-Konfiguration (`devcontainer.json`)

Die Hauptkonfiguration befindet sich in `.devcontainer/devcontainer.json`:

-   **Eigenständiges Docker-Image**: Verwendet `sail-8.4/app` direkt ohne Docker Compose
-   **Build-Konfiguration**: Definiert Build-Argumente für `WWWUSER` und `WWWGROUP`
-   **Workspace**: `/var/www/html` (Standard-Laravel-Verzeichnis)
-   **Benutzer**: `sail` (Laravel Sail Standard-Benutzer)
-   **Features**: Leer (Tools werden über postCreateCommand installiert)
-   **Extensions**: PHP, Laravel Blade, Tailwind CSS Extensions
-   **Port-Forwarding**: Automatisch für wichtige Services (5173, 33061, 6380, 8025)

### 2. Dockerfile-Anpassungen (`docker/8.4/Dockerfile`)

Das Dockerfile wurde angepasst um:

-   `ARG WWWUSER` hinzugefügt für korrekte Benutzer-ID
-   Benutzererstellung mit dynamischen IDs (`$WWWUSER` statt feste `1337`)
-   Vollständige Laravel-Umgebung mit PHP 8.4, Composer, NPM, Git

## Installation

### Automatische Installation (Empfohlen)

1. Öffnen Sie das Projekt in Cursor.ai oder VS Code
2. Klicken Sie auf "Reopen in Container" wenn die DevContainer-Benachrichtigung erscheint
3. Warten Sie bis der Container gebaut und gestartet ist

### Manuelle Installation

Falls die automatische Installation fehlschlägt, können Sie den Container manuell bauen:

```bash
cd /Users/pandora/Sites/pressekonto.de
docker build --build-arg WWWUSER=501 --build-arg WWWGROUP=20 -f docker/8.4/Dockerfile -t sail-8.4/app docker/8.4
```

## Verfügbare Tools

Nach der Installation sind folgende Tools verfügbar:

-   **PHP 8.4.12**: Mit Xdebug für Debugging
-   **Composer**: Für Laravel-Abhängigkeiten
-   **NPM**: Für Frontend-Assets
-   **Git**: Für Versionskontrolle
-   **Node.js**: Für JavaScript-Entwicklung

Überprüfen Sie die Installation:

```bash
which git
which npm
which composer
php --version
```

## Post-Create-Befehle

Nach dem Erstellen des Containers werden automatisch ausgeführt:

1. Composer-Abhängigkeiten (`composer install`)

## Entwicklung

### Erste Schritte

1. **Composer-Abhängigkeiten**: Werden automatisch installiert
2. **Laravel-Konfiguration**: `.env` Datei muss manuell erstellt werden (siehe Laravel-Dokumentation)
3. **Datenbank-Migrationen**: `php artisan migrate`
4. **Asset-Kompilierung**: `npm install && npm run dev`

### Häufige Befehle

```bash
# Laravel-Befehle
php artisan migrate
php artisan serve
php artisan tinker

# Composer
composer install
composer update

# NPM/Node
npm install
npm run dev
npm run build

# Sail-Befehle (falls verfügbar)
./vendor/bin/sail up
./vendor/bin/sail artisan migrate
```

## Troubleshooting

### Container startet nicht

1. Überprüfen Sie ob Docker Desktop läuft
2. Stellen Sie sicher, dass keine anderen Container die benötigten Ports blockieren
3. Versuchen Sie einen Clean-Build: `docker build --no-cache ...`

### Berechtigungsprobleme

Die Container sind so konfiguriert, dass sie mit Ihrer lokalen Benutzer-ID (`501`) laufen, um Berechtigungsprobleme zu vermeiden.

### NPM Global Install Probleme

Falls Sie globale NPM-Pakete installieren möchten, verwenden Sie lokale Installation:

```bash
# Lokale Installation (empfohlen)
npm install package-name

# Oder NPM-Prefix ändern
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

### Claude CLI Kompatibilitätsprobleme

**Problem**: Das `@anthropic-ai/claude-code` Paket ist nicht mit modernen Node.js-Versionen kompatibel.

**Symptome**:

-   Viele veraltete Abhängigkeiten (deprecated packages)
-   PhantomJS ARM64 Kompatibilitätsprobleme
-   Engine-Konflikte mit Node.js v22

**Lösung**:

curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> /home/sail/.bashrc && source /home/sail/.bashrc
export PATH="$HOME/.local/bin:$PATH" && claude --version
### Port-Konflikte

Falls Ports bereits belegt sind, können Sie die Port-Mapping in der DevContainer-Konfiguration anpassen.

## Erweiterte Konfiguration

### Zusätzliche Extensions hinzufügen

Bearbeiten Sie `devcontainer.json` und fügen Sie Extensions zum `extensions` Array hinzu:

```json
"extensions": [
    "bmewburn.vscode-intelephense-client",
    "onecentlin.laravel-blade",
    "shufo.vscode-blade-formatter",
    "bradlc.vscode-tailwindcss",
    "ihrc.vscode-php-cs-fixer"
]
```

### Zusätzliche Tools installieren

Fügen Sie Tools zum `postCreateCommand` hinzu:

```json
"postCreateCommand": "composer install --no-interaction --prefer-dist --optimize-autoloader && npm install -g your-tool"
```

## Support

Bei Problemen mit dem DevContainer:

1. Überprüfen Sie die Docker-Logs: `docker logs <container-name>`
2. Stellen Sie sicher, dass alle Umgebungsvariablen korrekt gesetzt sind
3. Versuchen Sie einen Neustart des DevContainers

## Bekannte Probleme und Lösungen

### DevContainer-CLI Kompatibilität

**Problem**: DevContainer-CLI erstellt temporäre Docker-Compose-Dateien die mit der Konfiguration kollidieren.

**Lösung**: Verwendung eines eigenständigen Docker-Images ohne Docker Compose-Abhängigkeit.

### Features-Installation

**Problem**: DevContainer Features können zu Build-Fehlern führen.

**Lösung**: Tools werden über `postCreateCommand` installiert statt über Features.

### Root-Berechtigungen

**Problem**: Der `sail`-Benutzer hat keine Root-Rechte für Paket-Installation.

**Lösung**: Alle notwendigen Tools sind bereits im Docker-Image installiert.



---

**Letzte Aktualisierung**: September 2025
**Laravel Version**: 12.x
**PHP Version**: 8.4.12
**Docker Version**: 2.x
**Status**: ✅ Vollständig funktionsfähig