Laravel Sail - Knowledge of Laravel

Was ist Sail

Laravel Sail ist ein schlankes Kommandozeilen-Interface, um die Docker-Entwicklungsumgebung von Laravel zu bedienen. Sie bauen damit eine Laravel-Anwendung mit PHP, MySQL und Redis auf – auch ohne Docker-Vorkenntnisse. Kern von Sail sind die Datei compose.yaml im Projekt-Root und das Skript sail. Das sail-Skript bietet praktische CLI-Methoden zur Steuerung der in compose.yaml definierten Container. Laravel Sail läuft unter macOS, Linux und Windows (über WSL2).

In Laravel 13 ist Sail nicht mehr die Standard-Entwicklungsumgebung. In der Skeleton-composer.json fehlt laravel/sail; stattdessen gibt es den Befehl composer setup. Standard ist ein Setup mit lokalem PHP + SQLite.

composer setup
composer dev

Wenn Sie Docker-Container brauchen, können Sie Sail wie gewohnt installieren und nutzen.

Sail ist ein Werkzeug für die lokale Entwicklung. Der Produktivbetrieb ist damit nicht vorgesehen. Für die Produktion sollten Sie eine eigene Docker-/Cloud-Konfiguration einrichten.

Installation

In ein bestehendes Projekt

Installieren Sie das Paket mit Composer.

Sail-Paket hinzufügen

composer require laravel/sail --dev

Konfigurationsdateien veröffentlichen

Führen Sie den Artisan-Befehl sail:install aus. Er legt compose.yaml im Projekt-Root an und ergänzt in der .env die notwendigen Umgebungsvariablen.

php artisan sail:install

Sie können interaktiv Dienste auswählen (MySQL, Redis, Mailpit usw.).

Sail starten

./vendor/bin/sail up

Der erste Start dauert etwas, da Docker-Images heruntergeladen werden. Danach ist die Anwendung unter http://localhost erreichbar.

Mit Docker Desktop for Linux verwenden Sie den default-Kontext: docker context use default. Bei Dateirechte-Problemen im Container setzen Sie SUPERVISOR_PHP_USER auf root.

Weitere Dienste hinzufügen

Um einer bestehenden Sail-Installation weitere Dienste hinzuzufügen, nutzen Sie sail:add.

php artisan sail:add

Devcontainer nutzen

Um in einem Devcontainer zu arbeiten, verwenden Sie die Option --devcontainer.

php artisan sail:install --devcontainer

Konfiguration

Shell-Alias einrichten

Standardmäßig müssen Sie jedes Mal ./vendor/bin/sail schreiben. Ein Alias erlaubt schlicht sail.

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Ergänzen Sie das in ~/.zshrc oder ~/.bashrc und starten Sie die Shell neu.

sail up

Nach dem Setzen des Alias können Sie in allen Beispielen dieser Doku sail statt ./vendor/bin/sail schreiben.

Images neu bauen

Wenn Sie Pakete aktuell halten möchten, bauen Sie die Images neu.

docker compose down -v

sail build --no-cache

sail up

Start und Stopp

Um alle in compose.yaml definierten Container zu starten, verwenden Sie up.

# Im Vordergrund starten
sail up

# Im Hintergrund starten
sail up -d

Stoppen mit stop; im Vordergrund mit Strg + C.

sail stop

Ablauf beim Start

Kommandos ausführen

Mit Sail läuft die Anwendung in einem Docker-Container. PHP-, Artisan-, Composer- und Node/NPM-Kommandos rufen Sie alle über sail auf.

Die in der Doku üblichen Befehle php artisan, composer, npm führen Sie in Sail-Umgebungen mit vorangestelltem sail aus.

PHP

sail php --version

sail php script.php

Composer

sail composer require laravel/sanctum

Artisan

sail artisan migrate

sail artisan queue:work

Node / NPM

sail node --version

sail npm run dev

# Yarn
sail yarn

Container-CLI (Shell)

Sie können auch direkt eine Bash-Session im Container öffnen.

sail shell

# Als root anmelden
sail root-shell

Für eine Tinker-Session:

sail tinker

Dienste

Ein Überblick über die von Sail bereitgestellten Dienste, die Sie bei sail:install auswählen können.

MySQL

Standardmäßig in compose.yaml enthalten. Daten werden über ein Docker-Volume persistiert. Beim ersten Start werden zwei Datenbanken angelegt: eine für die Anwendung und eine testing-Datenbank. Setzen Sie in der .env DB_HOST auf mysql.

DB_HOST=mysql
DB_PORT=3306

Für die Verbindung vom Host aus nutzen Sie GUI-Tools wie TablePlus. Der Standardport ist 3306.

Redis

Setzen Sie REDIS_HOST auf redis.

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

Um als Redis-Alternative Valkey zu verwenden, setzen Sie REDIS_HOST auf valkey.

Mailpit

Fängt lokal versendete E-Mails ab und zeigt sie in einer Web-UI an.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Die Web-UI ist während des Sail-Laufs unter http://localhost:8025 erreichbar.

Meilisearch / Typesense

Zusammen mit Laravel Scout testen Sie damit die Volltextsuche.

Meilisearch: MEILISEARCH_HOST=http://meilisearch:7700
Typesense: TYPESENSE_HOST=typesense, TYPESENSE_PORT=8108 usw.

RustFS (S3-kompatibler Storage)

Wenn Sie in Produktion Amazon S3 verwenden wollen, können Sie lokal einen S3-kompatiblen Storage emulieren.

FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://rustfs:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

Tests ausführen

sail test

sail test --group orders

sail test entspricht intern sail artisan test. Die eigene Datenbank testing bleibt vom Entwicklungsstand unberührt.

Laravel Dusk

Mit Sail können Sie Dusk-Browsertests ausführen, ohne Selenium lokal zu installieren. Kommentieren Sie den Selenium-Dienst in compose.yaml aus:

selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Auf Apple Silicon (M1/M2/M3) verwenden Sie das Image selenium/standalone-chromium.

Anschließend führen Sie die Dusk-Tests aus:

sail dusk

PHP- und Node-Versionen

PHP-Version wechseln

Ändern Sie in compose.yaml den build.context des Containers laravel.test.

# PHP 8.5 (Standard)
context: ./vendor/laravel/sail/runtimes/8.5

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4

# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3

Danach das Image neu bauen:

sail build --no-cache
sail up

Zusätzliche PHP-Erweiterungen

Die Sail-Runtime enthält gängige PHP-Erweiterungen. Wenn Ihre Anwendung zusätzliche benötigt, ergänzen Sie in compose.yaml beim Service laravel.test das Build-Argument PHP_EXTENSIONS (Leerzeichen-getrennt), sodass sie beim Build installiert werden.

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'

Anschließend das Container-Image neu bauen:

sail build --no-cache
sail up

Node-Version wechseln

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'

Site öffentlich teilen

Zum Kollegen-Preview oder für Webhook-Tests können Sie Ihre Site temporär öffentlich zugänglich machen.

sail share

Sie erhalten eine zufällige URL auf laravel-sail.site. Damit URL-Generierungshelfer korrekt funktionieren, setzen Sie in bootstrap/app.php einen Trusted Proxy:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

Auch eine feste Subdomain ist möglich.

sail share --subdomain=my-sail-site

Xdebug

Aktivieren

Veröffentlichen Sie zunächst die Konfigurationsdateien mit sail:publish und ergänzen Sie in der .env:

SAIL_XDEBUG_MODE=develop,debug,coverage

Stellen Sie sicher, dass die veröffentlichte php.ini folgende Zeilen enthält.

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Anschließend das Image neu bauen:

sail build --no-cache

CLI-Debugging

# Ohne Xdebug
sail artisan migrate

# Mit Xdebug
sail debug migrate

Browser-Debugging

Für den Ablauf, eine Debug-Session vom Browser aus zu starten, lesen Sie die Xdebug-Dokumentation. Nutzer von PhpStorm profitieren von Zero-configuration debugging.

Sail bedient die App über artisan serve. XDEBUG_CONFIG und XDEBUG_MODE werden erst ab Laravel 8.53.0 akzeptiert. Bei älteren Versionen funktioniert die Debug-Verbindung nicht.

Anpassen

Zum Anpassen der Dockerfiles und Konfigurationen veröffentlichen Sie die Dateien mit sail:publish.

sail artisan sail:publish

Die Dockerfiles liegen anschließend im Verzeichnis docker/. Nach Änderungen bauen Sie die Container neu:

sail build --no-cache

Unterschiede zur Produktion

Sail ist für lokale Entwicklung gedacht – nicht für Produktion. Für Docker-Deployments in Produktion nutzen Sie Dienste wie Laravel Cloud, Forge oder Ploi oder eine eigene Docker-Compose- bzw. Kubernetes-Konfiguration.

Wesentliche Unterschiede zusammengefasst:

Punkt	Sail (lokal)	Produktion
Zweck	Entwicklung, Debugging	Betrieb
Xdebug	Aktivierbar	Deaktiviert empfohlen
Mailpit	Fängt Mails ab und zeigt sie	Echter Mailserver
Datenpersistenz	Docker-Volume	Managed DB o. Ä.
Performance	Nicht optimiert	Erforderlich zu optimieren

​Was ist Sail

​Installation

​In ein bestehendes Projekt

​Weitere Dienste hinzufügen

​Devcontainer nutzen

​Konfiguration

​Shell-Alias einrichten

​Images neu bauen

​Start und Stopp

​Ablauf beim Start

​Kommandos ausführen

​PHP

​Composer

​Artisan

​Node / NPM

​Container-CLI (Shell)

​Dienste

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS (S3-kompatibler Storage)

​Tests ausführen

​Laravel Dusk

​PHP- und Node-Versionen

​PHP-Version wechseln

​Zusätzliche PHP-Erweiterungen

​Node-Version wechseln

​Site öffentlich teilen

​Xdebug

​Aktivieren

​CLI-Debugging

​Browser-Debugging

​Anpassen

​Unterschiede zur Produktion

Was ist Sail

Installation

In ein bestehendes Projekt

Weitere Dienste hinzufügen

Devcontainer nutzen

Konfiguration

Shell-Alias einrichten

Images neu bauen

Start und Stopp

Ablauf beim Start

Kommandos ausführen

PHP

Composer

Artisan

Node / NPM

Container-CLI (Shell)

Dienste

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS (S3-kompatibler Storage)

Tests ausführen

Laravel Dusk

PHP- und Node-Versionen

PHP-Version wechseln

Zusätzliche PHP-Erweiterungen

Node-Version wechseln

Site öffentlich teilen

Xdebug

Aktivieren

CLI-Debugging

Browser-Debugging

Anpassen

Unterschiede zur Produktion