Laravel Sail and Docker [In-Depth Tutorial]

Are you a Laravel developer looking to streamline your local development environment? Laravel is one of the most popular PHP frameworks out there, and for good reason. It's powerful, flexible, and easy to use.

However, setting up a local development environment for Laravel applications can be a pain. You need to install and configure a web server, database, and other dependencies, and even then, things don't always work as expected. That's where Laravel Sail comes in - a lightweight CLI that makes setting up a development environment for Laravel applications a breeze.

With Laravel Sail, you can create a Docker-based development environment in just a few simple steps. Sail comes with everything you need to get started with Laravel development, including a pre-configured web server, database, and other essential tools. This means you can spend less time setting up your environment and more time building great applications.

This tutorial walks you through how Laravel Sail implements Docker, installing Docker and Laravel, managing Sail containers, and executing commands. Let's get started.

How Laravel Sail implements Docker

Laravel provides Sail. Sail is the docker-compose.yml file that defines Docker containers. The containers build your Laravel application. Each container is an entry within the services configuration. laravel.test is the primary container. MySQL and Redis database services are pre-configured.

Sail comes with the sail script that provides a CLI for interacting with the Docker containers defined by the docker-compose.yml file. The sail commands are invoked using the vendor/bin/sail script. The script comes with a new Laravel installation. You can create an alias for the script in your home directory. Open ~/.zshrc or ~/.bashrc file and write this line.

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

Now restart the shell. After that, you can manage docker containers with sail instead of vendor/bin/sail command. Let's start by installing Docker and Laravel Sail.

Install Docker

Let's install the Docker desktop on Ubuntu 22.04 (LTS). The system should be a 64-bit version of Ubuntu Jammy Jellyfish 22.04 (LTS) or Ubuntu Impish Indri 21.10. You can check the version using the following command.

cat /etc/*release*

Update your machine's package index before installing the required packages. Updating the package index allows apt to use repositories over HTTPS.

sudo apt-get update

sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg-agent \
software-properties-common

Add Docker's official GPG keys.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Now add Docker repository to the system.

echo \
 "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update package index then install Docker. Lastly verify whether the service is running.

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl status docker

Good, docker is active and running!

steve@alila:~$ sudo systemctl status docker
● docker.service - Docker Application Container Engine
   Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2023-04-21 13:10:03 EAT; 1min 0s ago
TriggeredBy: ● docker.socket
    Docs: https://docs.docker.com
  Main PID: 6830 (dockerd)
    Tasks: 9
   Memory: 24.6M
   CGroup: /system.slice/docker.service
       └─6830 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
...

Now you should be able to pull the hello-world image and run it (requires internet connection).

sudo docker run hello-world

We have prefaced the above command with the sudo command because the docker user group does not have users. You can run the docker commands without sudo by running the following commands.

# create the docker group if does not exist.
sudo groupadd docker
# add the current user to the new group then log out and back into the machine to effect the changes. Restart a virtual machine instead.
sudo usermod -aG docker $USER
# activate the changes to the new group
newgrp docker

You may run into an error on re-running the hello-world container without the sudo command: WARNING: Error loading config file: /home/user/.docker/config.json -stat /home/user/.docker/config.json: permission denied

Get rid of the error by changing the ownership and permissions of the docker file.

sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R

Alternatively, you can install docker using the convenience script.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Now that Docker is up and running, let's install Laravel Sail and use it with Docker.

Install Laravel Sail

Installation with a new application

Launch the terminal and create a new Laravel application.

curl -s https://laravel.build/test_app | sudo bash

The command installs test_app and configures the docker-compose.yml file with mysql, pgsql, mariadb, redis, memcached, meilisearch, minio, selenium, and mailpit services. You can choose the services to configure using the with query string. For example, you can configure only MySQL and Redis, as follows.

curl -s "https://laravel.build/test_app?with=mysql,redis" | sudo bash

The command creates test_app project and pulls mysql and redis services.

Installation in an existing application

composer require laravel/sail --dev
php artisan sail:install

Composer installs Laravel Sail as a dev dependency. Next, publish docker-compose.yml file to the root of the application using the sail:install command.

Using Laravel Sail Interface

Start and stop containers

Navigate to the new project and power it up using the up Sail command.

Input

cd test_app && ./vendor/bin/sail up
# OR (if you have created an alias)
cd test_app && sail up

Output

You should be able to start the application on localhost. The startup may fail with a message stating the permission to storage is denied. Run the following commands in the working directory to solve the error.

sudo chown -R $USER:www-data storage
sudo chmod -R 775 storage
sail up -d

The -d, for detached, starts the container in the background.

cd test_app && ./vendor/bin/sail up -d

Stop the container using Control + C if the container runs in the foreground or stop command if it runs in the background.

sail stop

Executing commands

Use sail, instead of php to run commands with Laravel Sail.

# Running Artisan commands locally
php artisan queue:work

# Running Artisan commands within Laravel Sail
sail artisan queue:work

Precede PHP, Node or Composer commands with sail when running them with Laravel Sail.

sail php --version
sail npm run dev
sail composer require laravel/sanctum

Sail supports PHP 7.4 onwards, with the current default being 8.2. You can change default PHP version by customizing the laravel.test container's build definition.

context: ./vendor/laravel/sail/runtimes/<php_version>
# e.g
context: ./vendor/laravel/sail/runtimes/8.0

Likewise, you can update Node's build version from the default 18.

build:
   args:
     WWWGROUP: '${WWWGROUP}'
     NODE_VERSION: '<node_version>'

After that, you should update the docker-compose.yml

sail build --no-cache

and rebuild the container images.

sail up

What if you wish to start a bash session with the application's container? Use the shell command to connect to the application's containers. Then, you can inspect files and installed services and execute arbitrary shell commands.

sail shell
sail root-shell

You can also start a new Tinker session.

sail tinker

Lastly, you can share your application.

sail share

You get a random laravel-sail.site URL to access your application. Configure your application's trusted proxies with the TrustProxies middleware in the app/Http/Middleware/TrustProxies.php file.

/**
 * The trusted proxies for this application.
 *
 * @var array|string|null
 */
protected $proxies = '*';

You can choose domain for your shared site and provide subdomain when executing the share command.

sail share --subdomain=your-sail-site

Lastly, you can migrate changes using the migrate command.

sail artisan migrate

Key Takeaway

If you're a Laravel developer looking to streamline your local development workflow, Laravel Sail is the solution you've been searching for. With Sail, you can easily create a Docker-based development environment that includes a pre-configured web server, database, and other essential tools. This means you can spend less time setting up your environment and more time building great applications.

One of the best things about Laravel Sail is its simplicity - even if you're new to Docker or server administration, you can get up and running with Sail in just a few simple steps. And if you're an experienced developer, Sail is fully customizable, so you can tailor the environment to your specific needs and preferences.