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

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 10, 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.

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,mailhog" | bash

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. Tendremos que introducir las opciones que correspondan en el terminal.

Podemos repetir este proceso con 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.

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 la próxima vez que arranques Sail se cree de nuevo la base de datos. Luego 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.