Laravel Sail, dockeriza tu entorno de desarrollo Laravel

Laravel Sail es una interfaz de línea de comandos sencilla para interactuar con el entorno de desarrollo Docker predeterminado de Laravel. Laravel Sail proporciona un excelente punto de partida para crear aplicaciones Laravel con PHP, MySQL y Redis sin necesidad de tener experiencia previa en Docker.

Si no tienes conocimientos de Docker no te pierdas este curso.

Laravel Sail es compatible con Linux, Mac y Windows, pero en el caso de Windows vía WSL2 (Windows Subsystem for Linux). El proceso para hacer funcionar Laravel Sail en Windows no es complejo, pero dependiendo del entorno puede ser bastante pesado.

Si no sabes como instalar y configurar WSL2 en Windows para utilizar Laravel Sail, no te pierdas este curso.

¿Por qué utilizar Laravel Sail?

Si trabajas en entornos Linux o Mac no tendrás demasiados problemas para configurar tus entornos, hoy en día es una tarea bastante sencilla. En cambio, si te encuentras en Windows, instalar y configurar herramientas como Redis o Memcached puede resultar más complejo.

Independientemente del entorno en el que nos encontremos, Laravel Sail nos puede facilitar la vida enormemente para configurar entornos de desarrollo complejos sin configuraciones por nuestra parte. Para que te hagas una idea, los siguientes son los servicios que podemos utilizar en Laravel Sail con 0 configuraciones.

• mysql

• pgsql

• mariadb

• redis

• memcached

• meilisearch

• minio

• selenium

• mailhog

¿Por qué Laravel Sail es la herramienta perfecta para desarrollo?

Laravel Sail revoluciona el desarrollo local en Laravel al resolver uno de los mayores desafíos en el desarrollo web moderno: la consistencia del entorno de desarrollo. Aquí te explicamos por qué se ha convertido en una herramienta indispensable:

Desarrollo sin fricción

• Entorno uniforme garantizado: Todos los desarrolladores del equipo trabajan exactamente con las mismas versiones de PHP, MySQL, Redis y demás servicios, eliminando el clásico "en mi máquina funciona".

• Zero-configuration: Sail viene preconfigurado con las mejores prácticas para desarrollo Laravel. No necesitas ser un experto en Docker para tener un entorno profesional funcionando en minutos.

Flexibilidad y modernidad

• Cambios sin compromiso: ¿Necesitas probar tu aplicación con PHP 8.4? ¿Quieres cambiar de MySQL a PostgreSQL? Con Sail, estos cambios son cuestión de modificar una línea en tu configuración.

• Stack moderno incluido: Sail integra Vite para HMR (Hot Module Replacement) y otras herramientas modernas. Para WSL2, es necesaria una configuración específica en el archivo vite.config.js:

  export default defineConfig({
      // ...
      server: { 
          hmr: {
              host: 'localhost',
          },
      }, 
  });

Desarrollo local profesional

• Servicios enterprise en local: Puedes trabajar con servicios como Redis, Memcached o Meilisearch en local exactamente igual que en producción, sin comprometer el rendimiento de tu máquina.

• Aislamiento perfecto: Cada proyecto está completamente aislado. Puedes tener múltiples proyectos usando diferentes versiones de PHP o MySQL sin conflictos.

Productividad mejorada

• CLI simplificada: Olvídate de recordar comandos Docker complejos. sail artisan migrate o sail test son todo lo que necesitas.

• Testing realista: Al usar el mismo entorno que producción, los tests son más fiables y representativos.

Ideal para equipos

• Onboarding rápido: Nuevos desarrolladores pueden unirse al proyecto y tener el entorno completo funcionando en minutos, no horas.

• Documentación viva: El archivo docker-compose.yml actúa como documentación viva de las dependencias y servicios necesarios para tu aplicación.

Desarrollo multiplataforma sin dolor

• Consistencia cross-platform: Ya sea en Windows (vía WSL2), macOS o Linux, la experiencia de desarrollo es idéntica.

• Performance optimizada: Sail está optimizado para ofrecer el mejor rendimiento posible en desarrollo local, con configuraciones específicas para cada sistema operativo.

Requisitos específicos por sistema operativo:

macOS:

• Docker Desktop para Mac: Asegúrate de tener Docker Desktop instalado y actualizado. Esto también incluye Docker Compose, que es necesario para ejecutar los servicios de Docker.

Linux:

• Docker Compose: Instala Docker Compose utilizando los comandos apt, yum, dnf, o cualquier otro gestor de paquetes disponible en tu distribución de Linux.

• Docker Desktop: Si utilizas Docker Desktop para Linux, debes ejecutar el siguiente comando. Si no utilizas Docker Desktop para Linux, puede omitir este paso.

• docker context use default

Windows:

• Docker Desktop para Windows: Asegúrate de instalar Docker Desktop y activar el soporte de WSL 2 (Windows Subsystem for Linux), ya que Sail requiere un entorno Unix para funcionar correctamente.

• WSL2: Es recomendable instalar una distribución de Linux (como Ubuntu) a través de WSL 2 para ejecutar los comandos de Sail. Docker Desktop en Windows utiliza WSL2 para proporcionar un entorno de Docker nativo. Si tienes dudas sobre WSL2, no te pierdas nuestro curso.

Crear un proyecto con Laravel Sail

La forma más sencilla de crear un proyecto con Laravel Sail es utilizar el siguiente comando en cualquiera de sus versiones.

# por defecto se instalarán mysql, redis, meilisearch, mailhog, and selenium
curl -s https://laravel.build/laravel-sail-app | bash

# se instalarán mysql y redis únicamente
curl -s "https://laravel.build/laravel-sail-app?with=mysql,redis" | bash

Instalar Laravel Sail en un proyecto existente

También es posible instalar Laravel Sail en un proyecto existente, para ello, simplemente ejecuta los siguientes comandos en tu proyecto Laravel.

composer require laravel/sail --dev
php artisan sail:install

Arrancar un proyecto Laravel con Laravel Sail

En cualquiera de los casos de cómo haya sido creado el proyecto, arrancarlo es muy sencillo. Primero, debemos arrancar Docker, a continuación, debemos ejecutar el comando sail up. El problema es que el comando sail no existe en nuestro entorno, ya que sail está ubicado en nuestro proyecto vendor/bin/sail. Mi recomendación y la de Laravel es crear un alias de la siguiente forma.

# SAIL ALIAS
alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'

Si somos capaces de crear un alias, podremos ejecutar el siguiente comando para arrancar nuestro proyecto.

sail up

En caso contrario deberemos ejecutar lo siguiente.

./vendor/bin/sail up

Sea cual sea el caso, tenemos un flag en el comando sail up que nos permite dejar el terminal libre haciendo un detach del proceso, es decir, lo dejamos corriendo, pero sin ocupar el terminal, yo es lo que hago siempre:

sail up -d

Ejecutar comandos en un proyecto Laravel Sail

En este punto debemos entender que Docker crea entornos aislados de nuestra computadora, por este motivo, las versiones de Php, MySQL o Composer que podamos tener instaladas en nuestro equipo no son las mismas que las que estaremos utilizando en nuestro proyecto con Laravel Sail.

Para ejecutar cualquier comando y que éste afecte a nuestro proyecto debemos estar en un terminal ubicados en el directorio del proyecto en cuestión y ejecutar algunos de los siguientes comandos, todos a modo de ejemplo para que te hagas a la idea.

sail
sail php --version
sail artisan
sail composer --version
sail node --version
sail npm run prod
sail yarn
sail test
sail test --group orders
sail dusk
sail tinker

A continuación, te dejo la lista de todos los comandos que tenemos disponibles con Laravel Sail:

Laravel Sail

Usage:
  sail COMMAND [options] [arguments]

Unknown commands are passed to the docker-compose binary.

docker-compose Commands:
  sail up        Start the application
  sail up -d     Start the application in the background
  sail stop      Stop the application
  sail restart   Restart the application
  sail ps        Display the status of all containers

Artisan Commands:
  sail artisan ...          Run an Artisan command
  sail artisan queue:work

PHP Commands:
  sail php ...   Run a snippet of PHP code
  sail php -v

Composer Commands:
  sail composer ...                       Run a Composer command
  sail composer require laravel/sanctum

Node Commands:
  sail node ...         Run a Node command
  sail node --version

NPM Commands:
  sail npm ...        Run a npm command
  sail npx            Run a npx command
  sail npm run prod

PNPM Commands:
  sail pnpm ...        Run a pnpm command
  sail pnpx            Run a pnpx command
  sail pnpm run prod

Yarn Commands:
  sail yarn ...        Run a Yarn command
  sail yarn run prod

Bun Commands:
  sail bun ...        Run a bun command
  sail bunx           Run a bunx command
  sail bun run prod

Database Commands:
  sail mysql     Start a MySQL CLI session within the 'mysql' container
  sail mariadb   Start a MySQL CLI session within the 'mariadb' container
  sail psql      Start a PostgreSQL CLI session within the 'pgsql' container
  sail redis     Start a Redis CLI session within the 'redis' container

Debugging:
  sail debug ...          Run an Artisan command in debug mode
  sail debug queue:work

Running Tests:
  sail test          Run the PHPUnit tests via the Artisan test command
  sail phpunit ...   Run PHPUnit
  sail pest ...      Run Pest
  sail pint ...      Run Pint
  sail dusk          Run the Dusk tests (Requires the laravel/dusk package)
  sail dusk:fails    Re-run previously failed Dusk tests (Requires the laravel/dusk package)

Container CLI:
  sail shell        Start a shell session within the application container
  sail bash         Alias for 'sail shell'
  sail root-shell   Start a root shell session within the application container
  sail root-bash    Alias for 'sail root-shell'
  sail tinker       Start a new Laravel Tinker session

Sharing:
  sail share   Share the application publicly via a temporary URL
  sail open    Open the site in your browser

Binaries:
  sail bin ...   Run Composer binary scripts from the vendor/bin directory

Customization:
  sail artisan sail:publish   Publish the Sail configuration files
  sail build --no-cache       Rebuild all of the Sail containers

Bases de datos del proyecto con Laravel Sail

Cuando creamos nuestro proyecto con Laravel Sail, por defecto, se crean dos bases de datos utilizando MySQL:

• laravel: Este es el nombre por defecto de la base de datos del proyecto, simplemente se utiliza el nombre que está definido en el .env.

• testing: Esta base de datos está pensada para el entorno de tests con Laravel, y se crea al crear un nuevo proyecto con Laravel Sail.

Acceder a MySQL con un DBMS en Laravel Sail

Si no tenemos ocupado el puerto 3306, podemos acceder igual que lo hacemos siempre sin realizar ninguna modificación en nuestro proyecto. En cambio, si tenemos el puerto 3306 ocupado, deberemos hacer uso de la variable FORWARD_DB_PORT para cambiar el puerto con el que accederemos al 3306 del contenedor de la siguiente forma:

FORWARD_DB_PORT=3307

Una vez hecho, te recomiendo reiniciar tu entorno desde el cliente de docker y acceder a tu base de datos con tu DBMS preferido utilizando las siguientes credenciales.

host: localhost
port: 3307
user: sail
passsword: password
db_name: laravel

Añadir nuevos servicios a Laravel Sail

Sail permite agregar servicios adicionales a tu entorno de desarrollo de forma sencilla. Hay dos maneras principales de hacerlo:

Usando el comando sail:install

Laravel Sail proporciona un comando específico para instalar servicios adicionales:

# Instalar un nuevo servicio
sail artisan sail:install

# Verás un menú interactivo con las siguientes opciones:
# [0] mysql
# [1] pgsql
# [2] mariadb
# [3] redis
# [4] memcached
# [5] meilisearch
# [6] minio
# [7] mailpit
# [8] selenium
# [9] soketi

Modificando docker-compose.yml manualmente

También puedes editar directamente tu archivo docker-compose.yml para añadir servicios personalizados:

# Ejemplo para agregar MongoDB
services:
    mongodb:
        image: 'mongo:latest'
        ports:
            - '${FORWARD_MONGODB_PORT:-27017}:27017'
        environment:
            MONGO_INITDB_ROOT_USERNAME: '${MONGODB_USERNAME}'
            MONGO_INITDB_ROOT_PASSWORD: '${MONGODB_PASSWORD}'
            MONGO_INITDB_DATABASE: '${MONGODB_DATABASE}'
        volumes:
            - 'sail-mongodb:/data/db'
        networks:
            - sail

Configuración de variables de entorno

Para cada nuevo servicio, necesitarás actualizar tu archivo .env:

FORWARD_MONGODB_PORT=27017
MONGODB_USERNAME=sail
MONGODB_PASSWORD=password
MONGODB_DATABASE=laravel

Servicios populares y su configuración

RabbitMQ:

rabbitmq:
    image: 'rabbitmq:3-management'
    ports:
        - '${FORWARD_RABBITMQ_PORT:-5672}:5672'
        - '${FORWARD_RABBITMQ_MANAGEMENT_PORT:-15672}:15672'
    environment:
        RABBITMQ_DEFAULT_USER: '${RABBITMQ_USER}'
        RABBITMQ_DEFAULT_PASS: '${RABBITMQ_PASSWORD}'
    networks:
        - sail

Elasticsearch:

elasticsearch:
    image: 'elasticsearch:8.11.1'
    ports:
        - '${FORWARD_ELASTICSEARCH_PORT:-9200}:9200'
    environment:
        - discovery.type=single-node
        - xpack.security.enabled=false
    networks:
        - sail

Buenas prácticas al añadir servicios

1. Versionado: Especifica siempre una versión exacta de la imagen Docker para evitar problemas de compatibilidad.

2. Persistencia: Configura volúmenes para datos que necesiten persistir:

   volumes:
       sail-mongodb:
           driver: local

3. Redes: Asegúrate de que el servicio está en la red sail:

   networks:
       - sail

4. Variables de entorno: Usa variables del .env para configuraciones sensibles:

   environment:
       - 'KEY=${ENV_VARIABLE:-default_value}'

Reinicio después de cambios

Después de añadir nuevos servicios:

# Detener los contenedores
sail down

# Reconstruir y arrancar
sail up -d --build

Compartir nuestro sitio con Laravel Sail

Muchas veces necesitamos compartir nuestro sitio por varios motivos, mostrar nuestro trabajo a nuestros clientes o simplemente para dar acceso a Webhooks en entorno de desarrollo cuando todavía no tenemos nuestro sitio publicado. Gracias a Laravel Sail este proceso se convierte en algo muy sencillo, sólo debemos ejecutar el siguiente comando dentro de nuestro proyecto y podremos exponer nuestro proyecto local a todo el mundo durante 30 minutos.

sail share

#Trying to use custom domain:
#Thank you for using expose.
#Local-URL:		host.docker.internal:80
#Dashboard-URL:		http://127.0.0.1:4040
#Expose-URL:		http://uczyq5ydxj.laravel-sail.site:8080
#Expose-URL:		https://uczyq5ydxj.laravel-sail.site

#Remaining time: 00:29:11
#+--------+--------------+----------+---------------------+----------+
#| Method | URI          | Response | Time                | Duration |
#+--------+--------------+----------+---------------------+----------+
#| GET    | /favicon.ico | 200 OK   | 2022-02-06 11:54:55 | 18ms     |
#| GET    | /            | 200 OK   | 2022-02-06 11:54:53 | 923ms    |
#Remaining time: 00:26:45

---

Es importante destacar que Laravel Sail está diseñado específicamente para desarrollo, no para producción. En producción, podrías usar las imágenes Docker base que utiliza Sail, pero con configuraciones optimizadas para producción. Sail se centra en proporcionar la mejor experiencia de desarrollo posible, permitiéndote concentrarte en escribir código en lugar de gestionar tu entorno de desarrollo.

Puedes ver que Laravel Sail es una poderosa herramienta para facilitar nuestro entorno de desarrollo con Laravel.

Si te ha gustado esta entrada, compártela con tus colegas.

Sigue aprendiendo Laravel Sail a través de ejemplos en la ruta de Laravel 11.