220 lines
6.1 KiB
Markdown
220 lines
6.1 KiB
Markdown
# 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/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:
|
|
|
|
```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=\"/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:
|
|
|
|
```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
|