> Manuales > Manual de Laravel

Cómo instalar y usar Laravel Sail, para desarrollar aplicaciones Laravel con Docker, en Windows, Mac y Linux. Guía completa de Sail.

Guía de Laravel Sail

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.

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.

Sail no es más que una de las muchas alternativas que tienes para trabajar con Laravel para el desarrollo de proyectos en local. Otras alternativas muy interesantes las hemos visto en el Manual de Laravel, como por ejemplo Homestead o Valet.

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.

Importante: Si estás en Windows al instalar Docker Desktop encontrarás una casilla para marcar, que permite agregar todos los componentes para WSL2. Asegúrate de tenerla marcada durante el proceso de instalación.

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.

Si tenías Docker Desktop en Windows y por lo que sea no consigues respuesta al comando anterior desde el Linux con WSL2 tienes una configuración que realizar extra. Dentro de Docker Desktop, en la rueda dentada para la configuración, entramos en "Resources / WSL Integration" y marcamos que esté habilitada la integración y las distros donde la deseamos integrar.

Configuración extra de docker desktop para usuarios windows y wsl2

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

En el comando anterior "nueva-aplicacion-laravel" lo tendrás que sustituir por el nombre del proyecto que quieras generar.

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

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.

Seleccionar los servicios de Sail que quieres instalar

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.

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.

Ten en cuenta que si estás aplicando Sail sobre un proyecto existente es posible que tengas que restaurar bases de datos en el servidor de MySQL / Mariadb / PostgreSQL. Más abajo te explicamos algunos comandos Sail que puedes necesitar para realizar esta tarea.

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:

Ver los contenedores en marcha en Docker Desktop

Desde esta misma aplicación, Docker Desktop podrías gestionar los contenedores, aunque realmente no hace falta porque tienes los propios comandos de Sail.

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
La creación de alias puede cambiar dependiendo del sistema operativo. Generalmente se tiene que crear en el archivo .bashrc en Linux y en los MacOs a partir de Catalina, que tienen un terminal basado en zsh, lo tienes que crear en el archivo .zshrc. Puedes encontrar más información en la faq Cómo crear un alias de un comando en Linux.

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

Acuérdate que podrás ejecutar "sail down" si has creado convenientemente el alias "sail" en tu sistema.

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

Miguel Angel Alvarez

Fundador de DesarrolloWeb.com y la plataforma de formación online EscuelaIT. Com...

Manual