Get started with Laravel Sail

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...

Prerequisites

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

Sail actually consists of 4 components:

• a custom Docker image, which you can find the source (Dockerfile)of at https://github.com/laravel/sail/tree/1.x/runtimes
• a docker-compose.yml file
• a helper bash script to run and manage the docker containers, that you can find at https://github.com/laravel/sail/blob/1.x/bin/sail
• a composer package, which allows to easily integrate Sail into an existing Laravel project

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=0.0.0.0 --port=80 to run a webserver.

Installation

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).

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

Composer

You can run composer commands with

./vendor/bin/sail composer <command>

for example:

sail composer require laravel/sanctum

Tests

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: https://laravel.com/docs/11.x/sail

This blog post is licensed under CC BY-SA 4.0