Laravel Sail

Explicamos cómo montar un entorno de desarrollo local basado en Docker sin configuración usando Laravel Sail.

​

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

1. Añadir el paquete Sail

   composer require laravel/sail --dev
   
2. 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.

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