May 28, 2024 by Thibault Debatty | 833 views
Running an complete Laravel development environment requires multiple services: web server, database server, queue worker etc. Laravel Sail helps you install and use all these using docker containers. Here is how to use it...
To run the examples below, you will need:
To illustrate how Sail works, we will start with an existing laravel project:
composer create-project laravel/laravel sail-app
cd sail-app
Sail actually consists of 4 components:
Dockerfile
)of at https://github.com/laravel/sail/tree/1.x/runtimesdocker-compose.yml
fileIf you inspect the Sail Dockerfile
, you will find that the image packs together a lot of tools, including:
However, Apache or nginx are not installed, and the Sail image uses php artisan serve --host=0.0.0.0 --port=80
to run a webserver.
As mentioned above, Sail is also a composer package, so you can install Sail with
composer require laravel/sail --dev
The next step is to create the docker-compose.yml
file with:
php artisan sail:install
This shows a menu that allows to select the desired database.
Then the Sail command creates a docker-compose.yml
that will look like this:
services:
laravel.test:
build:
context: ./vendor/laravel/sail/runtimes/8.3
dockerfile: Dockerfile
args:
WWWGROUP: '${WWWGROUP}'
image: sail-8.3/app
extra_hosts:
- 'host.docker.internal:host-gateway'
ports:
- '${APP_PORT:-80}:80'
- '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
environment:
WWWUSER: '${WWWUSER}'
LARAVEL_SAIL: 1
XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
IGNITION_LOCAL_SITES_PATH: '${PWD}'
volumes:
- '.:/var/www/html'
networks:
- sail
depends_on:
- mysql
mysql:
image: 'mysql/mysql-server:8.0'
ports:
- '${FORWARD_DB_PORT:-3306}:3306'
...
Finally, Sail automatically executes docker compose build
to build the desired containers (using the aforementioned Dockerfile
).
As mentioned above, you can use the Sail script to start (and stop) containers:
./vendor/bin/sail up
# or start in background with:
./vendor/bin/sail up -d
After a few seconds, your Laravel app will be available at http://localhost
You can also stop the docker containers with:
./vendor/bin/sail down
The Sail script also allows to manage containers. Here are a few (most common) examples:
You can run database migrations, or any other artisan command, with
./vendor/bin/sail artisan migrate
You can run composer commands with
./vendor/bin/sail composer <command>
for example:
sail composer require laravel/sanctum
You can run your tests inside the Sail docker container with:
./vendor/bin/sail test
which is actually a shortcut for:
./vendor/bin/sail artisan test
The Sail command also allows to add services to your docker-compose.yml
:
php artisan sail:add
The list is pretty long and includes
Sail currently supports PHP 8.3, 8.2, 8.1, or PHP 8.0. The default is PHP 8.3. To change the PHP version that is used to serve your application, you must modify docker-compose.yml
:
# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3
# PHP 8.2
context: ./vendor/laravel/sail/runtimes/8.2
# PHP 8.1
context: ./vendor/laravel/sail/runtimes/8.1
# PHP 8.0
context: ./vendor/laravel/sail/runtimes/8.0
And don't forget to
./vendor/bin/sail build --no-cache
./vendor/bin/sail up
You can find other Sail commands and possibilities on the official documentation: https://laravel.com/docs/11.x/sail
This blog post is licensed under CC BY-SA 4.0