Configure Laravel Sail in any Laravel project

▶

We already know how to configure MySQL in our Laravel project, let's continue talking about the Laravel ecosystem.

Unlike other frameworks that require the developer to manually create Dockerfiles and docker-compose.yml, Laravel is disruptive: it provides a tool called Sail that is responsible for creating and managing the entire Docker environment for us.

What is Laravel Sail? 

Laravel Sail is a lightweight command-line interface for interacting with the Docker environment, which is now the default environment for developing in Laravel. Sail provides an excellent starting point for building a Laravel application with PHP, MySQL, and Redis, and best of all, you don't need previous Docker experience.

Essentially, Sail is the docker-compose.yml file and the sailing script that is stored at the root of your project. The sailing script provides a CLI with convenient methods to interact with the Docker containers defined by the docker-compose.yml file.

Sail is the latest Laravel development environment that emerged from Laravel in version 8, and comes to be on par with other official solutions such as Homestead for Windows and Valet for MacOS and community efforts such as Laragon (particularly the one I use), Laradock, and Vessel.

Laravel Sail is based on Docker, a technology that leverages containers to package applications so they can be run quickly and easily on any operating system.

The future of Sail seems bright, as the Laravel documentation already presents it as the preferred way to install and run Laravel projects locally, a place that Homestead and Valet occupied for years.

Laravel Sail is compatible with macOS, Linux, and Windows (via WSL2).

We can use Laravel Sail for any Laravel project; for this, we are going to follow the official documentation where we have the steps.

Laravel Sail is a lightweight command-line interface for interacting with Laravel's default Docker development environment. Sail provides an excellent starting point for building a Laravel application using PHP, MySQL, and Redis without requiring prior Docker experience.

Any recent Laravel project can use Sail

The first thing we need is to have the Laravel project. In my case, to put you in context, I have a project on Windows, which I work with Laragon (nothing of Sail) and on a Mac with Laravel Sail; they are the same projects but running in different environments.

Laravel Sail, a lightweight CLI for interacting with Laravel's default Docker environment, recently released a new update that allows you to choose which services should be configured in your project's docker-compose.yml file. Some of the options include MySQL, PostgresSQL, Redis, Memcached, Meilisearch, Selenium, and Mailhog.

A new parameter in the installer command determines which services Laravel Sail should include. For example:

$ curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

If you do not pass the with option, Sail will configure the default stack of MySQL, Redis, Meilisearch, Mailhog, and Selenium, and this new setting gives you more detailed control.

Install Docker

Although we are not going to interact much with Docker, this is a fundamental dependency to be able to work with Sail; you download it from the official website and install it. In the case of Windows, you must have aspects such as virtualization, the Linux subsystem, among others, enabled. You can get more information from the official Docker website. Also, we have a Docker Course for Developers.

️ 1. Laravel Sail Installation Installation of Sail in existing applications

To install it, the typical process: we install Sail as a normal package in Laravel. If you are interested in using Sail with an existing Laravel application, you can simply install Sail using the Composer package manager. Of course, these steps assume that your existing local development environment allows you to install Composer dependencies:

$ composer require laravel/sail --dev

It is a development dependency, hence the --dev

⚙️ 2. Sail Initialization: Install Sail in the project

For now, we have the dependency in our project, but we have an Artisan command to make the necessary modifications to our project:

$ php artisan sail:install

When executing this command:

• Sail asks for the database: Unlike other frameworks, Sail usually requires a "real" database (like MySQL) since SQLite works internally and it makes no sense to run it in an isolated container.
• Sail downloads images: You will start to see the Docker traces, such as the downloading of the Ubuntu image and the environment configuration.

3. Bringing up and Using the Project

For Sail to create the Docker configuration files (mainly the docker-compose.yml), we must execute the sail:install command.

We have EVERYTHING ready, so the next thing we do is start Sail with the command:

./vendor/bin/sail up   

• When executing sail up, Docker creates and starts the Laravel application container and the MySQL container.
• You can verify in Docker that the image and the containers are active.

You can check your .env and you will see that Sail already creates a default user for you in the database you selected:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=test
DB_USERNAME=sail
DB_PASSWORD=password

In your Docker you can see that the project is running:

Command Execution (Migrations)

Once the project is running (e.g., at http://laravel.test or similar), it will most likely fail, indicating that the database is not available or the tables do not exist.

To run migrations (or any Artisan command) inside the container, we replace php artisan with sail artisan:

$ ./vendor/bin/sail artisan migrate

Why sail artisan? The sail command communicates with the application container, running the Artisan command within that isolated environment. If we used php artisan directly, we would use the PHP interpreter installed locally on the machine.

After the migration, the application should load correctly in the browser, demonstrating that it is being served by the Docker environment managed by Sail.

Stopping the Environment

To stop the application and containers, simply run:

$ sail down

Or Control/Command + C in the terminal

Extra: Run in detached mode

If you want to run your project in detached mode, or what is the same, so that the terminal process does not keep running, but runs in the background, you pass the -d option:

$ ./vendor/bin/sail up -d

Extra:

If you see an error like the following when trying to start Sail:

ERROR: 
        Can't find a suitable configuration file in this directory or any
        parent. Are you in the right directory?
        Supported filenames: docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml

It means that you did NOT install it in your project:

$ php artisan sail:install

And follow the steps indicated above.

Basic Commands in Sail

Regarding command execution, you can use both PHP and Artisan commands, and of course, those provided by Sail thanks to the package we installed previously via docker-compose.

It is important to note that for programs that are part of Docker, such as MySQL or Redis or any other database, you must use the sail commands instead of basic Artisan; for example, instead of php artisan migrate, execute sail artisan migrate.

Basic docker-compose commands:

• docker-compose ps | sail ps: view running containers.
• docker-compose down | sail down: View the containers and remove them.
• docker-compose up | sail up: Run the containers.
• docker-compose up -d | sail up -d: Run the containers in background mode.

About Laravel Sail

Laravel Sail is a package that is installed via composer that offers a command-line interface; Sail is another of the environments we have at our disposal to be able to bring up or serve a Laravel project; it uses Docker to run the application but offers an abstraction to the Docker configuration processes that we would have to do manually if we want to use this tool as a development environment in Laravel, therefore, Sail does the entire configuration process for us.

Sail allows you to configure the entire project without needing practically anything installed at the operating system level, except Docker and perhaps PHP; everything else, that is, the server, database, and other dependencies, is installed in Docker. To use Sail, you can do it without problems on Linux or Mac; in the case of Windows, you must activate and configure the Linux subsystem.

Sail is one of my favorite services and I use it on MacOS to develop my projects, as well as the projects for my books and courses that I develop on that operating system. It is very lightweight and easy to use, it does not offer problems in general, and the only thing you should keep in mind is to turn off any process you have on the ports occupied by Sail when starting the service, which would be port 80 for the server or 3306. You can also change these ports for each Laravel project with Sail or simply turn off other services you have installed at the operating system level.