Docker n8n WHMCS module

Description

Changelog

Installation and Configuration Guide

Step-by-step instructions for installing, configuring, and setting up the Docker n8n WHMCS module, including Docker server preparation, n8n workflow setup, WHMCS integration, email templates, and product configuration.

Basic concepts and requirements

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The Docker n8n WHMCS module is part of the Docker module series by PUQcloud. It automates the deployment and management of n8n workflow automation instances using Docker containers.
Core Components
The system consists of three main components:

WHMCS Module — The core provisioning component installed on your WHMCS server

Debian 12 Server — Hosts Docker containers with n8n instances

n8n Server — Facilitates communication between WHMCS and the Docker server

Key Features

Workflow Automation — Uses n8n workflows as an API interface for Docker operations

Flexibility & Customization — All workflows and scripts are fully customizable

Prerequisites
Before proceeding with installation, review the foundational Docker module documentation:
https://doc.puq.info/books/docker-modules

WHMCS setup (install/update)

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
System requirements
The module uses ionCube encoding. Your server must meet the following requirements:

Requirement
Minimum

PHP
8.1 or 8.2

WHMCS
9+ or higher

ionCube Loader
v13 or newer (v14, v15)

Note: Module is coded with ionCube v13

To install and update a module, you must perform one and the same action.

Step 1 — Download the latest version of the module
PHP 8.2
wget http://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Docker-n8n/php82/PUQ_WHMCS-Docker-n8n-latest.zip

All versions are available via link: https://download.puqcloud.com/WHMCS/servers/PUQ_WHMCS-Docker-n8n/

Step 2 — Unzip the archive with the module
unzip PUQ_WHMCS-Docker-n8n-latest.zip

Step 3 — Copy and Replace
Copy the puqDockerN8N directory from the extracted PUQ_WHMCS-Docker-n8n archive to your WHMCS installation:
WHMCS_WEB_DIR/modules/servers/

Note: To install and update a module, you must perform one and the same action — download and copy the latest version over the existing files.

Preparing Docker server

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Docker Installation
For detailed instructions on installing and configuring Docker for PUQcloud modules, please refer to the dedicated documentation:
https://doc.puq.info/books/docker-modules/page/installing-docker-for-puqcloud-modules

Setting up n8n workflow

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The n8n workflow serves as the API interface between WHMCS and the Docker server. It receives commands from the WHMCS module and executes corresponding Docker actions via SSH.
Prerequisites

Self-hosted n8n instance or n8n cloud account
SSH access to the Docker server

Installation Options
Option 1: n8n Marketplace
Use the latest n8n Marketplace templates from the PUQcloud creator profile.
Option 2: Manual Import
Each module version includes a workflow template file (puq_docker_n8n_deploy.json) for manual import into n8n.

n8n Workflow Configuration
1. Create Credentials

Basic Auth Credential — For the Webhook API block (used by WHMCS to authenticate)

SSH Credential — For Docker server access

2. Configure Template Parameters
In the Parameters block, modify the following:

Parameter
Description

server_domain
Must match the hostname in WHMCS server settings

clients_dir
Storage location for user Docker data

mount_dir
Container disk mount point (typically unchanged)

Important: Do not modify screen_left and screen_right — these are technical parameters.

3. Docker Compose Configuration
The deploy-docker-compose element contains the Docker Compose configuration used for service creation, unlock, and update operations. This can be customized to match your requirements.
4. Nginx Configuration
The nginx element contains proxy server settings. Key sections:

main — Primary server block

main_location — Location rules for the main block

5. Bash Scripts
All bash scripts are generated within n8n and connected to the SSH element. They are fully controllable and return JSON or string responses.

Add server

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Add a new server to the system WHMCS
Navigate to: System Settings → Servers → Add New Server

Enter the correct Name and Hostname

Attention: Important Information
The hostname field represents the actual domain of the server running Docker and must match the server_domain parameter in the n8n workflow. If they do not match, communication will not function correctly.
Additionally, this domain must be configured so that all its subdomains resolve to the IP address of the server running Docker.

Module settings
In the Server Details section, select the "PUQ Docker n8n" module and enter the correct username and password for the API endpoint in the n8n workflow.

Additionally, in the Access Hash field, insert the URL of the API entry point for the n8n workflow.

Product Configuration

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Add new product to WHMCS
Navigate to: System Settings → Products/Services → Create a New Product
In the Module Settings section, select the "PUQ Docker n8n" module.

Configuration parameters

Parameter
Description

License key
A pre-purchased license key for the PUQ Docker n8n module. For the module to work correctly, the key must be active

Disk space (GB)
Allocated disk space for the Docker container in GB

CPU
CPU cores allocated for the Docker container (e.g., 0.1, 1, 2)

RAM (GB)
RAM allocated to the Docker container in GB (e.g., 0.1, 1, 2)

Main domain
The primary domain for the web interface of the application. If not set, the main domain will be taken from the hostname parameter in the server settings

Subdomain
A personal subdomain assigned to each service. If left empty or if the subdomain is already taken, it will be automatically generated

Link to instruction
URL to a guide that will be displayed in the client panel if provided

Notification at %
The percentage threshold for disk space usage that triggers a notification to the client. Set 0 to disable

Notification email template
The email template for the notification that will be sent when the threshold is reached

Supported Macros for Subdomain

Macro
Description

{user_id}
Client ID

{service_id}
Service ID

{random_digit_x}
Random number (x defines the length)

{random_letter_x}
Random letter (x defines the length)

{unixtime}
Unix timestamp

{year}
Year

{month}
Month

{day}
Day

{hour}
Hour

{minute}
Minute

{second}
Second

Default subdomain template: {user_id}-{service_id}-{second}

Metric Billing

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The Docker n8n WHMCS module supports metric billing through the standard WHMCS usage-based billing mechanism.
Available Metrics

Metric
Description

Traffic IN (GB)
Incoming network traffic in gigabytes

Traffic OUT (GB)
Outgoing network traffic in gigabytes

Configuration
To set up metric billing, follow the standard WHMCS usage-based billing configuration:
https://docs.whmcs.com/products/configuration-options/usage-billing/

Email Template — Welcome Email

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Template Details

Parameter
Value

Email Type
Product/service

Unique Name
puqDockerN8N Welcome Email

Subject
n8n Order Information

Body
Dear {$client_name},

Thank you for your order!

Product/Service: {$service_product_name}
Payment Method: {$service_payment_method}
Amount: {$service_recurring_amount}
Billing Cycle: {$service_billing_cycle}
Next Due Date: {$service_next_due_date}

The installation and setup of your n8n instance is in progress.
Within the next 4 minutes, you will be able to use your n8n instance.

Your n8n instance: https://{$service_domain}/

Note: When you log in for the first time, you will need to create an account.

Thank you for choosing our services!

{$signature}

Email Template — Update Email

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Template Details

Parameter
Value

Email Type
Product/service

Unique Name
puqDockerN8N Update Email

Subject
n8n Update Information

Body
Dear {$client_name},

Your instance is currently being updated.
You will be able to use your n8n server again within 3 minutes.

Your n8n instance: https://{$service_domain}/

Thank you for choosing our services!

{$signature}

Email Template — Disk Limit Notification

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Template Details

Parameter
Value

Email Type
Product/service

Unique Name
puqDockerN8N Notification disk limit

Subject
Disk space usage {$disk_used_percentage}%

Body
Dear {$client_name},

We would like to inform you that your n8n service ({$service_product_name})
has reached a high disk space usage level.

Service domain: {$service_domain}
Total disk space: {$disk_total}
Used disk space: {$disk_used}
Usage percentage: {$disk_used_percentage}%

We recommend reviewing your data or upgrading your plan to ensure
uninterrupted service.

Thank you for choosing our services!

{$signature}

Client Area

Overview of client-facing features available in the Docker n8n module, including the home screen, IP access control, reinstall functionality, and metric statistics.

Home Screen

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The client area home screen provides quick access to the n8n instance, real-time monitoring of resource usage, and essential management functions in one place.

Main Sections
Navigation Block

User Manual — Link to the documentation (if configured in product settings)

Connection Details

n8n Web Interface — Direct link to the n8n instance with a copy button

Change Owner Password — Button to change the n8n owner password via modal dialog

Resource Usage (Container Status)
Real-time monitoring of container resources:

Status — Current container state (Running, Stopped, Paused, etc.)

CPU Usage — CPU allocation and current load with progress bar

Memory Usage — RAM consumption with progress bar

Disk Usage — Storage usage with progress bar

Refresh — Button to reload container statistics

Application Information

Version — Installed n8n version

Users — List of active users in the n8n instance

Sidebar Navigation

Information — Main dashboard (home screen)

Restrict by IP — IP access control configuration

Reinstall — Full service reinstallation

IP Access Control

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The IP Access Control page allows clients to restrict access to their n8n instance by specifying allowed IP addresses.
Configuration

Navigate to Restrict by IP in the sidebar
Enter approved IP addresses in the text area (one IP per line)
Supports both IPv4 and IPv6 addresses
Click Save to apply changes

Important

If no IP addresses are configured, access is open to all IP addresses
Invalid IP addresses are automatically filtered out
Duplicate entries are removed

Reinstall

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The reinstall feature allows clients to fully reinstall their n8n application. This operation causes complete data loss.
Protection Against Accidental Reinstallation
To prevent accidental reinstallation, the client must:

Navigate to Reinstall in the sidebar
Type the word REINSTALL (in capital letters) in the verification field
Click the Reinstall button
Confirm the action in the dialog prompt

Warning: Reinstalling the service will completely remove all data. This action cannot be undone.

Metrics

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
If you use metrics for application traffic billing, the Metrics tab will display the usage statistics for the metrics.
Available Metrics

Metric
Description

Traffic IN (GB)
Incoming network traffic in gigabytes

Traffic OUT (GB)
Outgoing network traffic in gigabytes

Admin Area

Overview of administrative tools for managing Docker n8n services, including container management, resource monitoring, and application information.

Product Information

Docker n8n module WHMCS
Order now | Download | FAQ | n8n
Overview
The admin panel provides comprehensive tools for managing Docker n8n services, structured in two main sections with control buttons.

Module Commands

Command
Description

Create
Provision a new n8n container

Suspend
Suspend the service

Unsuspend
Reactivate a suspended service

Terminate
Remove the service completely

Change Package
Modify resource allocation

Container Start
Start the Docker container

Container Stop
Stop the Docker container

Mount Disk
Attach the container's disk to the host system

Unmount Disk
Detach the container's disk from the host system

API Connection Status
Displays the connection status to the n8n workflow API:

Green — API Connection OK

Red — API connection problem with error details

Container Status & Resource Monitoring
Real-time monitoring of the Docker container:

Metric
Description

Status
Container state (Running, Exited, Paused, etc.)

Name
Container name and ID

CPU Usage
Processor load with progress bar

Memory Usage
RAM consumption

Disk IO
Disk read/write statistics

Disk Mounted
Mounted disk usage (used/total)

Disk File
Disk image file size

Network IO
Network traffic statistics

Additional controls:

Refresh — Reload container statistics

Log — View container logs for troubleshooting

Application Information

Field
Description

Version
Installed n8n version

Users
List of users with system access

Metric Statistics
If metric billing is enabled, the admin area displays:

Metric
Description

Traffic IN (GB)
Incoming network traffic

Traffic OUT (GB)
Outgoing network traffic