Setting Up a Multi-Environment Laravel Application with Docker and GitHub Actions

Introduction

In the world of web development, setting up a robust application that can seamlessly transition between multiple environments—development, staging, and production—is essential for ensuring both efficiency and reliability. Laravel, a popular PHP framework, simplifies this process with its elegant syntax and powerful features. When combined with Docker for containerization and GitHub Actions for CI/CD (Continuous Integration and Continuous Deployment), developers can streamline their workflows and ensure consistent environments. In this article, we’ll walk through the steps to set up a multi-environment Laravel application using Docker and GitHub Actions.

What is Docker?

Docker is a platform that allows developers to automate the deployment of applications inside lightweight, portable containers. Containers package an application and its dependencies, ensuring that it runs consistently across different computing environments. This is particularly useful in a multi-environment setup, where code needs to behave identically in development and production.

Key Benefits of Using Docker

• Isolation: Each container runs in its own environment, preventing conflicts.
• Portability: Containers can be easily moved between different systems.
• Scalability: Containers can be scaled up or down based on application needs.

What are GitHub Actions?

GitHub Actions is a CI/CD tool that allows you to automate workflows directly from your GitHub repository. It enables developers to build, test, and deploy code directly from their repositories, making it an excellent choice for automating the deployment of Laravel applications.

Key Benefits of Using GitHub Actions

• Integration: Seamlessly integrates with your GitHub repositories.
• Customization: Workflows are customizable and can be triggered by various events.
• Community Support: A rich ecosystem of actions created by the community.

Setting Up Your Laravel Application

Step 1: Create a New Laravel Project

First, ensure you have Composer installed on your machine. Then, create a new Laravel project:

composer create-project --prefer-dist laravel/laravel multi-env-laravel
cd multi-env-laravel

Step 2: Set Up Docker

Create a Dockerfile in the root of your Laravel project:

# Dockerfile
FROM php:8.1-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y libpng-dev libjpeg-dev libfreetype6-dev
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

# Set working directory
WORKDIR /var/www

# Copy existing application directory contents
COPY . .

# Install PHP dependencies
RUN composer install

EXPOSE 9000
CMD ["php-fpm"]

Next, create a docker-compose.yml file to define your application services:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/var/www
    ports:
      - "9000:9000"
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Step 3: Build and Run Docker Containers

Run the following command to build and start your containers:

docker-compose up -d

You can access your Laravel application by visiting http://localhost:9000.

Step 4: Configure Environment Variables

Create a .env file in the root of your Laravel project, which will hold your environment-specific settings:

APP_NAME=MultiEnvLaravel
APP_ENV=local
APP_KEY=base64:YOUR_APP_KEY
APP_DEBUG=true
APP_URL=http://localhost:9000
DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=password

Step 5: Set Up GitHub Actions

Create a new directory called .github/workflows in your project root and then create a file named ci.yml inside it:

name: CI Pipeline

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    services:
      db:
        image: mysql:5.7
        env:
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: laravel
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping -h localhost"
          --health-interval=30s
          --health-timeout=10s
          --health-retries=3

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'

      - name: Install dependencies
        run: composer install

      - name: Run migrations
        run: php artisan migrate

      - name: Run tests
        run: php artisan test

Step 6: Test Your Setup

Commit your changes and push them to your GitHub repository. This action will trigger the GitHub Actions workflow you just set up. Monitor the Actions tab in your repository to see the build and deployment processes in action.

Troubleshooting Common Issues

• Container Fails to Start: Check your Docker logs using docker-compose logs.
• Database Connection Errors: Ensure your database service is up and that the credentials in your .env file match those in the Docker configuration.
• Application Not Found: Verify that your Docker container is running and that you're accessing the correct port.

Conclusion

Setting up a multi-environment Laravel application with Docker and GitHub Actions can greatly enhance your development workflow. By leveraging Docker's containerization capabilities and GitHub Actions' automation features, you can ensure that your application runs consistently across different environments, making it easier to develop, test, and deploy your code. With these steps, you're well on your way to creating a scalable and maintainable Laravel application. Happy coding!