Introduction

Continuous Integration (CI) and Continuous Deployment (CD) are essential practices in modern software development. With Jenkins and Docker, you can automate building, testing, and deploying Laravel projects safely and consistently.

Recommendation

Performance: If Jenkins runs on the same server as your Laravel containers, mount the Docker socket (/var/run/docker.sock) into the Jenkins container. This allows Jenkins to manage host Docker containers directly.
Security: Ensure proper permissions when sharing the socket, as it grants the Jenkins user full control over the host’s Docker engine.
Consistency: This approach ensures deployment consistency and reduces human error, making the pipeline smoother and easier to manage.

Step 1: Prepare Laravel 12 Project

First, initialize your Laravel 12 project and set up your version control.

Install Laravel 12 locally:

Bash

composer create-project --prefer-dist laravel/laravel:^12 laravel-12

Initialize Git:

Bash

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

Step 2: Docker Structure for Laravel

2.1 Nginx Configuration

Create project_root/docker/nginx/conf.d/default.conf:

Nginx

server {
    listen 80;
    server_name localhost;
    
    root /var/www/html/public;
    index index.php index.html;

    location /build/ {
        alias /var/www/html/public/build/;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME /var/www/html/public$fastcgi_script_name;
    }

    location ~ /\.ht {
        deny all;
    }
}

2.2 Nginx Dockerfile

Create project_root/docker/nginx/Dockerfile:

Dockerfile

FROM laravel-12:latest AS laravel-app-assets
FROM nginx:alpine
RUN mkdir -p /var/www/html/public
COPY conf.d /etc/nginx/conf.d
COPY --from=laravel-app-assets /var/www/html/public/build /var/www/html/public/build
COPY --from=laravel-app-assets /var/www/html/public/index.php /var/www/html/public/index.php
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

2.3 PHP + Node Build Dockerfile

Create project_root/docker/php/Dockerfile. This uses a multi-stage build to compile assets with Node 22 and serve the app via PHP 8.3.

Dockerfile

# Stage 1 - Node build
FROM node:22-alpine AS node-builder
WORKDIR /app
COPY package.json package-lock.json* pnpm-lock.yaml* ./
RUN if [ -f pnpm-lock.yaml ]; then npm i -g pnpm && pnpm install; \
    elif [ -f package-lock.json ]; then npm ci; \
    else npm install; fi
COPY resources resources
COPY public public
COPY vite.config.* tailwind.config.* postcss.config.* ./
RUN npm run build

# Stage 2 - PHP runtime
FROM php:8.3-fpm-alpine
RUN apk add --no-cache bash curl zip unzip libpng libpng-dev oniguruma-dev libxml2-dev icu-dev
RUN docker-php-ext-install pdo pdo_mysql mbstring exif pcntl bcmath gd intl
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /var/www/html
COPY . .
RUN composer install --no-dev
COPY --from=node-builder /app/public/build public/build
RUN chown -R www-data:www-data storage bootstrap/cache
USER www-data
CMD ["php-fpm"]

2.4 Docker Compose

Create project_root/docker-compose.yml:

YAML

services:
  app:
    image: laravel-12:latest
    container_name: laravel-12-app
    env_file:
      - .env
    restart: always

  nginx:
      build:
        context: ./docker/nginx
        dockerfile: Dockerfile
      container_name: laravel-12-nginx
      ports:
        - "80:80"
      depends_on:
        - app

Step 3: Jenkinsfile for CI/CD

Create the project_root/Jenkinsfile to define the automation logic.

Groovy

pipeline {
    agent any

    environment {
        IMAGE_NAME = "laravel-12"
        TAG = "${BUILD_NUMBER}"
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Prepare Env') {
            steps {
                withCredentials([file(credentialsId: 'laravel-12-env', variable: 'ENV_FILE')]) {
                    sh 'cp $ENV_FILE .env'
                }
            }
        }

        stage('Build Image') {
            steps {
                sh '''
                docker build \
                    -f docker/php/Dockerfile \
                    -t ${IMAGE_NAME}:${TAG} \
                    -t ${IMAGE_NAME}:latest \
                    .
                '''
            }
        }

        stage('Deploy') {
            steps {
                sh '''
                docker compose build nginx
                docker compose up -d
                docker compose exec -u root app sh -c "mkdir -p database && touch database/database.sqlite && chown -R www-data:www-data database"
                docker compose exec app php artisan migrate --force
                docker compose exec app php artisan optimize
                '''
            }
        }
    }

    post {
        success { echo "Laravel 12 deployed (build ${TAG})" }
        failure { echo "Deployment failed" }
        always {
            sh "docker image prune -f || true"
        }
    }
}

Step 4: Integrating Jenkins with GitLab

4.1 Install Jenkins Plugins

Navigate to Manage Jenkins > Plugins and install:

GitLab Plugin
GitLab API Plugin
GitLab Authentication Plugin

4.2 Setup SSH Key

Connect Jenkins to GitLab securely:

Generate key: docker exec -it jenkins ssh-keygen -t rsa -b 4096
Add to GitLab: Copy the public key to GitLab → Profile → SSH Keys.

4.3 Add Credentials in Jenkins

SSH Private Key: Add a "SSH Username with private key" credential with ID gitlab-ssh.
Secret File: Add your production .env file as a "Secret file" credential with ID laravel-12-env.

4.4 Configure GitLab Webhook

In GitLab, go to Settings → Integrations → Jenkins:

Jenkins URL: https://your-jenkins-url/
Trigger: Select "Push events" and "Merge request events".

Step 5: Test CI/CD

Create a Merge Request in GitLab.
Once merged into the main branch, Jenkins will trigger automatically.
Monitor the build in the Jenkins dashboard to ensure the image builds and containers restart successfully.

Conclusion

By using the DooD (Docker-out-of-Docker) technique, you achieve a lean CI/CD environment where:

Docker isolates the Laravel environment.
Jenkins orchestrates the build only when code changes.
Automation handles migrations and optimization, reducing the risk of manual errors.