> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Sail

> Wie Sie mit Laravel Sail eine Docker-basierte lokale Entwicklungsumgebung ohne Konfiguration einrichten.

## Was ist Sail

[Laravel Sail](https://github.com/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](https://docs.microsoft.com/en-us/windows/wsl/about)).

<Warning>
  **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.

  ```shell theme={null}
  composer setup
  composer dev
  ```

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

<Info>
  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.
</Info>

***

## Installation

### In ein bestehendes Projekt

Installieren Sie das Paket mit Composer.

<Steps>
  <Step title="Sail-Paket hinzufügen">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

  <Step title="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.

    ```shell theme={null}
    php artisan sail:install
    ```

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

  <Step title="Sail starten">
    ```shell theme={null}
    ./vendor/bin/sail up
    ```

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

<Warning>
  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`.
</Warning>

### Weitere Dienste hinzufügen

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

```shell theme={null}
php artisan sail:add
```

### Devcontainer nutzen

Um in einem [Devcontainer](https://code.visualstudio.com/docs/remote/containers) zu arbeiten, verwenden Sie die Option `--devcontainer`.

```shell theme={null}
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`.

```shell theme={null}
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.

```shell theme={null}
sail up
```

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

### Images neu bauen

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

```shell theme={null}
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`.

```shell theme={null}
# Im Vordergrund starten
sail up

# Im Hintergrund starten
sail up -d
```

Stoppen mit `stop`; im Vordergrund mit `Strg + C`.

```shell theme={null}
sail stop
```

### Ablauf beim Start

```mermaid theme={null}
flowchart TD
    A["sail up ausführen"] --> B{"Docker-Image<br>vorhanden?"}
    B -- Nein --> C["Image bauen/<br>herunterladen"]
    C --> D["Container starten"]
    B -- Ja --> D
    D --> E["laravel.test-Container<br>(App) startet"]
    D --> F["mysql-Container startet"]
    D --> G["redis-Container startet"]
    D --> H["mailpit-Container startet"]
    E --> I["Erreichbar unter http://localhost"]
```

***

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

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

### PHP

```shell theme={null}
sail php --version

sail php script.php
```

### Composer

```shell theme={null}
sail composer require laravel/sanctum
```

### Artisan

```shell theme={null}
sail artisan migrate

sail artisan queue:work
```

### Node / NPM

```shell theme={null}
sail node --version

sail npm run dev

# Yarn
sail yarn
```

### Container-CLI (Shell)

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

```shell theme={null}
sail shell

# Als root anmelden
sail root-shell
```

Für eine Tinker-Session:

```shell theme={null}
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`.

```ini theme={null}
DB_HOST=mysql
DB_PORT=3306
```

Für die Verbindung vom Host aus nutzen Sie GUI-Tools wie [TablePlus](https://tableplus.com). Der Standardport ist `3306`.

### Redis

Setzen Sie `REDIS_HOST` auf `redis`.

```ini theme={null}
REDIS_HOST=redis
REDIS_PORT=6379
```

### Valkey

Um als Redis-Alternative [Valkey](https://valkey.io/) zu verwenden, setzen Sie `REDIS_HOST` auf `valkey`.

### Mailpit

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

```ini theme={null}
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](/de/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.

```ini theme={null}
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

```shell theme={null}
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:

```yaml theme={null}
selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail
```

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

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

```shell theme={null}
sail dusk
```

***

## PHP- und Node-Versionen

### PHP-Version wechseln

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

```yaml theme={null}
# 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:

```shell theme={null}
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.

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'
```

Anschließend das Container-Image neu bauen:

```shell theme={null}
sail build --no-cache
sail up
```

### Node-Version wechseln

```yaml theme={null}
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.

```shell theme={null}
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:

```php theme={null}
->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})
```

Auch eine feste Subdomain ist möglich.

```shell theme={null}
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`:

```ini theme={null}
SAIL_XDEBUG_MODE=develop,debug,coverage
```

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

```ini theme={null}
[xdebug]
xdebug.mode=${XDEBUG_MODE}
```

Anschließend das Image neu bauen:

```shell theme={null}
sail build --no-cache
```

### CLI-Debugging

```shell theme={null}
# 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](https://xdebug.org/docs/step_debug#web-application).
Nutzer von PhpStorm profitieren von [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html).

<Warning>
  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.
</Warning>

***

## Anpassen

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

```shell theme={null}
sail artisan sail:publish
```

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

```shell theme={null}
sail build --no-cache
```

***

## Unterschiede zur Produktion

<Warning>
  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.
</Warning>

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 |


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/de/packages/laravel-boost-copilot-cli.md)
- [Laravel Scout](/de/scout.md)
- [Redis](/de/redis.md)
- [Artisan-Konsole](/de/artisan.md)
- [Wissen, das Sie vor dem Einstieg in Laravel benötigen](/de/true-tutorial.md)