Setting up a local development environment with Laravel is now a matter of minutes thanks to Sail. We see how to build a project from scratch and some essential commands.
Before, depending on our operating system, setting up a local development environment meant making certain decisions.
If we were using Mac we could use Valet and in a matter of minutes have a more or less functional development environment, but Valet did not work on Windows or Linux.
The other option was to use Homestead, which is not quick to assemble, or docker containers that we had to create one by one to meet our needs and prepare our development environment.
Now, with Laravel Sail, all of this has changed, and we can have a working development environment, whatever our operating system, with just one command.
The only thing we need before we start, is to install Docker Desktop on our machine and, in case of Windows, use Windows Subsystem for Linux 2 (WSL2).
Then, from the terminal and in the directory where we want to download Laravel, we execute the following command naming the project.
# You can replace example-app with your app name curl -s "https://laravel.build/example-app" | bash
This will download everything you need to set up our local development environment and start working with Laravel. At the end of the process, it will ask you for the
sudo password to be able to configure the permissions of certain folders within the project.
As soon as the command finish, if we see the output, it tells us to enter to the directory and run the containers with:
cd example-app && ./vendor/bin/sail up
With this, the development environment is up and running. By default, we will have:
- A container for the application itself with PHP 8 named with
- Another for the database in MySQL although, there is an option to use Postgres.
- A Redis container for the cache.
- And finally, Selenium to run the Laravel Dusk browser tests in case we need it.
Keep in mind that, since our project is now inside a Docker container, we have to execute all commands inside this container, which is where the expected PHP version is located among other things. It may seem complicated, but it’s not.
The first thing we have to do, although it is optional, is to configure an alias to run, more quickly, the Sail executable.
What we will do is add, in the file
.bashrc the following:
alias sail='bash vendor/bin/sail'
Once the alias is configured we can work with sail simply using
sail, from the terminal, instead of
To start the server we simply have to run
sail up to see the output log in the foreground, or
sail up -d to run it in the background in “daemon” mode.
When we want to stop the containers we will only have to write
sail down. As you can see, they are exactly the same commands that we use with Docker. In fact, if you write you will simply
sail be pitching
docker ps. It’s a simple way to work on a day-to-day basis and to get away from Docker a bit.
When executing any command we are interested in doing it inside the container and for this, we must work with
sail instead of using it directly
php artisan as we usually do.
# Run migration locally php artisan migrate # Run migrations with Laravel Sail sail artisan migrate
The same happens with PHP, Composer and Node / NPM
# Install Dusk, with Laravel Sail sail composer require --dev laravel/dusk # Print Laravel Sail PHP version sail php --version # Compile production assets with NPM in Laravel Sail sail npm run prod
As you can see, it is usually prepared to work with any of these components as we usually do, with the only difference that we must add
sail at the beginning.
With Sail, we can run the PHPUnit unit tests without any problem from the first second. We will simply do:
sail test # Same as sail artisan test
Running the navigation tests takes more configuration than the unit tests. In this case we need a Selenium container and the necessary Chrome drivers.
To achieve this we only have to uncomment the following block of the file docker-compose.yml:
selenium: image: 'selenium/standalone-chrome' volumes: - '/dev/shm:/dev/shm' networks: - sail
And add the Selenium dependency in the container
depends_on: - mysql - redis - selenium
With this, and obviously installing the library
laravel/dusk, we will be able to launch the tests with
In this case, although it may seem the same, the command
sail artisan dusk is not equivalent and would fail to execute.
Finally, you have to know that you can configure the containers as you want by publishing the configuration files.
sail artisan sail:publish
Remember that every change you make you will have to rebuild the containers with
sail build --no-cache