How to Set Up & Use Laravel Sail? (A Docker CLI for Devs)

Are you struggling with complex local development setups for your Laravel projects? Laravel Sail might just be the solution you’ve been waiting for. This powerful Docker-based tool simplifies your development workflow by offering a pre-configured environment with everything you need – PHP, MySQL, Redis, and more – contained within isolated Docker containers. No more manual setup hassles.

In this guide, we’ll walk you through mastering Laravel Sail, whether you’re a seasoned developer or just starting out. From basic setup to advanced features, we’ll cover everything you need to know to make the most of this efficient development environment.

What is Laravel Sail?

Laravel Sail is an official, lightweight command-line interface. It’s designed to streamline your Laravel application’s local development experience. At its core, Sail is a wrapper for Docker Compose. With it, you get a simple set of commands to interact with a pre-configured Docker environment.

When you initiate a new Laravel project, Sail is included by default. However, developers who prefer a virtualized setup may implement Laravel Homestead for local development to achieve a similar isolated environment. Running a single ./vendor/bin/sail up command starts a complete containerized environment. It typically includes:

• A PHP runtime
• A web server (NGINX or Apache)
• A MySQL database
• A Redis server
• A mailhog instance for email testing

Key Features of Laravel Sail

• Zero Docker Configuration: Interact with your environment using simple Sail commands without needing to learn Docker or edit complex docker-compose.yml files.
• Pre-Built Services: Spin up a full development stack instantly, including MySQL, PostgreSQL, Redis, and Mailpit, with a single command.
• Cross-Platform Consistency: Ensure every developer on your team has an identical local environment, eliminating “it works on my machine” issues across macOS, Windows, and Linux. For lightweight macOS setups, Laravel Valet offers another efficient approach tailored for Apple devices.
• Integrated Testing: Execute your application’s PHPUnit tests seamlessly within the isolated Docker container, guaranteeing a clean state for every test run.
• Customizable Containers: While pre-configured, the underlying Docker setup is fully extensible. So you can add new services like Meilisearch or MongoDB as your project grows.

Common Use Cases of Laravel Sail

• Onboarding New Developers: Drastically reduces setup time for new team members. A single command gets their local environment running with all required services. So they can contribute code on their first day.
• Standardizing Team Environments: Ensure every developer, regardless of their operating system, is working with an identical application stack. It prevents environment-specific bugs.
• Quick Project Prototyping: Rapidly spin up new Laravel projects or test new packages without worrying about local server conflicts or complex configuration.
• Isolated Feature Testing: Safely test features that rely on specific versions of PHP, databases, or caching systems without altering your local machine’s main setup.
• Learning Laravel: Provides an ideal, no-hassle environment for beginners to start with the framework, removing the initial barrier of server configuration.

Laravel Sail offers a simple, consistent, and isolated setup, so you can focus on building scalable applications.

How Does Laravel Sail Work?

Laravel Sail works by leveraging Docker to create a consistent, isolated development environment. Here’s a simple breakdown of the process:

Dockerfile & docker-compose.yml

When you install Sail, it provides a Dockerfile that defines the PHP environment and a docker-compose.yml file. That specifies all your application’s services (like MySQL, Redis, and the web server).

The Sail Script

The ./vendor/bin/sail file is a bash script that acts as a convenient wrapper. When you run a Sail command, it automatically executes docker-compose commands using these configuration files. That eliminates the need for you to type them out manually.

Container Orchestration

When you run sail up, Docker Compose reads the configuration and starts the defined containers. These containers run in an isolated network, meaning they don’t interfere with other software on your local machine.

Command Execution

When you prefix a command with sail (e.g., sail artisan), the script executes that command inside the application’s PHP container. This ensures you’re always using the correct versions of PHP, Composer, and Node that your project requires.

In essence, Sail translates your simple commands into complex Docker instructions. It manages the entire environment for you behind the scenes.

What are the Prerequisites to Install Laravel Sail?

Before using Laravel Sail, ensure your system meets these requirements:

• Docker Desktop: The only strict requirement. Sail is a Docker wrapper, so you must have Docker Desktop installed and running on your local machine (macOS, Windows, or Linux).
• Composer: Necessary for creating a new Laravel project, which is the standard way to get Sail. It is included by default in new Laravel installations.
• Compatible PHP & Laravel Versions: No local PHP is technically needed for Sail itself (it runs PHP in a container). But you will need a local PHP environment (>= 8.1) and Composer to create a new project.
• Adequate System Resources: Allocate sufficient CPU and RAM (at least 4GB) to Docker in its settings to ensure the containers run smoothly.
• Command-Line Access: You need comfort with using a terminal or command prompt to execute Sail’s artisan and bash commands.

With the prerequisites in place, you’re ready to undertake the Laravel Sail setup and development.

How to Install Laravel Sail?

Streamlining your Laravel development workflow starts with a robust development environment. Laravel Sail comes to the rescue, leveraging Docker to create a pre-configured and isolated environment. But if you’re exploring Laravel Homestead alternatives, Sail stands out as one of the easiest to set up and maintain.

Here’s how you go about it.

Prefer Videos Over Text? Here’s a Quick Setup:

Step 1: Create a New Laravel Project

Start by creating a new Laravel application using Composer. Run the following command in your terminal. This will create a project directory named my-sail-app.

composer create-project laravel/laravel my-sail-app

Navigate into your new project directory:

cd my-sail-app

Step 2: Install Laravel Sail

While Sail comes pre-installed in new projects, you can explicitly install it using Composer. This is useful for existing projects.

composer require laravel/sail --dev

After installation, publish Sail’s Docker configuration file with:

php artisan sail:install

Step 3: Choose and Configure Database

During the sail:install command, you will be prompted to select which services you want. You can choose MySQL, PostgreSQL, Redis, etc. The default is a MySQL stack. Your .env file will be automatically updated with the correct database connection details for Docker.

Step 4: Start Docker Containers

Ensure Docker Desktop is running. Then, start all the defined services (like your web server and database) by executing:

./vendor/bin/sail up

Add the -d flag to run the containers in the background:

./vendor/bin/sail up -d

Step 5: Access Your Laravel Application

Once the containers are running, your application will be available in your web browser at http://localhost. You should see the default Laravel welcome page.

Step 6: Create Alias for Sail Commands

Typing ./vendor/bin/sail repeatedly is cumbersome. Instead, you can use a shell alias to shorten the command to just sail. Run this command to create the alias:

alias sail='bash vendor/bin/sail'

You can now run commands like sail artisan, sail composer, and sail test. To make this alias permanent, add it to your shell’s configuration file (e.g., ~/.zshrc or ~/.bashrc).While Laravel Sail is quite straightforward for application development, there may still be some issues. For that, our dedicated Laravel development services will be helpful.

Example: Building a CRUD Application Using Laravel Sail

This example demonstrates building a simple project management application with Laravel Sail, creating, reading, updating, and deleting projects.

Start Your Environment

First, navigate to your project directory and start the Sail environment:

cd my-project
sail up -d

Generate Model and Migration

Create a Project model with a migration file:

sail artisan make:model Project -m

Edit the migration to include title and description fields, then run:

sail artisan migrate

Create Routes and Controller

Add resource routes in routes/web.php:

Route::resource('projects', ProjectController::class);

Generate the controller:

sail artisan make:controller ProjectController --resource

Implement Controller Methods

In ProjectController.php, implement the key CRUD methods:

• index(): return view(‘projects.index’, [‘projects’ => Project::all()]);
• create(): Show project creation form
• store(): Validate and save new project: Project::create($request->validated());
• edit(): Show form to edit existing project
• update(): Validate and update project
• destroy(): Delete project by ID

Create Blade Views

Create simple Blade templates in resources/views/projects/:

• index.blade.php: Loop through projects and display in a table
• create.blade.php & edit.blade.php: Forms with fields for title and description

Test Your Application

Visit http://localhost/projects in your browser. You can now:

• Click “Create New Project” to add entries
• View all projects in a list
• Click “Edit” to modify existing projects
• Click “Delete” to remove projects

Throughout this process, all commands run using sail prefix. So they execute in the proper Docker environment with your database and other services readily available.

Wrapping Up

Laravel Sail presents a robust solution for managing Laravel applications with Docker, offering streamlined setup and deployment processes. Its user friendly interface and extensive documentation make it accessible to developers of all levels. With benefits like scalability and ease of use, Laravel Sail is an invaluable tool for improving the Laravel project’s development experience.

Still confused about how Laravel Sail can benefit your application? Hire Laravel developers for consultation, solutions, and step-by-step deployment

FAQs About Laravel Sail

Mayur Upadhyay

Leading digital transformation projects with precision and creativity, Mayur turns complex ideas into results-driven web solutions. As Project Leader at WPWeb Infotech, he leverages his expertise in Laravel, PHP, Shopify, and Drupal to deliver innovation, scalability, and long-term success.