Step-by-Step Guide: Deploying Grav CMS on Linux VPS, macOS, & Windows with Docker LAMP Stack

A step-by-step beginner-friendly guide to setting up and deploying Grav CMS using docker-lamp-grav on Linux VPS, macOS, and Windows environments.

Welcome to this comprehensive, step-by-step guide! In this tutorial, we will walk you through deploying Grav CMS using the official open-source repository milkboyinchina/docker-lamp-grav across Linux VPS, macOS, and Windows.

Whether you are launching a cloud production server, local macOS development machine, or Windows workstation, containerizing your LAMP stack with Docker ensures consistent runtime environments, instant rollbacks, and effortless deployment.

Step 1: System Requirements & Server Preparation

Before diving into container deployment, ensure your host environment meets the baseline specs:

• Linux VPS / Server: Ubuntu 22.04 / 24.04 LTS, Debian 12, AlmaLinux 9, Rocky Linux 9, Fedora, CentOS Stream, Arch Linux, or any Linux distribution capable of running Docker. (Minimum 1 vCPU, 1 GB RAM, 15 GB SSD storage). Firewall ports 22 (SSH), 80 (HTTP), and 443 (HTTPS) open.
• macOS: macOS Monterey (12.0) or newer (Apple Silicon M1/M2/M3 or Intel).
• Windows: Windows 10 64-bit (Build 19044+) or Windows 11 with WSL2 enabled.

Step 2: Installing Docker Engine (Linux, macOS, & Windows)

Linux Server (Ubuntu, Debian, AlmaLinux, Rocky, & others)

Run the official convenience script to install Docker CE and the Docker Compose plugin:

# Update packages & install Docker engine
sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker

macOS (Intel & Apple Silicon M1/M2/M3)

1. Download Docker Desktop for Mac from docker.com/products/docker-desktop.
2. Choose Mac with Apple Silicon (M1/M2/M3) or Mac with Intel chip.
3. Open the .dmg file and drag Docker.app into your Applications folder.
4. Launch Docker Desktop from Applications and verify in Terminal:

   docker --version
   docker compose version

Windows 10 / 11 (WSL2 & PowerShell)

1. Enable WSL2 (Windows Subsystem for Linux) by running PowerShell as Administrator:

   wsl --install

2. Download Docker Desktop for Windows from docker.com/products/docker-desktop.
3. Run installer and ensure Use WSL 2 instead of Hyper-V is selected.
4. Restart your computer, launch Docker Desktop, and verify in PowerShell or WSL2:

   docker --version
   docker compose version

Step 3: Cloning the Docker-LAMP-Grav Repository

Next, clone the repository milkboyinchina/docker-lamp-grav onto your machine:

# Clone the repository into your workspace
git clone https://github.com/milkboyinchina/docker-lamp-grav.git docker-lamp-grav

# Navigate into the project folder
cd docker-lamp-grav

The repository structure contains pre-configured container definitions for:

• Apache 2.4 with mod_rewrite enabled for Grav URL routing.
• PHP 8.3 FPM optimized with OPcache and core extensions (gd, zip, mbstring, curl, xml).
• Grav CMS Core with automated permission handling.

Adaptability: Deploying Other PHP Applications (WordPress, Laravel, Drupal)

While this stack comes pre-configured for Grav CMS, the underlying Apache 2.4 + PHP 8.3 FPM + Docker Compose architecture makes docker-lamp-grav a versatile foundation for any modern PHP application or framework:

• WordPress: Drop your WordPress files into the src/ directory, add a MariaDB/MySQL container to docker-compose.yml, and complete the setup wizard.
• Laravel: Place your Laravel application inside src/, set Apache's DocumentRoot to src/public, and run your Artisan migrations.
• Drupal & Symfony: The optimized PHP 8.3 extensions (gd, mbstring, zip, xml, opcache) provide out-of-the-box support for Drupal, Symfony, and CodeIgniter projects.

Step 4: Environment Configuration & Permissions

Copy the example environment file and set up your domain and directory permissions:

# Copy example environment configuration
cp .env.example .env

# Adjust file ownership for the Web server user (www-data) on Linux/macOS
sudo chown -R 33:33 src/user src/logs src/cache

If you wish to customize port bindings or environment settings, edit .env:

nano .env

Step 5: Launching Containers & Accessing Grav CMS

Build and launch the containerized stack in background detached mode (-d):

# Launch Docker LAMP Grav stack
docker compose up -d --build

Check the status of the running containers:

docker compose ps

Finalizing Setup in Your Browser

1. Open your web browser and navigate to your server's IP address or localhost: http://localhost/ or http://YOUR_SERVER_IP/
2. You will be greeted by the Grav CMS Admin Registration Screen.
3. Create your master admin account username, email, and password.
4. Log into the Grav Admin Panel to start creating content, customizing themes, and publishing articles!

Useful Maintenance Commands

Here are handy commands for managing your Grav Docker server across platforms:

# View live container logs
docker compose logs -f

# Clear Grav cache from host
docker compose exec web php bin/gpm clear-cache

# Restart container stack
docker compose restart

Congratulations! You now have a high-performance, containerized Grav CMS instance running smoothly on Linux, macOS, or Windows.