Laravel Sail is a lightweight command-line interface (CLI) that makes getting up and running with Laravel easy.
Based around Docker, Laravel Sail provides useful commands to start, stop, and ‘SSH-in’ to a virtual, isolated development environment, consisting of containers.
With Sail, PHP, Node, MySQL and Redis do not have to be installed locally on your machine; Sail bundles these services together and allows you to interact with them from the command line – very useful as it means that your machine’s core configuration does not have to be modified.
Don’t worry if you have no prior experience with Docker; Sail abstracts much of the complexity of setting up a Docker environment and the basic configuration is more than enough to get started in most cases. However, if you wish to dig deeper and extend Sail at any point, for example by adding your own container images, it’s not too difficult to do so.
For this post, we’ll start with the basics to help you get started using Laravel Sail with a new project.
Laravel Sail: Key Concepts
- Laravel Sail is built on top of Docker. Docker simplifies local development by allowing you to run a web application in a virtual, isolated area, with services packaged as containers (PHP, MySQL etc.).
- Laravel Sail is a command-line interface (CLI). Its commands are intended to be run using a terminal client such as iTerm2.
- Using Sail, you can get up and running with a local Laravel development environment quickly.
Laravel Sail: Getting Started
Laravel Sail is included by default with installations of Laravel 8. For this guide, we will create a fresh Laravel 8 project, set up our environment for Sail and get our project up and running on localhost using Sail’s terminal commands.
First off, let’s make sure we’ve got everything in place that Laravel Sail needs. Follow along instructions for your operating system below.
- For macOS: Make sure that Docker Desktop is installed. From your preferred terminal client, run the command curl -s “https://laravel.build/sail-example-project” | bash to create a new project named sail-example-project.
- For Windows: Make sure that Docker Desktop is installed. Additionally, make sure Windows Subsystem for Linux 2 (WSL2) is installed and enabled, and configure Docker Desktop to use the WSL2 backend [WSL2 backend instructions]. Run a Windows Terminal session for WSL2 Linux and run the command curl -s “https://laravel.build/sail-example-project” | bash to create a new project named sail-example-project.
- For Linux: Make sure that Docker is installed. From your preferred terminal client, run the command curl -s “https://laravel.build/sail-example-project” | bash to create a new project named sail-example-project.
Once you’ve created a new project, it’s time to use Sail to serve it on localhost. You can simply change directory into your new project and run the ./vendor/bin/sail up command to build your containers and make your project accessible locally, as follows:
cd sail-example-project && ./vendor/bin/sail up
Viewing your Project on localhost
After running ./vendor/bin/sail up, head over to http://localhost to see your project!
Laravel Sail: Creating an Alias
Sail provides a range of commands which can be forwarded on to various services inside your containerised development environment. For example, instead of php artisan tinker, you can run ./vendor/bin/sail artisan tinker.
It quickly gets tedious to keep writing ./vendor/bin/sail so at this point we would recommend setting up an alias so that Sail commands are accessible by just sail, for instance, sail artisan tinker.
If you’re on macOS, you can create an alias by placing the following in your ~/.bash_profile file:
alias sail='bash vendor/bin/sail'
Depending on the terminal you are using, you might need to update a different file, for example ~/.zshrc for zsh.
Restart your terminal after adding the alias.
Laravel Sail: Running Commands
As mentioned previously, Sail provides equivalent commands for PHP and other services. One approach is to interact with services from outside their containers using sail commands. Alternatively, you can essentially ‘SSH in’ to the development environment using the special sail shell command, and then run commands against PHP, Node etc. directly, as normal. You can, for instance, call sail shell and then php artisan tinker. We prefer this approach.
Starting, Stopping, ‘SSH-ing in’
Here are three commands which you’ll be using frequently:
- sail up – starts containers, serves application on http://localhost
- sail down – stops serving the application, powers down containers
- sail shell – starts a Bash session inside the virtual environment, allows you to run commands against services directly
Additionally, you can press CTRL+C to power down if sail up is running.
Laravel Sail: For Existing Projects
So far, we’ve used Laravel Sail with a new project called sail-example-project. Sail is not limited to just new projects, however; if you have an existing project you can take advantage of Sail’s features too. You just need to make sure composer is installed on your machine in order to pull in the laravel/sail package. If composer is installed, you can run the following in your project’s root directory:
composer require laravel/sail --dev
Next, you need to run an Artisan command to publish Sail’s Docker configuration file (docker-compose.yml) to the root directory of your project. Run the following in your terminal:
Then you can run the ./vendor/bin/sail up command normally to build your application’s containers and set up your project on localhost.
Laravel Sail: Extending Sail
Extending Laravel Sail is beyond the scope of this article, but it is worthwhile noting that since Sail is essentially a wrapper over Docker you can extend it with custom images, port configurations and more.
We hope that this article has been helpful in explaining how to get started with Laravel Sail, in particular how to use the sail up, sail down and sail shell commands to interact with Sail’s Docker environment, and serve your application on localhost.
- The first call to sail up may be slow as the containers are built for the first time. Subsequent calls will be a lot faster.