Docker WHMCS Development Environment

A complete Docker-based development environment for WHMCS with PHP 8.2, Apache, ionCube Loader, MariaDB, and MailHog. Perfect for developing addons, gateways, server modules, hooks, and templates.

Features

PHP 8.2 + Apache with all required extensions
ionCube Loader (automatically installed)
MariaDB 10.6 database
MailHog for capturing outbound emails (no real emails sent)
Live reload - edit code locally, refresh browser
Works on Apple Silicon (M1/M2/M3) via emulation
No host dependencies - everything runs in Docker

Quick Start

Option 1: Use Pre-built Docker Image (Recommended)

Clone this repository:

git clone https://github.com/Askedio/docker-whmcs.git
cd docker-whmcs

Update docker-compose.yml to use Docker Hub image:

Edit docker-compose.yml and change the whmcs service:

whmcs:
  platform: linux/amd64
  # Use pre-built image from Docker Hub
  image: gcphost/whmcs:latest
  # Comment out the build section
  # build:
  #   context: ./web
  #   dockerfile: Dockerfile

Add your WHMCS files:

# Extract your WHMCS ZIP file into the whmcs/ directory
# The whmcs/ directory should contain index.php, admin/, modules/, etc.
mkdir -p whmcs
# Then unzip your WHMCS download into ./whmcs

Start the stack:
```
docker compose up -d
```
Access WHMCS Installer:

Open http://localhost:8080/install in your browser to begin the WHMCS installation.

Database Connection Settings (use these during installation):
- Database Hostname: db
- Database Name: whmcs
- Database Username: whmcs
- Database Password: whmcs
You'll also need your WHMCS license key during the installation process.

MailHog UI: http://localhost:8025 (view captured emails)

Option 2: Build Locally

If you prefer to build the image yourself:

Clone and prepare:

git clone https://github.com/Askedio/docker-whmcs.git
cd docker-whmcs
mkdir -p whmcs
# Extract your WHMCS ZIP into ./whmcs

Build and start:

docker compose build
docker compose up -d

Access WHMCS Installer:

Open http://localhost:8080/install in your browser.

Database Connection Settings:
- Database Hostname: db
- Database Name: whmcs
- Database Username: whmcs
- Database Password: whmcs
You'll also need your WHMCS license key during installation.

Prerequisites

Docker and Docker Compose
A WHMCS license key (get a free dev license from your WHMCS account)
WHMCS installation files (download from WHMCS client area)

Important: WHMCS License Required

You need a valid WHMCS license to use this environment.

WHMCS will not run without a license key. If you have an active WHMCS license, you can usually generate a free "development" license from your WHMCS account that works with local/non-public URLs.

Platform Support

Works On All Platforms

This Docker setup works on:

Apple Silicon Macs (M1/M2/M3) - via x86_64 emulation
Intel Macs - native
Linux (x86_64/AMD64) - native
Windows (WSL2 or Docker Desktop) - native

The docker-compose.yml is configured with platform: linux/amd64 on all services, which:

Enables ionCube compatibility (ionCube only supports x86_64)
Works seamlessly on Apple Silicon via Docker's built-in emulation
Works natively on Intel/AMD systems

No special configuration needed - run docker compose up on any platform.

Local WHMCS Files Setup

You place your WHMCS files locally in the whmcs/ directory:

Download WHMCS from your WHMCS client area

Extract the ZIP file into the whmcs/ folder:

cd docker-whmcs
mkdir -p whmcs
# Extract your WHMCS ZIP so that whmcs/index.php exists

The files are bind-mounted into the container (see line 34 in docker-compose.yml: ./whmcs:/var/www/html)
Edit files locally and see changes immediately - no rebuild needed.

The whmcs/ directory is gitignored, so your WHMCS installation files stay private and aren't committed to the repository.

Project Structure

docker-whmcs/
├── docker-compose.yml    # Main compose file
├── web/
│   ├── Dockerfile        # PHP/Apache image with ionCube
│   └── php.ini          # Development PHP settings
├── whmcs/               # YOUR WHMCS FILES GO HERE (not in repo)
│   ├── index.php
│   ├── admin/
│   ├── modules/
│   └── ...
└── README.md

The `whmcs/` Directory

This directory is where you place your WHMCS application files:

Extract your WHMCS ZIP file into this directory
After installation, WHMCS will generate configuration.php here
This folder is bind-mounted, so you can edit code locally and see changes immediately

Note: The whmcs/ directory is gitignored. You must provide your own WHMCS files.

Configuration

Database Settings

Default database credentials (set in docker-compose.yml):

Host: db (use this inside WHMCS, not localhost)
Database: whmcs
Username: whmcs
Password: whmcs
Root Password: rootpass

You can change these in docker-compose.yml before starting.

MailHog Configuration

MailHog automatically captures all outbound emails. Configure WHMCS SMTP settings:

Host: mailhog
Port: 1025
No authentication
No TLS

View captured emails at: http://localhost:8025

Custom Domain (Optional)

If your dev license requires a specific domain:

Add to /etc/hosts:
```
127.0.0.1 dev.whmcs.local
```
Access WHMCS at http://dev.whmcs.local:8080
Use http://dev.whmcs.local:8080 as the System URL during installation

Development Workflow

After WHMCS is installed:

Edit code locally in ./whmcs/modules/, ./whmcs/templates/, etc.
Refresh browser - changes appear immediately (no rebuild needed)
Check MailHog at http://localhost:8025 for test emails
View logs:
```
docker compose logs -f whmcs
```

Common Development Tasks

Add an addon: Create ./whmcs/modules/addons/YourAddon/
Add a gateway: Create ./whmcs/modules/gateways/yourgateway/
Add hooks: Place files in ./whmcs/includes/hooks/
Custom templates: Edit files in ./whmcs/templates/

All changes are live - refresh your browser to see updates.

Docker Hub

Pulling the Image

The pre-built image is available on Docker Hub:

docker pull gcphost/whmcs:latest

Publishing Updates to Docker Hub

If you're the maintainer and want to publish updates:

Build for multiple platforms:

docker buildx create --use --name multiarch
docker buildx build --platform linux/amd64,linux/arm64 \
  -t gcphost/whmcs:latest \
  -t gcphost/whmcs:8.2 \
  ./web \
  --push

Or build and push manually:

docker build -t gcphost/whmcs:latest ./web
docker push gcphost/whmcs:latest

Troubleshooting

ionCube Error

If you see ionCube loader errors:

Apple Silicon: Make sure platform: linux/amd64 is set in docker-compose.yml
Verify ionCube is loaded:
```
docker compose exec whmcs php -v
```
You should see "with the ionCube PHP Loader (enabled)"

Database Connection Issues

Use db as the hostname, not localhost or 127.0.0.1
Ensure the db service is running: docker compose ps
Check database logs: docker compose logs db

Permission Issues

If you encounter file permission issues:

# Fix ownership (adjust user:group as needed)
sudo chown -R $(id -u):$(id -g) whmcs/

What's Included

PHP Extensions

pdo_mysql
gd (with JPEG support)
mbstring
intl
xml
curl
zip

PHP Configuration

Development-friendly settings:

display_errors = On
error_reporting = E_ALL
memory_limit = 256M
upload_max_filesize = 20M
max_execution_time = 120

Contributing

Contributions welcome. Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

This Docker setup is licensed under the MIT License. See LICENSE for details.

Note: WHMCS itself is proprietary software and requires a valid license from WHMCS Ltd.

Links

Website: https://askedio.github.io/docker-whmcs (GitHub Pages)
GitHub: https://github.com/Askedio/docker-whmcs
Docker Hub: https://hub.docker.com/r/gcphost/whmcs
WHMCS: https://www.whmcs.com/members/aff.php?aff=3256

Support

For issues with this Docker setup, please open an issue on GitHub.

For WHMCS licensing and support, contact WHMCS directly.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
docs		docs
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
docker-compose copy.yml		docker-compose copy.yml
docker-compose.yml		docker-compose.yml

License

Askedio/docker-whmcs

Folders and files

Latest commit

History

Repository files navigation

Docker WHMCS Development Environment

Features

Quick Start

Option 1: Use Pre-built Docker Image (Recommended)

Option 2: Build Locally

Prerequisites

Important: WHMCS License Required

Platform Support

Works On All Platforms

Local WHMCS Files Setup

Project Structure

The whmcs/ Directory

Configuration

Database Settings

MailHog Configuration

Custom Domain (Optional)

Development Workflow

Common Development Tasks

Docker Hub

Pulling the Image

Publishing Updates to Docker Hub

Troubleshooting

ionCube Error

Database Connection Issues

Permission Issues

What's Included

PHP Extensions

PHP Configuration

Contributing

License

Links

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

The `whmcs/` Directory

Packages