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

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

## ¿Qué es Sail?

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

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

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

  Si necesitas contenedores Docker, puedes instalar Sail como hasta ahora.
</Warning>

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

***

## Instalación

### Instalación en un proyecto existente

Instala el paquete con Composer.

<Steps>
  <Step title="Añadir el paquete Sail">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

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

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

    De forma interactiva puedes elegir servicios: MySQL, Redis, Mailpit, etc.
  </Step>

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

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

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

### Añadir servicios

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

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

### Uso con Devcontainer

Si quieres desarrollar dentro de un [Devcontainer](https://code.visualstudio.com/docs/remote/containers), usa `--devcontainer`.

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

```shell theme={null}
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
```

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

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

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

### Reconstrucción de imágenes

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

```shell theme={null}
docker compose down -v

sail build --no-cache

sail up
```

***

## Arranque y parada

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

```shell theme={null}
# En primer plano
sail up

# En segundo plano
sail up -d
```

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

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

### Flujo de arranque

```mermaid theme={null}
flowchart TD
    A["Ejecuta sail up"] --> B{"¿Existen las imágenes<br>de Docker?"}
    B -- No --> C["Construir/<br>descargar imagen"]
    C --> D["Arrancar contenedores"]
    B -- Sí --> D
    D --> E["Contenedor laravel.test<br>(app) arrancado"]
    D --> F["Contenedor mysql arrancado"]
    D --> G["Contenedor redis arrancado"]
    D --> H["Contenedor mailpit arrancado"]
    E --> I["Accesible en http://localhost"]
```

***

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

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

### Comandos PHP

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

sail php script.php
```

### Comandos Composer

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

### Comandos Artisan

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

sail artisan queue:work
```

### Comandos Node / NPM

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

```shell theme={null}
sail shell

# Conectar como root
sail root-shell
```

Para abrir una sesión de Tinker:

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

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

Para conectar desde la máquina anfitriona, usa un cliente GUI como [TablePlus](https://tableplus.com). Puerto por defecto: `3306`.

### Redis

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

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

### Valkey

Si prefieres [Valkey](https://valkey.io/) como alternativa a Redis, configura `REDIS_HOST` como `valkey`.

### Mailpit

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

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

```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
```

***

## Ejecución de pruebas

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

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

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

Ejecuta los tests de Dusk.

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

***

## Versiones de PHP / Node

### Cambiar la versión de PHP

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

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

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

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

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

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

### Cambiar la versión de Node

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

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

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

También puedes indicar un subdominio.

```shell theme={null}
sail share --subdomain=my-sail-site
```

***

## Xdebug

### Activación

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

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

Comprueba que el `php.ini` publicado contenga:

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

Reconstruye la imagen.

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

### Depuración desde CLI

```shell theme={null}
# Sin Xdebug
sail artisan migrate

# Con Xdebug
sail debug migrate
```

### Depuración desde el navegador

Consulta la [documentación de Xdebug](https://xdebug.org/docs/step_debug#web-application) para iniciar la sesión de depuración desde el navegador.
Con PhpStorm resulta útil configurar [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html).

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

***

## Personalización

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

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

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

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

***

## Diferencias con producción

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

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 |


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/es/packages/laravel-boost-copilot-cli.md)
- [Laravel Scout](/es/scout.md)
- [Consola Artisan](/es/artisan.md)
- [Redis](/es/redis.md)
- [Conocimientos necesarios antes de empezar con Laravel](/es/true-tutorial.md)