Laravel Docker Setup
Sail & Docker Compose Guide
“It works on my machine!” — Docker eliminates that excuse. This complete guide walks you through Laravel's official Docker solution (Sail) and Docker Compose, from installation to customizing services, with real-world examples and best practices.
📑 Table of Contents
1. Introduction
Docker has revolutionized development by providing lightweight, isolated containers that run consistently across any environment. Laravel embraces Docker with Laravel Sail — a built-in solution that uses Docker Compose to manage your application's services.
With Sail, you get a complete development environment with PHP, MySQL, Redis, Meilisearch, Mailhog, and more — all without installing any of these tools locally. This guide covers everything from initial setup to advanced customization, so you can harness the full power of Docker for your Laravel projects.
2. Laravel Sail
Laravel Sail is a light-weight command-line interface for interacting with Laravel's default Docker configuration. It provides a simple way to run a Laravel application using Docker without prior Docker experience.
Sail is automatically installed with new Laravel projects (since Laravel 8). It consists of:
- A
docker-compose.ymlfile defining services (app, MySQL, Redis, etc.). - A
Dockerfilefor the application container. - A
./vendor/bin/sailscript that wraps docker-compose commands.
Sail uses Docker Compose under the hood, so you can use any docker-compose command directly if you prefer.
3. Installation
There are two primary ways to get started with Laravel and Sail.
📌 Option 1: Using Laravel Installer (Recommended)
📌 Option 2: Via Composer (Existing Project)
If you already have a Laravel project, you can install Sail:
During sail:install, you can choose which services to include (MySQL, PostgreSQL,
Redis, etc.).
alias sail='./vendor/bin/sail'
to save typing.
4. Services & Configuration
Sail's default docker-compose.yml includes several services, each defined as a
separate container. Here are the most common ones:
- laravel.test — The main application container running PHP-FPM and Nginx.
- mysql — MySQL database (default port 3306).
- redis — Redis for caching and sessions.
- meilisearch — Search engine (optional).
- mailhog — Email testing tool (captures outgoing emails).
- selenium — For browser testing (optional).
You can also add PostgreSQL, MariaDB, or other services by editing the
docker-compose.yml file.
Environment variables for each service are defined in the .env file, which Sail
automatically maps to the containers.
5. Sail Commands
Sail acts as a wrapper around docker-compose, making common tasks easier.
You can also pass any docker-compose command directly:
sail docker-compose ps.
6. Customizing Docker Compose
One of Sail's greatest strengths is its flexibility. You can easily add or remove services, change PHP versions, or override configurations.
📌 Adding a New Service
To add, for example, a PostgreSQL database:
- Edit
docker-compose.ymland add a new service definition. - Update your
.envfile to use the new database connection. - Restart Sail:
sail downthensail up -d.
📌 Changing PHP Version
In the docker-compose.yml, find the laravel.test service and update the
image tag (e.g., image: sail-8.2/app to sail-8.3/app). You may need to rebuild:
📌 Overriding Environment Variables
You can set environment-specific values in a .env.sail file or directly in
.env.
docker-compose.yml,
always run sail down and sail up -d to apply them.
7. Common Issues & Fixes
- Port conflict: If port 80 or 3306 is already in use, change the port mapping
in
docker-compose.yml(e.g.,ports: - 8080:80). - Permission errors on Linux: Run Sail with
sail up -das your user, but if you get permission issues, consider adding your user to thedockergroup. - Container not starting: Check logs with
sail logs. - MySQL connection refused: Ensure
DB_HOST=mysqlin.env. - Composer out of memory: Increase memory limit in
.envor usesail composer install --no-dev. - Mailhog not receiving emails: Check that
MAIL_HOST=mailhogandMAIL_PORT=1025are correct.
sail logs to see real-time container logs,
and sail exec laravel.test bash to get inside the container for inspection.
9. Best Practices
- Use Sail for local development — it's the official Laravel solution and ensures a consistent environment.
- Keep Docker images updated — periodically rebuild with
sail buildto get security patches. - Store persistent data in volumes — Sail uses volumes for databases and caches, so data survives container restarts.
- Use environment variables — Never hard-code credentials; use
.envand override for different environments. - Optimize for performance — On macOS, use
mutagenor Docker Desktop's file sharing settings for better performance. - Extend Sail with additional services — Easily add tools like phpMyAdmin, Adminer, or Elasticsearch as separate services.
- Version control your
docker-compose.yml— Share the configuration with your team to maintain parity. - Use Sail in CI/CD — You can run Sail in GitHub Actions or GitLab CI to test your application in the same environment.
0 Comments
thanks for your comments!