Docker in Production: Automated Deployment with GitHub Actions

10 min readUpdated on

This comprehensive guide will transform your Laravel deployment process into a smooth, automated pipeline using Docker and GitHub Actions. Learn how to set up a bulletproof production environment that scales with your needs.

0. Create User (optional—you can use your non-root user)

bash
# Create user with proper primary group
sudo adduser deployer --ingroup www-data
sudo usermod -aG sudo deployer

1. Initial Server Setup

bash
# Install Docker and Docker Compose (the convenience script is fine for a quick start;
# Docker's docs recommend the apt repository install for production servers)
curl -fsSL https://get.docker.com | sudo sh

# Add user to Docker group (membership in the docker group is effectively root access on the host)
sudo usermod -aG docker deployer

2. Set Up SSH Key for GitHub Actions (as deployer user)

bash
# Create SSH directory
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Generate SSH key
ssh-keygen -t ed25519 -N "" -C "github-actions-deploy"

# Add public key to authorized_keys
cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# Display the private key
cat ~/.ssh/id_ed25519

3. Add GitHub Secrets

Add the following secrets to your GitHub repository:

  • SSH_HOST: Your VPS IP address or domain
  • SSH_USER: deployer
  • SSH_KEY: The private SSH key generated above
  • SSH_PORT: 22 (or your custom SSH port)

Add one more secret for the production .env file (a repository variable is stored in plain text and shown in logs, so do not use one for this):

  • ENV_FILE: The contents of your .env file

If your ghcr.io packages are private, also run docker login ghcr.io once on the server with a personal access token that has the read:packages scope, otherwise docker compose pull will fail. Create the target directory too: mkdir -p ~/laravel.

4. Application Setup

Create the following files in your Laravel project:

4.1 Docker Configuration Files

  1. Create docker/php/Dockerfile:
dockerfile
FROM dommin/php-8.4-fpm-alpine:latest

USER root

RUN addgroup -g 1000 appuser && \
    adduser -D -u 1000 -G appuser appuser

RUN sed -i 's/user = www-data/user = appuser/g' /usr/local/etc/php-fpm.d/www.conf && \
    sed -i 's/group = www-data/group = appuser/g' /usr/local/etc/php-fpm.d/www.conf

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /var/www

COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist --no-scripts

COPY --chown=appuser:appuser . .
COPY --chown=appuser:appuser --from=node /var/www/public/build /var/www/public/build
COPY --chown=appuser:appuser docker/supervisord.conf /etc/supervisord.conf
COPY --chown=appuser:appuser docker/php/php.ini /usr/local/etc/php/php.ini
COPY --chown=appuser:appuser docker/php/www.conf /usr/local/etc/php-fpm.d/www.conf

RUN mkdir -p \
    storage/framework/cache \
    storage/framework/sessions \
    storage/framework/views \
    storage/app/public \
    bootstrap/cache \
    storage/logs \
    /var/log/supervisor \
    /var/run/php \
    /var/log/php-fpm \
    /home/appuser/.cache/puppeteer \
    && chown -R appuser:appuser \
    storage \
    bootstrap/cache \
    public \
    /var/log/supervisor \
    /var/run/php \
    /var/log/php-fpm \
    /home/appuser/.cache/puppeteer \
    && chmod -R 775 storage bootstrap/cache

RUN ln -s /var/www/storage/app/public /var/www/public/storage

USER appuser

EXPOSE 9000

CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisord.conf"]

1.1 Create docker/supervisord.conf:

ini
[supervisord]
nodaemon=true
logfile=/var/www/storage/logs/supervisord.log
pidfile=/tmp/supervisord.pid
user=appuser

[program:php-fpm]
command=/usr/local/sbin/php-fpm --nodaemonize
user=appuser
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stderr_logfile=/dev/stderr
stdout_logfile_maxbytes=0
stderr_logfile_maxbytes=0

[program:horizon]
command=php /var/www/artisan horizon
user=appuser
autostart=true
autorestart=true
stdout_logfile=/var/www/storage/logs/horizon.log
stderr_logfile=/dev/stderr
stdout_logfile_maxbytes=0
stderr_logfile_maxbytes=0
stopwaitsecs=3600

[program:scheduler]
command=php /var/www/artisan schedule:work
user=appuser
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stderr_logfile=/dev/stderr
stdout_logfile_maxbytes=0
stderr_logfile_maxbytes=0

[program:reverb]
command=php /var/www/artisan reverb:start
user=appuser
autostart=true
autorestart=true
stdout_logfile=/var/www/storage/logs/reverb.log
stderr_logfile=/dev/stderr
stdout_logfile_maxbytes=0
stderr_logfile_maxbytes=0
stopwaitsecs=3600

1.3 Create docker/php/php.ini:

ini
[PHP]
expose_php = Off
max_execution_time = 120
max_input_time = 120
memory_limit = 256M

[opcache]
opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0
opcache.enable_cli=0

[File Uploads]
upload_max_filesize = 64M
post_max_size = 64M
max_file_uploads = 20

[Date]
date.timezone = Europe/Warsaw

[Error]
display_errors = Off
display_startup_errors = Off
log_errors = On
error_reporting = E_ALL & ~E_DEPRECATED
error_log = /var/www/storage/logs/php-error.log

1.4 Create docker/php/www.conf:

ini
[www]
user = appuser
group = appuser

listen = 0.0.0.0:9000

pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3
pm.status_path = /status

access.log = /proc/self/fd/1
catch_workers_output = yes
decorate_workers_output = no
  1. Create docker/nginx/Dockerfile:
dockerfile
FROM nginx:stable-alpine

# Declare build arguments
ARG HTPASSWD_USER
ARG HTPASSWD_PASS

# Create necessary directories first
RUN mkdir -p /var/www/public

COPY --from=node /var/www/public/build /var/www/public/build

COPY public/*.php public/*.txt public/*.ico /var/www/public/

COPY docker/nginx/conf.d /etc/nginx/conf.d

# Create .htpasswd file for basic auth (optional)
RUN if [ -n "$HTPASSWD_USER" ] && [ -n "$HTPASSWD_PASS" ]; then \
    apk add --no-cache apache2-utils && \
    htpasswd -b -c /etc/nginx/.htpasswd "$HTPASSWD_USER" "$HTPASSWD_PASS"; \
fi

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
  1. Create docker/node/Dockerfile
dockerfile
FROM node:22-alpine

WORKDIR /var/www

COPY package*.json ./
RUN npm ci

COPY vite.config.ts tsconfig.json ./

COPY . .

RUN npm run build

The builder image no longer receives the full production .env: that file holds database and API secrets, and anything copied into an image is readable by everyone who can pull it. If Vite needs VITE_* values at build time, pass only those, for example as build arguments.

  1. Create docker-compose.production.yml:
yaml
services:
  app:
    image: ${REGISTRY}/${PHP_IMAGE_NAME}:${TAG:-latest}
    container_name: laravel_app
    restart: unless-stopped
    working_dir: /var/www
    env_file: .env
    volumes:
      - laravel_storage:/var/www/storage
      - ./.env:/var/www/.env
    ports:
      - '8080:8080'
    networks:
      - laravel_network
    depends_on:
      - redis

  nginx:
    image: ${REGISTRY}/${NGINX_IMAGE_NAME}:${TAG:-latest}
    container_name: laravel_nginx
    restart: unless-stopped
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - laravel_storage:/var/www/storage
    networks:
      - laravel_network
    depends_on:
      - app

  redis:
    image: redis:alpine
    container_name: laravel_redis
    restart: unless-stopped
    networks:
      - laravel_network
    volumes:
      - redis_data:/data

networks:
  laravel_network:
    driver: bridge

volumes:
  laravel_storage:
  redis_data:

4.2 GitHub Actions Workflow

Create .github/workflows/workflow.yml:

yaml
name: 🚀 Build, Push and Deploy

on:
  push:
    branches:
      - main

env:
  REGISTRY: ghcr.io
  NODE_IMAGE_NAME: dommmin/laravel-production-node-builder
  PHP_IMAGE_NAME: dommmin/laravel-production-php
  NGINX_IMAGE_NAME: dommmin/laravel-production-nginx
  DOCKER_BUILDKIT: 1

jobs:
  build:
    name: 🏗️ Build and Push Images
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push Node builder image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: docker/node/Dockerfile
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.NODE_IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.NODE_IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64

      - name: Build and push PHP image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: docker/php/Dockerfile
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.PHP_IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.PHP_IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64
          build-contexts: |
            node=docker-image://${{ env.REGISTRY }}/${{ env.NODE_IMAGE_NAME }}:${{ github.sha }}

      - name: Build and push Nginx image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: docker/nginx/Dockerfile
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.NGINX_IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.NGINX_IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64
          build-contexts: |
            node=docker-image://${{ env.REGISTRY }}/${{ env.NODE_IMAGE_NAME }}:${{ github.sha }}
          build-args: |
            HTPASSWD_USER=${{ secrets.HTPASSWD_USER }}
            HTPASSWD_PASS=${{ secrets.HTPASSWD_PASS }}

  deploy:
    name: 🚀 Deploy to Production
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4 # Critical for accessing files!

      - name: Setup SSH Authentication
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_KEY }}

      - name: Configure known_hosts
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan -p ${{ secrets.SSH_PORT }} ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts

      - name: Prepare environment file
        env:
          ENV_FILE: ${{ secrets.ENV_FILE }}
        run: |
          printf '%s\n' "$ENV_FILE" > .env
          {
            echo "REGISTRY=${{ env.REGISTRY }}"
            echo "PHP_IMAGE_NAME=${{ env.PHP_IMAGE_NAME }}"
            echo "NGINX_IMAGE_NAME=${{ env.NGINX_IMAGE_NAME }}"
            echo "TAG=${{ github.sha }}"
          } >> .env

      - name: Transfer deployment files
        run: |
          scp -P ${{ secrets.SSH_PORT }} \
            docker-compose.production.yml \
            ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:~/laravel/docker-compose.yml

          scp -P ${{ secrets.SSH_PORT }} \
            .env deploy.sh \
            ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:~/laravel/

      - name: Trigger deployment script
        run: |
          ssh -p ${{ secrets.SSH_PORT }} ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} \
            "cd ~/laravel && chmod +x deploy.sh && ./deploy.sh"

4.3 Deployment Script

Create deploy.sh:

bash
#!/bin/bash

# Fail immediately if any command fails
set -eo pipefail

# Deployment header
echo "🚀 Starting production deployment..."
echo "🕒 $(date)"

# Pull latest images
echo "📥 Pulling updated Docker images..."
docker compose pull

# Stop existing containers if running
echo "🛑 Stopping existing containers..."
docker compose down --remove-orphans

# Start fresh containers
echo "🔄 Starting new containers..."
docker compose up -d --force-recreate

# Run application maintenance
echo "🔧 Running application maintenance tasks..."
docker compose exec -T app php artisan optimize:clear
docker compose exec -T app php artisan optimize
docker compose exec -T app php artisan storage:link
docker compose exec -T app php artisan migrate --force

# Cleanup old Docker objects
echo "🧹 Cleaning up unused Docker resources..."
docker image prune -f

# Success message
echo "✅ Deployment completed successfully!"
echo "🕒 $(date)"

4.4 Directory Structure

Your Laravel project should have the following structure:

.
├── .github
│   └── workflows
│       └── workflow.yml
├── docker
│   ├── node
│   │   ├── Dockerfile
│   ├── nginx
│   │   ├── Dockerfile
│   │   └── conf.d
│   │       └── default.conf
│   ├── supervisord.conf
│   └── php
│       ├── Dockerfile
│       ├── php.ini
│       └── www.conf
├── docker-compose.production.yml
├── deploy.sh
└── ... (other Laravel files)

Troubleshooting

  • Permission Issues:

    bash
    # Check Docker access
    docker ps
    
  • Docker Issues:

    bash
    # Check Docker status
    sudo systemctl status docker
    
  • Deployment Failures: Check the GitHub Actions logs for detailed error messages.

Conclusion

After completing these steps, your server will be ready for Docker-based Laravel deployment. The setup ensures:

  • Proper permissions for Docker and Laravel
  • Secure SSH access for GitHub Actions
  • Persistent storage for Laravel data
  • Every deploy tagged with the commit SHA, so a rollback is TAG=<sha> in the server .env followed by docker compose up -d
  • Security best practices implementation

Related articles

Maintenance and growth

Do you need cleaner deployments or maintenance?

I help teams stabilize environments, improve release flow, and keep existing systems moving without unnecessary disruption.

Comments (0)
Sign in to leave a comment

You need to be signed in to add a comment.

Login

Need someone to take responsibility for the next step?

Let’s talk about your project and define a scope that actually makes sense for your goals.