Cómo instalar y usar Laravel Sail, para desarrollar aplicaciones Laravel con Docker, en Windows, Mac y Linux. Guía completa de 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.
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.
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.
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
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
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.
También puedes cambiar los servicios de Sail una vez se ha creado el proyecto. El procedimiento sería similar al que se explica en la FAQ: Cómo cambiar MySQL por MariaDB en Laravel Sail.
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.
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:
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
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
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
Por supuesto, necesitas Docker Desktop instaado en tu sistema para que esto funcione correctamente.
IMPORTANTE: Este comando lo puedes personalizar con la versión de PHP que necesite tu proyecto, desde la 74, 80, 81, hasta 82 o las que puedan venir.
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
Recuerda que si no has instalado el alias de Sail como te hemos enseñado antes en este artículo, siempre tienes que lanzar el comando sail
con la ruta completa al binario:
./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.
Miguel Angel Alvarez
Fundador de DesarrolloWeb.com y la plataforma de formación online EscuelaIT. Com...