DEV Community

Daichi Izushi
Daichi Izushi

Posted on

[Laravel v11 x Docker] Efficiently Set Up a Laravel App Dev Environment with Laravel Sail

#php #laravel #docker #laravelsail

About Laravel Sail

Laravel Sail is the official development environment for the Laravel framework. Sail provides a lightweight command-line interface (CLI) to easily set up and manage a Laravel application development environment using Docker. Below, we explain the main features and usage of Laravel Sail.

Benefits of Using Laravel Sail

  1. Build a development environment independent of the OS
    • Sail uses Docker to containerize the development environment for Laravel applications. This allows you to build a development environment that is independent of the OS.
  2. Easy setup of the development environment
    • With Sail, you can set up a Laravel development environment with just a few commands. Even complex development environments using MySQL, Redis, MailHog, etc., can be easily built.
  3. Easy management of projects with different versions
    • For example, the version of Laravel depends on the version of PHP, but by setting the environment for each project in the docker-compose.yml file, you can easily switch versions.

Image description
When you create a project using Docker with Laravel Sail, the structure will look like the diagram above.

Usage

Development Environment

  • Mac
  • PHP v8.3
  • Laravel v11
  • Docker

Prerequisites

Before creating a Laravel project, download and start Docker Desktop.
https://www.docker.com/products/docker-desktop/

1. Creating a Laravel Project

Run the following command to create a new Laravel project and set up Laravel Sail.

curl -s "https://laravel.build/example-app" | bash
cd example-app
Enter fullscreen mode Exit fullscreen mode

This will create the Laravel project files. The development environment is described in the generated docker-compose.yml file.

Specify services with the with query

If you want to specify the PHP version or use PostgreSQL instead of MySQL, you can specify with=<service>,<service>,... in the command when generating the project.

curl -s "https://laravel.build/example-app?php=81&with=pgsql,redis" | bash
Enter fullscreen mode Exit fullscreen mode

2. Starting Sail

Move to the project directory and start Sail.

./vendor/bin/sail up -d
Enter fullscreen mode Exit fullscreen mode

This command starts the Docker containers and runs the Laravel application.

※Registering an alias

Typing ./vendor/bin/sail an be cumbersome, so save it as an alias sail in your shell's configuration file.

Check the path of the shell you are using with the following command

echo $SHELL
Enter fullscreen mode Exit fullscreen mode

Example: /bin/zsh

Editing the Shell configuration file

  • For zsh

The Shell configuration file is ~/.zshrc.
To add an alias, run the following command

echo "alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'" >> ~/.zshrc
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode
  • For bash

The shell configuration file is ~/.bash_profile or ~/.bashrc.
To add an alias, run the following command:

echo "alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'" >> ~/.bash_profile
source ~/.bash_profile
Enter fullscreen mode Exit fullscreen mode

With the above settings, you can run the sail command in a shortened form.

sail up -d
Enter fullscreen mode Exit fullscreen mode

3. Using Sail Commands

You can use Sail to perform various development tasks. Here are some examples.

  • Starting the application: 
sail up -d
Enter fullscreen mode Exit fullscreen mode
  • Stopping the application: 
sail down
Enter fullscreen mode Exit fullscreen mode
  • Running Artisan commands: 
sail artisan migrate
Enter fullscreen mode Exit fullscreen mode
  • Running Composer commands: 
sail composer install
Enter fullscreen mode Exit fullscreen mode
  • Running npm commands: 
sail npm install
Enter fullscreen mode Exit fullscreen mode

4. Changing Services

Even after creating the project, you can change the services by modifying the docker-compose.yml file, which is the Docker configuration file. Here, we will change the PHP version and the database used.

Changing the PHP version

First, check the current PHP version

sail php -v
PHP 8.3.12 (cli) (built: Sep 27 2024 03:53:05) (NTS)
Enter fullscreen mode Exit fullscreen mode

Next, modify the development environment information described in the docker-compose.yml file.

services:
    laravel.test:
        build:
            context: "./vendor/laravel/sail/runtimes/8.3"
            dockerfile: Dockerfile
            args:
                WWWGROUP: "${WWWGROUP}"
        image: "sail-8.3/app"
Enter fullscreen mode Exit fullscreen mode

Change build context and image to 8.1 .

services:
    laravel.test:
        build:
            context: "./vendor/laravel/sail/runtimes/8.1"
            dockerfile: Dockerfile
            args:
                WWWGROUP: "${WWWGROUP}"
        image: "sail-8.1/app"
Enter fullscreen mode Exit fullscreen mode

After modifying docker-compose.yml, stop the application.

sail down
Enter fullscreen mode Exit fullscreen mode

Next, rebuild the Docker containers to reflect the changes.

sail build --no-cache
Enter fullscreen mode Exit fullscreen mode

Restart the application.

sail up -d
Enter fullscreen mode Exit fullscreen mode

Check if the PHP version has changed.

sail php -v
PHP 8.1.30 (cli) (built: Sep 27 2024 04:07:29) (NTS)
Enter fullscreen mode Exit fullscreen mode

The PHP version has been changed from PHP 8.3 to PHP 8.1.

Changing the database used

Change a project created with MySQL to PostgreSQL.

Run the Sail installation command

sail php artisan sail:install
Enter fullscreen mode Exit fullscreen mode

Select pgsql

 ┌ Which services would you like to install? ───────────────────┐
 │   ◼ mysql                                                  ┃ │
 │ › ◻ pgsql                                                  │ │
 │   ◻ mariadb                                                │ │
 │   ◻ redis                                                  │ │
 │   ◻ memcached                                              │ │
 └────────────────────────────────────────────────── 1 selected ┘
  Use the space bar to select options.
Enter fullscreen mode Exit fullscreen mode

Check the docker-compose.yml file and confirm that the pgsql entries have been added.

services:
    laravel.test:
...
        depends_on:
            - mysql
            - redis
            - meilisearch
            - mailpit
            - selenium
            - pgsql
...
        pgsql:
            image: 'postgres:17'
            ports:
                - '${FORWARD_DB_PORT:-5432}:5432'
            environment:
                PGPASSWORD: '${DB_PASSWORD:-secret}'
                POSTGRES_DB: '${DB_DATABASE}'
                POSTGRES_USER: '${DB_USERNAME}'
                POSTGRES_PASSWORD: '${DB_PASSWORD:-secret}'
            volumes:
                - 'sail-pgsql:/var/lib/postgresql/data'
                - './vendor/laravel/sail/database/pgsql/create-testing-database.sql:/docker-entrypoint-initdb.d/10-create-testing-database.sql'
            networks:
                - sail
            healthcheck:
                test:
                    - CMD
                    - pg_isready
                    - '-q'
                    - '-d'
                    - '${DB_DATABASE}'
                    - '-U'
                    - '${DB_USERNAME}'
                retries: 3
                timeout: 5s
Enter fullscreen mode Exit fullscreen mode

ext, open the .env file in the project directory and confirm that DB_CONNECTION=pgsql and DB_HOST=pgsql are set.
If not, change them manually.

DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=******
Enter fullscreen mode Exit fullscreen mode

After confirming the changes in docker-compose.yml and .env, stop the application.

sail down
Enter fullscreen mode Exit fullscreen mode

Next, rebuild the Docker containers to reflect the changes.

sail build --no-cache
Enter fullscreen mode Exit fullscreen mode

Restart the application.

sail up -d
Enter fullscreen mode Exit fullscreen mode

Run the migration files.

sail artisan migrate

INFO  Preparing database.

Creating migration table ................................ 6.00ms DONE

INFO  Running migrations.

0001_01_01_000000_create_users_table .................... 5.74ms DONE
0001_01_01_000001_create_cache_table .................... 1.45ms DONE
0001_01_01_000002_create_jobs_table ..................... 3.44ms DONE
Enter fullscreen mode Exit fullscreen mode

Start a shell in Docker and check pgsql

Display the list of currently running Docker containers.

sail ps
Enter fullscreen mode Exit fullscreen mode 
NAME                                IMAGE                          COMMAND                  SERVICE
laravel-sail-setup-laravel.test-1   sail-8.3/app                   "start-container"        laravel.test
laravel-sail-setup-mailpit-1        axllent/mailpit:latest         "/mailpit"               mailpit
Enter fullscreen mode Exit fullscreen mode

Check the container name of the application and start the bash of the application inside Docker.

docker exec -it laravel-sail-setup-laravel.test-1 bash
Enter fullscreen mode Exit fullscreen mode

Connect to pgsql.

psql -U sail -h pgsql laravel
Enter fullscreen mode Exit fullscreen mode

You will be prompted for a password, so enter the DB_PASSWORD specified in the .env file.

Password for user sail:******
Enter fullscreen mode Exit fullscreen mode

Check the tables in pgsql

laravel=# \dt
               List of relations
 Schema |         Name          | Type  | Owner
--------+-----------------------+-------+-------
 public | cache                 | table | sail
 public | cache_locks           | table | sail
 public | failed_jobs           | table | sail
 public | job_batches           | table | sail
 public | jobs                  | table | sail
 public | migrations            | table | sail
 public | password_reset_tokens | table | sail
 public | sessions              | table | sail
 public | users                 | table | sail
(9 rows)
Enter fullscreen mode Exit fullscreen mode

In this way, you can change from MySQL to PostgreSQL even after creating the project.

Conclusion

Through this article, you will understand how to efficiently set up and manage a development environment using Laravel Sail. By selecting appropriate services and customizing the settings according to the project's requirements, you can achieve a more flexible and powerful development environment.

Top comments (0)

Read next

sertxudev profile image

Add a sidebar with options in a Filament resource

Sergio Peris -

pcmagas profile image

How I can run elasticsearch locally for development using docker?

Dimitrios Desyllas -

rimelek profile image

Comparing 3 Docker container runtimes - Runc, gVisor and Kata Containers

Ákos Takács -

zhangzhuyue profile image

Develop the management system on cloud for simple programmble controller.

zhuyue -