Laravel Sail - Knowledge of Laravel

¿Qué es Sail?

Laravel Sail es una CLI ligera para operar un entorno de desarrollo Docker de Laravel. Permite montar una aplicación con PHP, MySQL y Redis sin necesidad de conocimientos previos de Docker. En el centro de Sail están el archivo compose.yaml en la raíz del proyecto y el script sail. El script sail ofrece métodos CLI cómodos para manipular los contenedores Docker definidos en compose.yaml. Laravel Sail funciona en macOS, Linux y Windows (mediante WSL2).

En Laravel 13, Sail ya no es el entorno de desarrollo estándar. Se ha eliminado laravel/sail del composer.json del esqueleto y en su lugar se ofrece el comando composer setup. El estándar es ejecutar la aplicación con PHP local + SQLite.

composer setup
composer dev

Si necesitas contenedores Docker, puedes instalar Sail como hasta ahora.

Sail es una herramienta exclusiva de desarrollo local. No está pensada para producción. Prepara una configuración Docker o de nube adecuada para producción.

Instalación

Instalación en un proyecto existente

Instala el paquete con Composer.

Añadir el paquete Sail

composer require laravel/sail --dev

Publicar los archivos de configuración

Ejecuta el comando Artisan sail:install. Publica compose.yaml en la raíz y añade las variables de entorno necesarias a .env.

php artisan sail:install

De forma interactiva puedes elegir servicios: MySQL, Redis, Mailpit, etc.

Arrancar Sail

./vendor/bin/sail up

La primera vez tarda un poco al descargar imágenes Docker. Después puedes acceder en http://localhost.

Con Docker Desktop for Linux, ejecuta docker context use default para usar el contexto default. Si aparecen errores de permisos en el contenedor, pon la variable SUPERVISOR_PHP_USER a root.

Añadir servicios

Para añadir servicios a una instalación existente de Sail, usa sail:add.

php artisan sail:add

Uso con Devcontainer

Si quieres desarrollar dentro de un Devcontainer, usa --devcontainer.

php artisan sail:install --devcontainer

Configuración

Alias en la shell

Por defecto necesitas escribir ./vendor/bin/sail cada vez. Con un alias puedes usar solo sail.

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

Añádelo a ~/.zshrc o ~/.bashrc y reinicia la shell.

sail up

Con el alias configurado, en todos los ejemplos de esta documentación puedes usar sail en lugar de ./vendor/bin/sail.

Reconstrucción de imágenes

Para mantener los paquetes actualizados, reconstruye las imágenes.

docker compose down -v

sail build --no-cache

sail up

Arranque y parada

Para arrancar todos los contenedores definidos en compose.yaml, usa up.

# En primer plano
sail up

# En segundo plano
sail up -d

Para detener, usa stop; si está en primer plano, pulsa Ctrl + C.

sail stop

Flujo de arranque

Ejecución de comandos

Con Sail, la aplicación se ejecuta dentro de un contenedor Docker. Ejecuta a través de sail los comandos PHP, Artisan, Composer y Node/NPM.

Los comandos php artisan, composer y npm que aparecen habitualmente en la documentación oficial de Laravel, con Sail se ejecutan anteponiendo sail.

Comandos PHP

sail php --version

sail php script.php

Comandos Composer

sail composer require laravel/sanctum

Comandos Artisan

sail artisan migrate

sail artisan queue:work

Comandos Node / NPM

sail node --version

sail npm run dev

# Con Yarn
sail yarn

CLI del contenedor (shell)

También puedes abrir una sesión Bash dentro del contenedor.

sail shell

# Conectar como root
sail root-shell

Para abrir una sesión de Tinker:

sail tinker

Servicios

Resumen de los servicios que ofrece Sail. Puedes seleccionarlos durante sail:install.

MySQL

Viene incluido por defecto en compose.yaml. Los datos se persisten en un volumen Docker. En el primer arranque se crean automáticamente dos bases de datos: una para la app y otra testing. Configura DB_HOST en .env como mysql para acceder desde la app.

DB_HOST=mysql
DB_PORT=3306

Para conectar desde la máquina anfitriona, usa un cliente GUI como TablePlus. Puerto por defecto: 3306.

Redis

Configura REDIS_HOST en .env como redis para acceder desde la app.

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

Si prefieres Valkey como alternativa a Redis, configura REDIS_HOST como valkey.

Mailpit

Captura el correo enviado durante el desarrollo y lo muestra en una interfaz web.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Con Sail en marcha, accede a la UI de Mailpit en http://localhost:8025.

Meilisearch / Typesense

Prueba búsqueda de texto completo integrándolos con Laravel Scout.

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

RustFS (almacenamiento compatible con S3)

Si en producción usarás Amazon S3, puedes emular un almacenamiento compatible con S3 en local.

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

Ejecución de pruebas

sail test

sail test --group orders

sail test equivale internamente a sail artisan test. Se usa la base de datos testing dedicada, sin afectar a los datos de desarrollo.

Laravel Dusk

Con Sail puedes ejecutar pruebas de navegador de Dusk sin instalar Selenium localmente. Descomenta el servicio Selenium en compose.yaml.

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

En Apple Silicon (M1/M2/M3), usa la imagen selenium/standalone-chromium.

Ejecuta los tests de Dusk.

sail dusk

Versiones de PHP / Node

Cambiar la versión de PHP

Cambia build.context del contenedor laravel.test en compose.yaml.

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

Tras cambiar, reconstruye la imagen.

sail build --no-cache
sail up

Extensiones adicionales de PHP

Las imágenes de Sail incluyen las extensiones habituales. Si necesitas más, añade PHP_EXTENSIONS como argumento de build en el servicio laravel.test, con las extensiones separadas por espacios; se instalarán al construir la imagen.

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

Después de actualizar compose.yaml, reconstruye la imagen.

sail build --no-cache
sail up

Cambiar la versión de Node

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

Compartir el sitio públicamente

Para previsualizarlo con compañeros o probar webhooks puedes exponer temporalmente el sitio.

sail share

Se genera una URL aleatoria del tipo laravel-sail.site. Para que los helpers de generación de URL funcionen correctamente, configura los proxies de confianza en bootstrap/app.php.

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

También puedes indicar un subdominio.

sail share --subdomain=my-sail-site

Xdebug

Activación

Publica los archivos de configuración con sail:publish y añade en .env:

SAIL_XDEBUG_MODE=develop,debug,coverage

Comprueba que el php.ini publicado contenga:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Reconstruye la imagen.

sail build --no-cache

Depuración desde CLI

# Sin Xdebug
sail artisan migrate

# Con Xdebug
sail debug migrate

Depuración desde el navegador

Consulta la documentación de Xdebug para iniciar la sesión de depuración desde el navegador. Con PhpStorm resulta útil configurar Zero-configuration debugging.

Sail sirve la aplicación con artisan serve. El soporte para XDEBUG_CONFIG y XDEBUG_MODE está desde Laravel 8.53.0. Con versiones anteriores la conexión de depuración no funciona.

Personalización

Para personalizar el Dockerfile o los archivos de configuración de Sail, publícalos con sail:publish.

sail artisan sail:publish

Después de publicarlos, el Dockerfile queda en el directorio docker/. Tras modificarlo, reconstruye la imagen.

sail build --no-cache

Diferencias con producción

Sail está pensado solo para desarrollo local. No es adecuado para producción. Para desplegar con Docker en producción considera servicios como Laravel Cloud, Forge o Ploi, o tu propia configuración Docker Compose / Kubernetes.

Diferencias principales:

Aspecto	Sail (local)	Producción
Objetivo	Desarrollo y depuración	Prestación del servicio
Xdebug	Se puede habilitar	Se recomienda deshabilitar
Mailpit	Captura correos y los previsualiza	Servidor de correo real
Persistencia de datos	Volúmenes Docker	BD gestionada, etc.
Rendimiento	Sin optimización	Optimización imprescindible

​¿Qué es Sail?

​Instalación

​Instalación en un proyecto existente

​Añadir servicios

​Uso con Devcontainer

​Configuración

​Alias en la shell

​Reconstrucción de imágenes

​Arranque y parada

​Flujo de arranque

​Ejecución de comandos

​Comandos PHP

​Comandos Composer

​Comandos Artisan

​Comandos Node / NPM

​CLI del contenedor (shell)

​Servicios

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS (almacenamiento compatible con S3)

​Ejecución de pruebas

​Laravel Dusk

​Versiones de PHP / Node

​Cambiar la versión de PHP

​Extensiones adicionales de PHP

​Cambiar la versión de Node

​Compartir el sitio públicamente

​Xdebug

​Activación

​Depuración desde CLI

​Depuración desde el navegador

​Personalización

​Diferencias con producción

¿Qué es Sail?

Instalación

Instalación en un proyecto existente

Añadir servicios

Uso con Devcontainer

Configuración

Alias en la shell

Reconstrucción de imágenes

Arranque y parada

Flujo de arranque

Ejecución de comandos

Comandos PHP

Comandos Composer

Comandos Artisan

Comandos Node / NPM

CLI del contenedor (shell)

Servicios

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS (almacenamiento compatible con S3)

Ejecución de pruebas

Laravel Dusk

Versiones de PHP / Node

Cambiar la versión de PHP

Extensiones adicionales de PHP

Cambiar la versión de Node

Compartir el sitio públicamente

Xdebug

Activación

Depuración desde CLI

Depuración desde el navegador

Personalización

Diferencias con producción