Comprehensive Guide to Deploying a Laravel Project with Docker and Sail in Production

Deployment of a Laravel project in a production environment may be challenging, but it is greatly simplified by using Docker and Laravel Sail. This means the guide will take you step by step in deploying a Laravel application with Docker and Sail. It's pretty easy and swift to set up in your production environment.

Table of Contents

1. Introduction
2. Prerequisites
3. Setting Up the Laravel Project
4. Configuring Docker
5. Using Laravel Sail
6. Preparing for Production
7. Deploying to Production
8. Managing and Scaling Your Application
9. Troubleshooting Common Issues
10. Conclusion

---

1. Introduction

Laravel is a powerful PHP framework that provides a robust set of tools and an elegant syntax for web application development. Docker, a containerization platform, allows developers to package applications with all their dependencies, ensuring consistency across different environments. Laravel Sail is an official package that provides a simple command-line interface for interacting with Laravel's Docker configuration.

Deploying a Laravel application using Docker and Sail in a production environment offers several benefits, including consistency, scalability, and ease of management. This guide will cover the step-by-step process, from setting up your Laravel project to deploying it on a production server.

---

2. Prerequisites

Before diving into the deployment process, ensure you have the following prerequisites:

• Basic understanding of Laravel and Docker.
• A server or cloud instance (e.g., AWS, DigitalOcean, etc.).
• Docker installed on your local machine.
• Composer installed on your local machine.
• SSH access to your production server.
• Domain name pointed to your server's IP address.

---

3. Setting Up the Laravel Project

Step 1: Create a New Laravel Project

First, create a new Laravel project using Composer. Open your terminal and run:

composer create-project --prefer-dist laravel/laravel laravel-docker-sail
cd laravel-docker-sail

Step 2: Initialize Git Repository

Initialize a Git repository in your project directory:

git init
git add .
git commit -m "Initial commit"

---

4. Configuring Docker

Step 1: Install Docker

Ensure Docker is installed on your local machine. You can download and install Docker from the official website.

Step 2: Create a Dockerfile

In your project root, create a Dockerfile with the following content:

# Use the official PHP image as the base image
FROM php:8.0-fpm

# Set the working directory
WORKDIR /var/www

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpng-dev \
    libjpeg62-turbo-dev \
    libfreetype6-dev \
    locales \
    zip \
    jpegoptim optipng pngquant gifsicle \
    vim \
    unzip \
    git \
    curl

# Clear cache
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# Install PHP extensions
RUN docker-php-ext-install pdo_mysql mbstring zip exif pcntl
RUN docker-php-ext-configure gd --with-freetype --with-jpeg
RUN docker-php-ext-install gd

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Copy existing application directory contents
COPY . /var/www

# Copy existing application directory permissions
COPY --chown=www-data:www-data . /var/www

# Change current user to www
USER www-data

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

Step 3: Create a Docker Compose File

Create a docker-compose.yml file in your project root with the following content:

version: '3.8'

services:
  laravel:
    build:
      context: .
      dockerfile: Dockerfile
    image: laravel-docker-sail
    container_name: laravel_app
    restart: unless-stopped
    tty: true
    environment:
      SERVICE_NAME: laravel_app
      SERVICE_TAGS: dev
    working_dir: /var/www
    volumes:
      - ./:/var/www
    networks:
      - laravel

  mysql:
    image: mysql:5.7
    container_name: mysql
    restart: unless-stopped
    tty: true
    ports:
      - "3306:3306"
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_ROOT_PASSWORD: secret
      SERVICE_TAGS: dev
      SERVICE_NAME: mysql
    volumes:
      - mysql:/var/lib/mysql
    networks:
      - laravel

networks:
  laravel:

volumes:
  mysql:

Step 4: Build and Run Docker Containers

Build and run the Docker containers using Docker Compose:

docker-compose up --build -d

You should now have a running Docker container for your Laravel application and a MySQL database.

---

5. Using Laravel Sail

Laravel Sail provides a simple command-line interface for managing your Laravel Docker environment.

Step 1: Install Laravel Sail

You can install Laravel Sail via Composer:

composer require laravel/sail --dev

Step 2: Publish Sail Configuration

Publish Sail's Docker configuration to your project:

php artisan sail:install

Step 3: Start Sail

Start your Sail environment:

./vendor/bin/sail up

You can now use Sail to manage your Laravel Docker environment. For example, you can run database migrations using:

./vendor/bin/sail artisan migrate

---

6. Preparing for Production

Step 1: Environment Configuration

Ensure your .env file is configured correctly for the production environment. Update the following variables:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=secret

Step 2: Optimize Configuration

Optimize your application for production by running the following commands:

./vendor/bin/sail artisan config:cache
./vendor/bin/sail artisan route:cache
./vendor/bin/sail artisan view:cache

Step 3: Build Production Docker Image

Build a production-ready Docker image:

docker build -t laravel-docker-sail:production .

---

7. Deploying to Production

Step 1: Set Up Production Server

Ensure your production server has Docker and Docker Compose installed. Connect to your server via SSH:

ssh user@your-server-ip

Step 2: Clone Repository

Clone your Laravel project repository to your production server:

git clone https://github.com/yourusername/laravel-docker-sail.git
cd laravel-docker-sail

Step 3: Update Environment Variables

Update the .env file on your production server with the appropriate values.

Step 4: Run Docker Compose

Run Docker Compose to start your Laravel application:

docker-compose up -d

Your Laravel application should now be running in a production environment.

---

8. Managing and Scaling Your Application

Step 1: Monitoring

Use Docker tools to monitor the health and performance of your containers. Docker provides built-in commands like docker stats to view resource usage.

Step 2: Scaling

To scale your application, you can increase the number of running containers. Update your docker-compose.yml file to specify the desired number of replicas:

services:
  laravel:
    ...
    deploy:
      replicas: 3

Apply the changes:

docker-compose up -d --scale laravel=3

Step 3: Load Balancing

Set up a load balancer (e.g., Nginx, HAProxy) to distribute traffic across multiple instances of your Laravel application.

---

9. Troubleshooting Common Issues

Issue 1: Container Not Starting

If your container is not starting, check the logs to identify the issue:

docker-compose logs

Look for error messages and fix any configuration issues.

Issue 2: Database Connection Errors

Ensure your database credentials in the .env file are correct. Verify the MySQL container is running and accessible.

Issue 3: File Permissions

If you encounter file permission issues, ensure the correct user permissions are set in your Dockerfile and Docker Compose configuration.

---

10. Conclusion

Deploying a Laravel project with Docker and Sail in a production environment offers a streamlined and efficient workflow. By following this guide, you can set up, manage, and scale your Laravel application with ease. The combination of Laravel, Docker, and Sail provides a powerful toolset for modern web application deployment, ensuring consistency and reliability across different environments.