Get started with Laravel Sail

May 28, 2024 by Thibault Debatty | 241 views

Laravel PHP Docker

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:

  • PHP 8.3
  • composer
  • Docker
  • docker-compose, or the Docker compose extension

Laravel project installation

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:

If you inspect the Sail Dockerfile, you will find that the image packs together a lot of tools, including:

  • PHP
  • composer
  • npm and node.js
  • mysql-client
  • postgresql-client
  • supervisor
  • ffmpeg

However, Apache or nginx are not installed, and the Sail image uses php artisan serve --host= --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:

            context: ./vendor/laravel/sail/runtimes/8.3
            dockerfile: Dockerfile
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.3/app
            - 'host.docker.internal:host-gateway'
            - '${APP_PORT:-80}:80'
            - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
            - '.:/var/www/html'
            - sail
            - mysql
        image: 'mysql/mysql-server:8.0'
            - '${FORWARD_DB_PORT:-3306}:3306'

Finally, Sail automatically executes docker compose build to build the desired containers (using the aforementioned Dockerfile).

Start and stop containers

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

Manage containers

The Sail script also allows to manage containers. Here are a few (most common) examples:

Migrations and artisan commands

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

Add services

The Sail command also allows to add services to your docker-compose.yml:

php artisan sail:add

The list is pretty long and includes

  • redis
  • memcached
  • mailpit
  • minio


Change PHP version

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

Go further

You can find other Sail commands and possibilities on the official documentation:

This blog post is licensed under CC BY-SA 4.0

This website uses cookies. More information about the use of cookies is available in the cookies policy.