Laravel Sail

Come costruire un ambiente di sviluppo locale basato su Docker senza configurazioni usando Laravel Sail.

​

Cos’è Sail

Laravel Sail è un’interfaccia a riga di comando leggera per gestire l’ambiente di sviluppo Docker di Laravel. Ti permette di costruire un’applicazione Laravel con PHP, MySQL e Redis senza conoscenze preliminari di Docker.

Il cuore di Sail è il file compose.yaml collocato nella root del progetto e lo script sail. Lo script sail fornisce comodi metodi CLI per gestire i container Docker definiti in compose.yaml.

Laravel Sail funziona su macOS, Linux e Windows (tramite WSL2).

In Laravel 13 Sail non è più l’ambiente di sviluppo standard. laravel/sail è stato rimosso dal composer.json dello scheletro e al suo posto è disponibile il comando composer setup. Lo standard è la configurazione con PHP locale + SQLite.

composer setup
composer dev

Se ti servono i container Docker, puoi comunque installare e usare Sail.

Sail è uno strumento pensato esclusivamente per lo sviluppo locale. Non è pensato per l’uso in produzione. Per la produzione prepara separatamente una configurazione Docker / cloud adeguata.

---

​

Installazione

​

Installazione in un progetto esistente

Installa il pacchetto con Composer.

1. Aggiungi il pacchetto Sail

   composer require laravel/sail --dev
   
2. Pubblica i file di configurazione

   Esegui il comando Artisan sail:install. Questo comando pubblica compose.yaml nella root del progetto e aggiunge le variabili d’ambiente necessarie a .env.

   php artisan sail:install
   

   Puoi scegliere i servizi in modo interattivo. Seleziona MySQL, Redis, Mailpit, ecc.

3. Avvia Sail

   ./vendor/bin/sail up
   

   Al primo avvio il download delle immagini Docker richiede un po’ di tempo. Dopo l’avvio puoi accedere all’applicazione su http://localhost.

Se usi Docker Desktop for Linux, esegui docker context use default per usare il contesto default. Se all’interno dei container si verificano errori di permessi sui file, imposta la variabile d’ambiente SUPERVISOR_PHP_USER su root.

​

Aggiungere servizi aggiuntivi

Per aggiungere servizi a un’installazione Sail esistente, usa il comando sail:add.

php artisan sail:add

​

Uso di Devcontainer

Se vuoi sviluppare all’interno di un Devcontainer, usa l’opzione --devcontainer.

php artisan sail:install --devcontainer

---

​

Configurazione

​

Impostazione degli alias della shell

Di default devi digitare ogni volta ./vendor/bin/sail. Con un alias della shell puoi digitare solo sail.

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

Aggiungilo a ~/.zshrc o ~/.bashrc e riavvia la shell.

sail up

Dopo aver impostato l’alias, in tutti gli esempi di comando di questa documentazione puoi scrivere sail al posto di ./vendor/bin/sail.

​

Ricostruzione delle immagini

Se vuoi mantenere i pacchetti aggiornati, ricostruisci le immagini.

docker compose down -v

sail build --no-cache

sail up

---

​

Avvio e arresto

Per avviare tutti i container Docker definiti in compose.yaml usa il comando up.

# Avvio in foreground
sail up

# Avvio in background
sail up -d

Per fermarli usa il comando stop, oppure premi Ctrl + C se sono in foreground.

sail stop

​

Flusso di avvio

---

​

Esecuzione dei comandi

Con Sail l’applicazione gira all’interno di container Docker. I comandi PHP, Artisan, Composer, Node / NPM si eseguono tutti tramite sail.

I comandi php artisan, composer e npm frequenti nella documentazione ufficiale di Laravel devono essere eseguiti in ambiente Sail anteponendo sail.

​

Comandi PHP

sail php --version

sail php script.php

​

Comandi Composer

sail composer require laravel/sanctum

​

Comandi Artisan

sail artisan migrate

sail artisan queue:work

​

Comandi Node / NPM

sail node --version

sail npm run dev

# Se usi Yarn
sail yarn

​

CLI del container (shell)

Puoi anche aprire direttamente una sessione Bash all’interno del container.

sail shell

# Collegati come utente root
sail root-shell

Per aprire una sessione Tinker:

sail tinker

---

​

Servizi

Panoramica dei servizi forniti da Sail. Puoi selezionarli con sail:install durante l’installazione.

​

MySQL

Incluso di default in compose.yaml. I dati sono persistenti tramite Docker Volume. Al primo avvio vengono create automaticamente due database: uno per l’app e uno per il testing.

Imposta DB_HOST a mysql in .env per accedervi dall’app.

DB_HOST=mysql
DB_PORT=3306

Per collegarti dalla macchina locale usa un tool GUI come TablePlus. La porta predefinita è 3306.

​

Redis

Impostando REDIS_HOST a redis in .env puoi accedere a Redis dall’app.

REDIS_HOST=redis
REDIS_PORT=6379

​

Valkey

Se usi Valkey come alternativa a Redis, imposta REDIS_HOST su valkey.

​

Mailpit

Cattura le email inviate durante lo sviluppo locale e le mostra nell’anteprima Web UI.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Con Sail attivo puoi accedere alla Web UI di Mailpit su http://localhost:8025.

​

Meilisearch / Typesense

Puoi provare la ricerca full-text integrata con Laravel Scout.

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

​

RustFS (storage S3-compatibile)

Se prevedi di usare Amazon S3 in produzione, puoi emulare in locale uno storage S3-compatibile.

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

---

​

Esecuzione dei test

sail test

sail test --group orders

sail test è internamente equivalente a sail artisan test. Di default viene predisposto un database testing dedicato, così non influisci sui dati di sviluppo.

​

Laravel Dusk

Con Sail puoi eseguire i test browser Dusk senza installare Selenium in locale. Rimuovi il commento dal servizio Selenium in compose.yaml.

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

Su Apple Silicon (M1/M2/M3) usa l’immagine selenium/standalone-chromium.

Poi esegui i test Dusk.

sail dusk

---

​

Versione di PHP / Node

​

Cambiare la versione di PHP

Modifica build.context del container laravel.test in compose.yaml.

# PHP 8.5 (predefinito)
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

Dopo la modifica ricostruisci l’immagine.

sail build --no-cache
sail up

​

Estensioni PHP aggiuntive

L’immagine runtime di Sail include estensioni PHP comuni. Se l’applicazione richiede estensioni aggiuntive, aggiungi l’argomento di build PHP_EXTENSIONS separando i valori con spazi al servizio laravel.test di compose.yaml per installarle durante il build dell’immagine.

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

Dopo aver aggiornato compose.yaml, ricostruisci le immagini dei container.

sail build --no-cache
sail up

​

Cambiare la versione di Node

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

---

​

Condivisione pubblica del sito

Per anteprima ai colleghi o test di webhook, puoi pubblicare temporaneamente il sito all’esterno.

sail share

Viene generato un URL casuale su laravel-sail.site. Perché gli helper di generazione URL funzionino correttamente, configura i proxy fidati in bootstrap/app.php.

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

Puoi anche specificare un sottodominio.

sail share --subdomain=my-sail-site

---

​

Xdebug

​

Attivazione

Prima pubblica i file di configurazione con sail:publish, poi aggiungi in .env:

SAIL_XDEBUG_MODE=develop,debug,coverage

Verifica che il file php.ini pubblicato contenga:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Dopo la modifica ricostruisci l’immagine.

sail build --no-cache

​

Debug via CLI

# Esecuzione senza Xdebug
sail artisan migrate

# Esecuzione con Xdebug
sail debug migrate

​

Debug via browser

Per le istruzioni per avviare una sessione di debug dal browser consulta la documentazione ufficiale di Xdebug. Se usi PhpStorm è comoda la configurazione Zero-configuration debugging.

Sail serve l’app con artisan serve. L’accettazione di XDEBUG_CONFIG e XDEBUG_MODE è a partire da Laravel 8.53.0. Nelle versioni precedenti la connessione di debug non funzionerà.

---

​

Personalizzazione

Per personalizzare i Dockerfile e i file di configurazione di Sail, pubblicali con il comando sail:publish.

sail artisan sail:publish

Dopo la pubblicazione i Dockerfile si trovano nella directory docker/. Dopo le modifiche ricostruisci i container.

sail build --no-cache

---

​

Differenze rispetto alla produzione

Sail è un ambiente dedicato allo sviluppo locale. Non è pensato per l’uso in produzione. Per il deploy Docker in produzione valuta servizi come Laravel Cloud, Forge, Ploi o una tua configurazione Docker Compose / Kubernetes.

Le principali differenze tra Sail e la produzione sono riassunte qui sotto.

Aspetto	Sail (locale)	Produzione
Obiettivo	Sviluppo, debug	Erogazione del servizio
Xdebug	Attivabile	Consigliato disattivato
Mailpit	Cattura ed anteprima delle email	Vero server di posta
Persistenza dati	Docker Volume	DB gestito, ecc.
Performance	Nessuna ottimizzazione	Ottimizzazione essenziale