Laravel Sail is a light-weight command-line interface for interacting with Laravel's default Docker development environment. Sail provides a great starting point for building a Laravel application using PHP, MySQL, and Redis without requiring prior Docker experience.
At its heart, Sail is the docker-compose.yml
file and the sail
script that is stored at the root of your project. The sail
script provides a CLI with convenient methods for interacting with the Docker containers defined by the docker-compose.yml
file.
Laravel Sail is supported on macOS, Linux, and Windows (via WSL2).
Install Docker Desktop
https://docs.docker.com/desktop/install/windows-install/
After the installation is complete go to your windows user directory (C:\Users\YOURUSER) and create a file named .wslconfig
with the following content:
[wsl2]
memory=2GB # Limits VM memory in WSL 2
processors=4 # Makes the WSL 2 VM use 4 virtual processors
localhostForwarding=true # Boolean specifying if ports bound to wildcard or localhost in the WSL 2 VM should be connectable from the host via localhost:port.
swap=8GB
You will need to restart your computer after this step.
WSL2 Configuration
Install Ubuntu distribution and set it as default using Windows PowerShell.
# Check list of available distributions
wsl --list --verbose
wsl --set-default-version 2
# Install Ubuntu-20.04 distribution
# Don't forget to add a user with password on this step
wsl --install -d "Ubuntu-20.04"
# Set distribution as default
wsl -s Ubuntu-20.04
# Start distribution
wsl -d Ubuntu-20.04
Then run wsl --list --verbose
at the end and the Ubuntu distribution should look like this:
Now make sure Docker Desktop settings look like this:
Install PHP in Ubuntu 20.04 distribution.
In Windows Power Shell run the command wsl
to start a new Ubuntu session. Once inside the Ubuntu terminal run:
sudo apt update
sudo add-apt-repository -y ppa:ondrej/php
sudo apt install -y php8.1-common php8.1-cli
sudo apt install -y php8.1-curl php8.1-gd php8.1-mbstring php8.1-xml php8.1-zip
php --version
Composer 2 should also be installed. Check version by running composer -V
. If it is not installed follow this installation guide: https://www.digitalocean.com/community/tutorials/how-to-install-composer-on-ubuntu-20-04-quickstart
Conclusion
Now you should be able to run a laravel project with sail.
Adding Sail to a Project
Move to the project root directory and run:
composer require laravel/sail --dev
php artisan sail:install
# Start docker container
./vendor/bin/sail up
Running the container in a project with Sail already initialized (Existing docker-compose.yml):
# Start docker container
./vendor/bin/sail up
Sometimes container start might fail and its related to permissions issues so be mindful of where to place your project files and give them the proper permissions. (or run it with sudo prefix)
📋 Related articles
Laravel Sail installation guide
https://laravel.com/docs/9.x/installation#getting-started-on-windows
Laravel Sail usage guide
Top comments (0)