b2in/.devcontainer

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:

cd /Users/pandora/Sites/b2in.local
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:

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

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

# 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="/root/.local/bin:$PATH"' >> /home/sail/.bashrc

echo 'export PATH="$HOME/.local/bin:$PATH"' >> /home/sail/.bashrc

source /home/sail/.bashrc

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:

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

"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