How to Install Laravel with Docker: A Practical Guide to Laravel Sail

by

You want to start a Laravel project. Before writing your first feature, you need to set up PHP, extensions, Composer, and a database.

When you work on multiple projects, this setup becomes more complicated: each application may require different versions and configurations.

Docker helps organize these dependencies into containers. And Laravel Sail provides a simple way to work with this environment during local development.

In this article, we will create a Laravel application with MySQL and Redis, start the containers, and run everyday development commands.

What Is Laravel Sail?

Sail is a command-line interface for Laravel’s Docker development environment.

Docker runs the containers. Docker Compose defines the services and their connections. Sail makes it easier to start the application, run migrations, and install dependencies.

The configuration lives in the compose.yaml file. In older projects, you may find docker-compose.yml instead.

Sail is designed for local development. Deploying an application to production requires a configuration suited to that environment.

1. Set Up Docker

Before creating the project, you need a working Docker installation, Docker Compose, Bash, and curl.

On Linux, you can use Docker Engine with the Compose plugin. On macOS, use Docker Desktop. On Windows, use Docker Desktop with WSL2 and run the commands in your Linux distribution’s terminal.

Follow the official installation instructions for your operating system:

Check the installed versions:

docker --version
docker compose version

Then verify that your terminal can access Docker:

docker info

If you get a connection error, check that Docker is running. If you get a permission error, configure access according to the documentation for your installation.

With this project creation workflow, you do not need PHP or Composer installed on your computer: the initial setup uses Docker.

2. Create the Laravel Project

Navigate to the directory where you keep your projects and run:

curl -sS "https://laravel.build/my-project?with=mysql,redis" | bash

This command downloads and executes Laravel’s project creation script. Use the official domain shown above.

The name my-project becomes the name of the new directory. The with=mysql,redis parameter selects the services used in this example.

The initial installation may take a few minutes, depending on your connection and the images Docker needs to download.

Once it finishes, run:

cd my-project

You will have the application code, its dependencies, and the Sail configuration.

3. Start the Containers

From the project’s root directory, run:

./vendor/bin/sail up -d

The -d option keeps the containers running in the background.

On the first run, Docker may need to build the application image. Wait for this process to finish.

Check the status of the services:

./vendor/bin/sail ps

Then open http://localhost in your browser.

If the application shows a database error, wait for MySQL to finish initializing and continue with the next step.

4. Check the Database Configuration and Run Migrations

The installer configures the connection to your selected services. Check the DB_* variables in the .env file.

For MySQL in this example, the application should use:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306

Keep the database name, username, and password generated by the installer.

Why use mysql instead of localhost?

Inside the application container, localhost points to that container itself. The name mysql identifies the database service on the Docker Compose network.

Now run:

./vendor/bin/sail artisan migrate

Migrations create the tables defined by the application. If they have already run, Laravel will report that there are no pending migrations.

5. Run Commands Inside the Docker Environment

With Sail, you use the tools installed inside the container:

TaskCommand
Run Artisan./vendor/bin/sail artisan about
Install PHP dependencies./vendor/bin/sail composer install
Install JavaScript dependencies./vendor/bin/sail npm install
Run tests./vendor/bin/sail artisan test

To develop the frontend with Vite, run:

./vendor/bin/sail npm install
./vendor/bin/sail npm run dev

Keep the second command running in a terminal while you work. Access the application through its Laravel URL; Vite serves the assets and updates the frontend during development.

To generate compiled assets, run:

./vendor/bin/sail npm run build

6. Simplify Commands with an Alias

To save some typing, create an alias in your terminal:

alias sail='./vendor/bin/sail'

Now, from the project’s root directory, you can run:

sail artisan migrate
sail composer install
sail npm run dev

This alias applies to your current terminal session. To make it available in new terminals, add it to your shell configuration file, such as ~/.bashrc or ~/.zshrc.

7. Resolve Port Conflicts

If another service is using port 80, configure a different port in .env:

APP_PORT=8080
APP_URL=http://localhost:8080

Recreate the containers to apply the change:

./vendor/bin/sail down
./vendor/bin/sail up -d

Then visit http://localhost:8080.

If port 3306 on your computer is already in use, set:

FORWARD_DB_PORT=3307

Recreate the containers again.

Keep DB_PORT=3306. The application still connects to MySQL through the container’s internal port. Port 3307 is used by tools running on your computer, such as a database client.

8. Read the Logs and Stop the Environment

When something goes wrong, start with the logs:

./vendor/bin/sail logs -f

To follow only the application’s logs, run:

./vendor/bin/sail logs -f laravel.test

Press Ctrl+C to stop following the logs.

To stop the containers, run:

./vendor/bin/sail stop

To remove the containers and the project’s network, run:

./vendor/bin/sail down

The database’s named volumes remain intact. Avoid adding -v unless you intend to delete the data: that option also removes those volumes.

An Environment Ready for Building and Learning

Laravel Sail helps you start a project and keep your development tools inside an environment defined by Docker.

This makes it easier to share the configuration with other developers and work on projects with different dependencies.

It also gives you a foundation for experimenting with queues, integrations, and failure scenarios. Getting containers running is the first step; building a reliable application requires deciding how it should behave when a service becomes slow, unavailable, or returns an unexpected response.

Now choose a small feature, implement it, and run your first tests inside this environment.

References:

Editorial note: this tutorial uses the laravel.build creation workflow, documented in earlier Laravel versions. It does not pin a framework version. Check the generated version with

./vendor/bin/sail artisan --version.

Leave a Comment