Laravel Sail es una herramienta que nos aporta una nueva alternativa para crear tu entorno de desarrollo de aplicaciones Laravel. Esta herramienta está basada en Docker, lo que nos permite tener todos los programas necesarios para ejecutar aplicaciones Laravel sin necesidad de instalar estos programas directamente en el ordenador.

En este artículo vamos a cubrir los siguientes puntos:

• Por qué usar Laravel Sail
• Qué es Laravel Sail
• Cómo configurar WSL2 en Windows
• Configuración de Docker en tu equipo
• Instalar Sail
• Instalar nuevos servicios de Sail en un proyecto donde ya tienes Sail
• Comandos para usar Laravel Sail
• Acceso a la base de datos de Sail para poder administrar
• Trabajar con npm desde Sail
• Restaurar un proyecto con Sail que has clonado
• Ver emails enviados al desarrollar, con Mailpit
• Videotutorial de Laravel Sail

Por qué usar Laravel Sail

Los motivos son diversos, pero creo que el más importante sería la posiblidad de convivencia de varios proyectos Laravel en una misma máquina sin complicaciones.

A lo largo de tu vida como desarrollador puedes mantener diversos proyectos, nuevos proyectos con versiones de PHP y Laravel actuales, pero también proyectos antiguos que tienen requisitos menos modernos. Por ejemplo podrías tener un proyecto con Laravel 6, 7 u 8 sobre PHP 7.4 pero otro proyecto de Laravel 9 sobre PHP 8.

Hacer convivir versones de PHP en tu máquina puede ser complejo. Si actualizas PHP en tu ordenador posíblemente afectará a proyectos antiguos, pero si no lo haces posíblemente no puedas instalar Laravel en versiones más modernas. Es un dilema que no queda fácilmente resoluble usando sistemas como Valet, que te instalan PHP directamente en tu máquina.

Sin embargo, en un proyecto Laravel Sail sí que es posible tener una versión de PHP totalmente personalizada, así como versiones de MySQL o MariaDB, PostgreSQL o cualquier otro software del que dependas en general.

Además, desarrollar en contenedores también puede colaborar a mantener tu ordenador más limpio. Gracias a Docker, un software para crear y gestionar contenedores que ha tomado mucha tracción en los últimos años, conseguimos tener más limpio el ordenador que usamos para desarrollar, ya que no necesitamos instalar en la máquina host todo el stack de programas necesarios para ejecutar los sitios. Además, la virtualización con Docker es realmente ligera y consume pocos recursos en el ordenador, en comparación con alternativas más tradicionales como Virtualbox.

En todo caso, seguramente todos los lectores tendrán una idea de las ventajas de Docker, por lo que pasaremos directamente al grano.

Qué es Laravel Sail

Sail es una interfaz de línea de comandos para trabajar con entornos de desarrollo basados en Docker para ejecutar aplicaciones Laravel. Ofrece toda una abstracción a los procesos de configuración de Docker que tendríamos que hacer manual si queremos usar esta herramienta como entorno de desarrollo en local. Ofrece imágenes de Docker ya preparadas para las aplicaciones Laravel, con el servidor web, compatibilidad con PHP, MySQL o MariaDB, Redis y otros programas dentro del stack típico de Laravel.

Puedes usar Laravel Sail sin tener ni idea de cómo funciona Docker, lo que es una maravilla para quien quiere desarrollar sin preocuparse por las complejidades de crear su propio entorno dockerizado.

Al final, por debajo, Laravel Sail usa las mismas herramientas que usarías si trabajases directamente con Docker, como su docker-compose.yml, etc. Como extra, Sail nos ofrece toda una serie de comandos para interaccionar con la máquina virtual donde se están ejecutando las aplicaciones, como una especie de túnel mediante el cual podemos interactuar con los servidores de desarrollo, sin necesidad de meternos en ellos.

Dónde puedes usar Laravel Sail

Una de las ventajas de Laravel Sai es que es perfectamente compatible con todos los sistemas operativos típicos para desarrollar. Puedes usarlo en Linux, MacOS y Windows.

Solo hay un detalle para los usuarios de Windows y es que, para poder trabajar con Sail necesitamos tener WSL2 (Windows Subsystem Linux 2). WSL2 permite disponer de un Linux en tu Windows, bajo el mismo sistema de archivos y Sail se aprovecha de esta posibilidad para ejecutarse sobre un sistema Linux, en vez de un sistema Windows. Configurar WSL2 no tiene mucha complejidad, pero representa un paso adicional para los usuarios de Windows.

Cómo configurar WSL2 en Windows

Si eres usuario de Linux y Mac puedes saltarte esta sección. En otro caso, si quieres usar Sail en Windows, tienes que comenzar por instalar WSL2.

Microsoft ha publicado una guía de instalación de WSL2 en Windows, que está perfectamente explicada paso por paso y en perfecto español, por lo que te recomendamos seguirla.

No tardarás mucho en tener WSL2 en tu sistema y disfrutar con la experiencia de tener acceso a todo un Linux en tu Windows, operando sobre el mismo sistema de archivos. Podrás abrir sesiones de consola y trabajar con tu ordenador con comandos Linux en la distribución que más te guste.

Comandos básicos de WSL en Windows

Qué no te abrume la cantidad de texto que encontrarás en esa página porque realmente es todo muy sencillo y se resume en ejecutar Power Shell en modo administrador y lanzar un comando.

Para abrir Power Shell en modo administrador haces clic derecho sobre el icono y escoges la opción "Abrir como administrador".

El comando para instalar WSL en Windows 10 o Windows 11 es el siguiente:

wsl --install

Solo hay algunos detalles a tener en cuenta. Primero que este comando requiere que no tengas instalado antes WSL. Si lo tuvieras y quisieras actualizar a la versión más nueva haces este otro comando:

wsl --update

Si ya tuvieras WSL en tu máquina te recomiendo hacer esa actualización. Si tienes WSL pero no tienes alguna distribución de Linux instalada con el comando mencionado antes wsl --install se instalará una distro predeterminada, que es Ubuntu.

Personalmente recomiendo Ubuntu, pero si tuvieras otras preferencias en principio no sería un problema. Puedes lanzar el siguiente comando para ver las distros que están disponibles:

wsl --list --online

Te aparecerá los nombres de un listado de posibles distribuciones instalables en WSL. Luego para instalar la distribución que quieras lo haces con el comando como este:

wsl --install -d Debian

Ese comando te instalará Debian, pero podrías poner cualquier otra distro de la lista que viste antes.

El resto de las notas que encontrarás en el artículo de Microsoft están dedicadas a resolver problemas comunes con WSL en Windows. Por lo que si en tu equipo surge cualquier problema es una buena fuente de información para tratar de resolverlo.

Configuración de Docker en tu equipo

Tendrás que instalar Docker en tu equipo. Si estás trabajando con Windows o Mac te recomendamos instalar Docker Desktop, ya que te ofrece una interfaz gráfica para trabajar con Docker que facilita un tanto las cosas.

Si no tienes Docker, solo con instalar Docker Desktop se te instalará todo lo necesario para trabajar.

Puedes probar si Docker está funcionando en tu sistema lanzando el comando siguiente:

docker -v

Si estás en Windows este comando lo tienes que lanzar desde WSL2, con una sesión de terminal sobre la distro que tengas instalada en WSL2.

Instalar Sail

Ahora que tenemos los componentes que nos hacen falta para empezar en nuestro equipo, básicamente Docker (y WLS2 en el caso de Windows), podemos comenzar a usar Sail en un proyecto Laravel. Llegado a este punto podemos encontrarnos en dos escenarios:

• Queremos crear un nuevo proyecto Laravel donde usaremos Sail como entorno de desarrollo
• Queremos usar Sail en un proyecto Laravel ya existente

Ambas alternativas requieren pasos distintos que vamos a tratar en los siguientes puntos.

Iniciar un proyecto Laravel con Sail

Si estamos comenzando un proyecto Laravel desde cero y queremos usar Sail como plataforma de desarrollo, en lugar de otras alternativas como Homestead o Valet, podemos lanzar un comando de consola, que nos proporcionará la instalación de un proyecto nuevo, con todos los archivos, dependencias instaladas y Sail configurado.

Para ello debemos asegurarnos que tenemos Docker instalado en la máquina, como hemos explicado en los pasos anteriores. Una vez disponemos de Docker en el terminal, lanzamos el siguiente comando:

curl -s "https://laravel.build/nueva-aplicacion-laravel" | bash

Una vez se ponga a funcionar ese comando, tendremos una carpeta con el mismo nombre del proyecto, donde se colocarán todos los archivos de Laravel. Para hacer que el proyecto se ponga en marcha lanzaremos los siguientes comandos:

Primero nos moveremos a la carpeta del proyecto, que hemos indicado al crearlo en el comando anterior:

cd nueva-aplicacion-laravel

A continuación, lanzamos el comando que arranca Sail y pone en marcha el proyecto.

./vendor/bin/sail up

La primera vez que arrancas el proyecto verás que se descarga la imagen Docker usada para los contenedores. Este proceso puede ser un poco largo, dependiendo de tu máquina y por supuesto de la conexión a Internet. Sin embargo, no debes preocuparte de que tarde mucho, ya que esta descarga solo se producirá una vez.

Una vez en marcha el proyecto podremos acceder a la URL de localhost para verlo en marcha: http://localhost

Iniciar Sail escogiendo los servicios a instalar

Este segundo punto sería exactamente en el escenario del punto anterior: queremos crear un proyecto nuevo Laravel en el que vamos a trabajar con Sail. La diferencia en este caso es que queremos escoger los servicios de Sail instalados.

¿Por qué podremos necesitar escoger los servicios de Sail que se incorporarán en el proyecto? bueno, posiblemente no lo necesites, pero en mi caso suelo trabajar preferentemente con MariaDB en lugar de MySQL, por eso quiero que el instalador me tome como gestor de bases de datos MariaDB. Sin embargo, para otros proyectos puede que no se necesario instalar Redis por ejemplo, o que no necesites Selenium.

De este modo podrás seleccionar qué cosas de Sail quieres que se instalen:

curl -s "https://laravel.build/backend2-app?with=mariadb,redis,mailpit" | bash

Anteriormente el servicio que hacía la captura y visualización de los emails salientes de las aplicaciones Laravel era "mailhog", sin embargo, actualmente en Sail ya no se usa Mailhog, ya que este software se encuentra en desuso. Los servicios a instalar deberían incluir el sustituto, que es una aplicación llamada Mailpit. Si ves que en algún tutorial se menciona el servicio de mailhog quiere decir que no han actualizado el texto. Simplemente habría que sustituir mailhog por mailpit. El concepto sigue siendo el mismo, por lo que este cambio atañe únicamente a la elección de los servicios,

Como puedes ver, con el parámetro "with" podemos indicar que vamos a usar solamente los servicios de mariadb, redis y mailhog. Puedes escoger tus propias alternativas, si por ejemplo necesitas trabajar con el sistema gestor PostgreSQL.

Instalar Laravel Sail un proyecto existente

Laravel Sail es un entorno de desarrollo que viene instalado en cualquier aplicación de Laravel creada nueva. Sin embargo, si tenemos ya un proyecto de Laravel antiguo y queremos usar Sail, necesitamos instalarlo manualmente.

El proceso es muy sencillo, gracias a Composer, usando el comando siguiente:

composer require laravel/sail --dev

Ahora ya tenemos Sail en nuestro sistema y podemos usar el CLI que nos ofrece. El primer comando que ejecutaremos es el que nos permite traernos el archivo "docker-compose.yml" a la raíz del proyecto:

php artisan sail:install

Una vez lanzado el comando se solicitará que seleccionemos qué servicios de Sail queremos instalar en el proyecto. Para ello el terminal nos mostrará una serie de opciones de servicios como las que puedes ver en la imagen siguiente:

Tendremos que introducir las opciones que correspondan en el terminal. Si son varias las podemos separar por comas. Por ejemplo, si queremos instalar "mariadb", "redis" y "mailpit" escribiríamos "2,3,7" y apretamos la tecla enter.

Si por algún motivo quieres añadir más tarde nuevos servicios a instalar, podemos repetir este proceso las veces que sea, añadiendo tantos servicios de Sail como queramos instalar.

Estas acciones irán componiendo el código de un archivo llamado docker-compose.yml, que usa Docker para indicar qué contenedores se deben levantar en el sistema con cada proyecto.

Instalar Sail en un proyecto existente sin tener PHP o Composer

El problema de los pasos anteriores para instalar Sail en un proyecto laravel existente es que necesitas PHP y Composer. Eso no es siempre posible, dependiendo de cada caso, puesto que no siempre tienes PHP o Composer en el ordenador host, o no los tienes en las versiones adecuadas para funcionar.

En estos casos puedes usar Docker para crear un contenedor con el cual instalar Sail en tu proyecto. Es una tarea sencilla, aunque necesitas saber los comandos adecuados.

Para instalar Laravel Sail en el proyecto existente mediante un contenedor Docker puedes lanzar este comando:

docker run --rm -v $(pwd):/app -w /app laravelsail/php82-composer:latest composer require laravel/sail --dev --ignore-platform-req=ext-gd

Eso creará un contenedor con PHP y Composer lo usará para instalar Sail y luego lo eliminará.

Además estamos ignorando la librería GD, que no es que sea necesario, pero a veces puedes tener dependencias que requieran requisitos como este. Dado el contenedor que estamos usando está bastante "pelado", es posible que no tenga todo lo que necesites y, en ese caso, podría fallar. Esta misma manera de proceder puede servirte para ignorar otras dependencias que puedan ser necesarias en tu plataforma.

Luego, para ejecutar el comando de instalación de Sail necesitas PHP y Artisan, por tanto, si no tienes PHP necesitarás levantar otro contenedor.

docker run --rm -v $(pwd):/app -w /app laravelsail/php82-composer:latest php artisan sail:install

Eso te creará el archivo docker-compose.yml para levantar los contenedores de Sail.

El único problema de este modo de trabajo es que los contenedores no los puedes elegir, porque no aparece el diálogo interactivo. Puedes definirlos entonces en el propio comando de instalación. Por ejemplo, si quieres instalar MariaDB en lugar de MySQL el comando sería así:

docker run --rm -v $(pwd):/app -w /app laravelsail/php82-composer:latest php artisan sail:install --with=mariadb

Espero que estos comandos te sirvan de guía y pistas para saber cómo solucionar los casos en los que tengas que instalar Sail en un proyecto Laravel que ya tengas o heredado, vía Docker, o lo que es lo mismo, sin necesidad de tener instalado PHP o Composer.

Instalar nuevos servicios de Sail en un proyecto donde ya tienes Sail

En ocasiones tienes ya un proyecto en el que vienes trabajando con Sail y en algún momento requieres nuevos servicios que te proveen otros contenedores de Docker que no tienes todavía instalados. Si ocurre esto tienes que seguir el procedimiento similar al que hemos explicado para instalar Sail en un proyecto existente.

Lanzas el comando de instalación de Sail:

sail artisan sail:install

No te preocupes por si este comando rompe algo que tengas anteriormente. En realidad no será así porque detectará lo que tienes actualmente instalado.

Luego seleccionas entre las opciones que se presentan qué servicios nuevos necesitas instalar. Esto realizará los cambios oportunos en el docker-compose.yml, colocando el código necesario para crear los nuevos contenedores.

Por último lanzas el comando de build del propio Sail, ya que es necesario ejecutarlo cada vez que se hacen cambios en el docker-compose.yml.

sail build

Comandos para usar Laravel Sail

A partir de ahora, para trabajar con tus proyectos Laravel, muchas de las operativas que hacías directamente mediante el terminal necesitarás realizarlas por medio de comandos de Laravel Sail. En los siguientes puntos vamos a explicarte cuáles son estos comandos, desde arrancar los contenedores de tu entorno de desarrollo a instalar dependencias.

Arrancar Sail

Ahora que tenemos el archivo docker-compose.yml podemos levantar la aplicación Laravel usando Docker, mediante el comando siguiente:

./vendor/bin/sail up

Con esto nuestra aplicación estará en marcha y podremos verla desde http://localhost o http://127.0.0.1.

Además, si instalaste Docker Desktop en tu ordenador, podrás ver que los contenedores están corriendo. Aparecerá algo como lo que puedes ver en esta imagen:

Crear un Alias a Sail para acortar el comando

Si creas en tu sistema un alias podrías ahorrarte la parte de escibir la ruta de Sail en ./vendor/bin/sail todo el rato.

alias sail="bash ./vendor/bin/sail"

Así, lanzar los comandos de Sail será tan rápido como escribir:

sail up

Otros comandos de Sail

Aparte del comando "sail up" que acabamos de ver, te resultarán útiles otros comandos de Sail, que permiten como decíamos interactuar con la máquina dockerizada donde se ejecutan las aplicaciones sin necesidad de entrar en ella.

down: Permite parar y eliminar los contenedores.

sail down

artisan: Permite acceder a Artisan desde dentro del contenedor, necesario para correr migraciones y otras cuestiones como poner en marcha el sistema de ejecución de colas y jobs.

sail artisan migrate

composer: Podemos instalar dependencias directamente con el Composer que se ejecuta dentro del contenedor.

sail composer require watson/sitemap

share: Este comando sirve para que tu sitio local se pueda acceder mediante un túnel desde otros ordenadores conectados a Internet.

sail share

Ten en cuenta que el comando "share" requiere de algunas configuraciones extra que están explicadas en la documentación. Recuerda que tienes más información sobre comandos útiles de Laravel Sail en la documentación de Laravel.

mysql: Si quieres abrir una sesión de línea de comandos con MySQL con el contenedor que se está ejecutando, entonces puedes usar este comando. Simplemente te abre el cliente mysql conectado con la base de datos de tu proyecto.

sail mysql

De manera similar dispones de otros comandos para acceder a otros sistemas gestores de bases de datos, por ejemplo MariaDB.

sail mariadb

Acceso a la base de datos de Sail para poder administrar

Algo que seguramente querrás hacer en algún momento es acceder a la base de datos que se genera en los contenedores con Laravel Sail, para por ejemplo restaurar un backup de una base de datos, ver qué datos hay en las tablas, etc.

Aunque las bases de datos estén dentro del contenedor es posible acceder mediante un software del estilo de HeidiSQL o Sequel Pro, TablePlus, etc. Para ello necesitas simplemente hacer un forward del puerto, algo que se configura en el archivo .env de tu aplicación.

FORWARD_DB_PORT=3306

Esta configuración de forward no es recomendable en contenedores en producción, pero en el contenedor de desarrollo resulta muy cómoda y a veces imprescindible para trabajar.

Si quieres saber más sobre esta configuración y solucionar casos especiales de puertos ocupados, lee la faq: ¿Cómo acceder a una base de datos MySQL / MariaDB en un contenedor Docker creado con Laravel Sail?

Trabajar con npm desde Sail

Por supuesto, si quieres usar npm para, por ejemplo, instalar dependecnias en tu proyecto, tendrás que anteponer sail al comando correspondiente.

Algunos ejemplos de comandos de npm y Node para Sail que tendrás que usar en tus proyectos serían los siguientes:

Obtener la versión de Node instalada en Sail:

sail node --version

Ejecutar npm para instalar dependencias:

sail npm install

Producir los bundles de Javascript para desarrollo:

sail npm run dev

Restaurar un proyecto con Laravel Sail si no tienes PHP y Composer en local

En algunas máquinas donde no disponemos de PHP y Composer instalado en local puede surgir un problema al intentar instalar / restaurar un proyecto Laravel que funciona con Docker y Sail.

Después de hacer el clonado del repositorio de GitHub, en el caso que en el ordenador que estás trabajando no tengas ni PHP ni Composer instalado, no eres capaz de instalar las dependencias de Composer para restaurar completamente ese proyecto Laravel y por tanto no puedes ejecutar el comando "sail up", porque necesitas las dependencias.

Es un caso de "pescadilla que se muerde la cola":

• Como no tengo instaladas las dependencias, no puedo arrancar el proyecto con Sail
• Como no tengo PHP y Composer en local, no puedo instalar las dependencias.

Incluso a veces, aunque tengas PHP y Composer puede que el proyecto te pida otra versión de PHP y tampoco lo puedas instalar. En esos casos hay una solución en la documentación de Laravel para trabajar con Sail, donde nos ofrecen un comando que justamente nos arregla el problema.

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php82-composer:latest \
    composer install --ignore-platform-reqs

Lo que hace ese comando es lanzar un contenedor donde está PHP y Composer instalado y se encarga de instalar todas las dependencias del proyecto. Después de ejecutar el comando ya tienes tu Sail instalado y podrás realizar los comandos para seguir trabajando con el proyecto.

Otros detalles para restaurar el proyecto Laravel Sail

Ten en cuenta que para restaurar el proyecto también necesitarás hacer algunas cosas extra, que voy a resumir a modo de notas para poder ayudar a quienes lo necesiten.

Primero debes hacerte el archivo .env. Generalmente encontrarás en el proyecto un archivo llamado .env.example. Tendrás que hacer una copia de ese archivo con el nombre .env:

cp .env.example .env

Después de hacer el .env puedes instalar Sail con el comando de Docker anterior.

A continuación arrancas Sail:

sail up

./vendor/bin/sail up

Seguidamente necesitarás restaurar la base de datos con el comando de artisan migrate:

sail php artisan migrate

Este comando te puede dar un error como Access denied for user 'sail'... Si te ocurre esto es porque la base de datos puede que no se haya creado bien. Especialmente ocurre cuando has cambiado el .env o has creado el .env después de haber instalado Sail.

Si estuvieras ante esta situación, lo puedes solucionar simplemente borrando los volúmenes de Sail declarados en el docker-compose.yml. Esto lo haces con el comando:

sail down -v

El comando anterior hará que se borren los volúmenes, por lo que tendrás que crear de nuevo la base de datos. Esto lo haces otra vez el sail up y el sail php artisan migrate.

En principio es lo básico que necesitarás para restaurar la mayoría de los proyectos Laravel donde se usa Sail.

Recuperar la base de datos por medio de un backup

En algunos proyectos necesitamos recupear la base de datos por medio de algún backup, ya sea porque no se estén usando migraciones o porque sea un proyecto que requiere unos datos particulares para funcionar y no tengamos los seeders.

En este caso podemos usar los comandos de conexión con la base de datos mediante el terminal. Por ejemplo, si tu base de datos es MySQL puedes consultar la faq Restaura base de datos MySQL desde un archivo dump .sql en una base de datos local con Laravel Sail.

Ver los emails enviados en la aplicación Laravel con Mailpit

Hasta hace poco Laravel Sail venía con Mailhog, sin embargo recientemente se ha cambiado a otro proyecto llamado Mailpit, ya que el software Mailhog se encuentra abandonado.

Así pues, cada vez que creas un proycto nuevo con Laravel Sail en el archivo docker-compose.yml encontrarás una entrada para un servicio que se llama Mailpit (Esto lo puedes ver en el punto depends_on).

Mailpit se encarga de interceptar los emails que salen desde la aplicación Laravel en el modo de desarrollo y ofrece una interfaz web para poder visualizar los correos electrónicos generados. Lo que nos importa es que podemos acceder a esos correos usando la dirección de localhost y el puerto 8025.

http://localhost:8025

Por supuesto, esta url solo estará activa si tienes Sail arrancado. Además tienes en el archivo .env las configuraciones para Mailpit, donde como default host debe estar el puerto 1025. Esto debería estar en el .env:

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Referencia: Puedes consultar otras informaciones y preguntas y respuestas sobre Sail en la categoría de Laravel Sail.

Videotutorial de Laravel Sail

Acabamos el artículo presentando un videotutorial en el que verás más gráficamente cómo usar Laravel Sail para el inicio y desarrollo de proyectos con el framework PHP Laravel. No se trataron todos los puntos explicados en este artículo pero es una estupenda introducción.