Modernizing Local Development with Laravel Sail and Docker

Overview of Containerized Development

Setting up a local development environment often leads to the infamous "it works on my machine" dilemma. Laravel Sail solves this by providing a lightweight command-line interface for interacting with Docker. By packaging your application and its dependencies into isolated containers, you ensure that your local environment perfectly mirrors production. This consistency eliminates configuration drift and allows you to run complex services like Redis or MySQL without cluttering your host operating system.

Prerequisites

Before running your first container, you need Docker Desktop installed and running on your machine. You should have a basic understanding of the terminal and the Laravel framework.

Key Libraries & Tools

• Docker: The underlying platform that manages containers.
• Laravel Sail: A lightweight CLI that wraps Docker Compose commands into a Laravel-friendly syntax.
• Docker Compose: The tool Sail uses to orchestrate multiple containers (app, database, cache) defined in a docker-compose.yml file.
• TablePlus: A recommended GUI for connecting to and managing the databases running inside your Sail containers.

Setting Up the Environment

If you have an existing Laravel application, you can integrate Sail by running the following command in your terminal:

php artisan sail:install

This command prompts you to select which services (like MySQL, Meilisearch, or Selenium) you want to include. It generates a docker-compose.yml file in your root directory. Once configured, start your environment with:

./vendor/bin/sail up

The first run downloads the necessary Docker Images, but subsequent starts happen in seconds.

Syntax and Alias Conventions

Typing ./vendor/bin/sail for every command is tedious. To streamline your workflow, add an alias to your shell configuration file (.zshrc or .bashrc):

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

Now you can run standard Artisan commands directly through the container:

sail artisan migrate
sail composer require laravel/sanctum

Practical Examples

Sail excels in team environments. When a new developer joins, they simply clone the repo and run sail up. There is no need to manually install PHP versions or database drivers. For larger apps, you can easily add services like Mailpit to catch outgoing emails during testing without setting up an actual SMTP server.

Tips & Gotchas

Remember that since your app runs inside a container, any command that needs to interact with your code or the database must be prefixed with sail. If you accidentally run php artisan migrate on your local machine instead of through Sail, it will likely fail or connect to the wrong database instance. Always check the Docker Dashboard to ensure your containers are healthy if you encounter connection issues.