This tutorial covers how to install and configure the GameCP WHMCS provisioning module. With this module, game servers are automatically created when customers purchase hosting plans through WHMCS.

What It Does

The GameCP WHMCS module connects your billing system to GameCP so that:

Game servers are automatically provisioned when orders are paid
Customers can log into GameCP directly from the WHMCS client area via Single Sign-On (SSO)
Server lifecycle operations (suspend, unsuspend, terminate) sync between WHMCS and GameCP
Live metrics (CPU, memory, player count) are displayed in the WHMCS client area
WHMCS custom fields and configurable options are automatically mapped to GameCP environment variables

Installation

1. Download the Module

Download the latest release from the GitHub repository as a ZIP file.

2. Upload to WHMCS

Extract the ZIP and upload the contents to your WHMCS server directory:

/path/to/whmcs/modules/servers/gamecp/

3. Verify Files

The following files should be present in the directory:

File	Purpose
`gamecp.php`	Core module logic
`clientarea.tpl`	Client area management interface
`logo.png`	Module icon for the WHMCS interface
`whmcs.json`	Module metadata for the WHMCS marketplace

4. Set Permissions

Ensure the directory and files are readable by your web server user (usually www-data or apache).

Server Configuration

Before creating products, you need to tell WHMCS how to connect to your GameCP instance.

Adding a GameCP Server

Go to Setup > Products/Services > Servers > Add New Server
Fill in the following:

Field	Value
Name	Any descriptive name (e.g., "GameCP Production")
Hostname	Your GameCP domain (e.g., `app.gamecp.com`)
Type	Select gamecp from the dropdown
Username	Leave blank
Password	Leave blank
Access Hash	Your GameCP API key

The protocol (https://) is added automatically if not specified.

Generating an API Key

Log into GameCP as an admin
Go to Settings > API Keys
Click Create API Key
Copy the generated key (it starts with gcp_)
Paste it into the Access Hash field in WHMCS

Server Groups (Recommended)

Create a Server Group containing your GameCP server. This enables load balancing across multiple GameCP instances and is the recommended setup. The module is designed to work with server groups and automatically resolves the correct API credentials.

Product Configuration

Creating a Game Hosting Product

Go to Setup > Products/Services > Products/Services > Create New Product
Under the Module Settings tab:
- Module Name: Select GameCP
- Server Group: Select your GameCP server group

Module Options

The module exposes four configuration options on each product:

Option	Field	Description
Game Config ID	`configoption1`	The MongoDB ObjectId of the game template in GameCP. Find this in the game config editor URL or the game library.
Node ID	`configoption2`	Optional. Specific node ID to deploy on. Leave empty for automatic node selection.
Location	`configoption3`	Optional. Geographic location preference for node selection.
Auto Deploy	`configoption4`	Whether to automatically install the game after server creation. Disable for games that need user configuration first (e.g., Steam Guard tokens).

Finding the Game Config ID

Open the game config editor in GameCP. The Game Config ID is the MongoDB ObjectId shown in the URL when editing a game config:

https://app.gamecp.com/games/67a1b2c3d4e5f67890abcdef
                              └────── This is the ID ──────┘

Environment Variable Mapping

One of the most powerful features of the module is automatic environment variable mapping. This lets you use WHMCS custom fields and configurable options to control game server settings.

How It Works

Create a Custom Field or Configurable Option in WHMCS with a friendly name
GameCP automatically matches it to the game template's environment variable
The value is applied when the server is provisioned

Matching Rules

The matching is case-insensitive and space/underscore normalized:

WHMCS Field Name	Matches GameCP Env Var
`Server Name`	`SERVER_NAME`
`Max Memory`	`MAX_MEMORY`
`Max Players`	`MAX_PLAYERS`
`RCON Password`	`RCON_PASSWORD`
`server-name`	`SERVER_NAME`

What Happens When There's No Match

Matched variables: The WHMCS value overrides the template default
Unmatched variables: A new custom environment variable is created with the user editable flag set to false (billing-controlled)

Reserved Field Names

These field names are used internally for provisioning and are not passed as environment variables:

Game Config ID
GameCP Server ID
GameCP Server Name
Node ID
Location

Example: Minecraft with Custom Memory

Create a Configurable Option Group in WHMCS:
- Name: Minecraft Options
- Assign to your Minecraft product
Add a Configurable Option:
- Name: Max Memory
- Type: Dropdown
- Options: 1024|1GB, 2048|2GB, 4096|4GB
When a customer orders with 2GB selected:
- WHMCS sends "Max Memory": "2048"
- GameCP matches it to MAX_MEMORY in the template
- The server starts with the 2GB memory limit

Server Naming

The server name is determined in this order:

WHMCS Domain field — if your product uses the domain field, that value is used
Auto-generated — falls back to Game Server #123 (using the WHMCS service ID)

Customers can rename their server in the GameCP panel after provisioning.

Order Flow

When a customer purchases a GameCP product, here's what happens automatically:

Payment processed — the order is activated in WHMCS
User creation — the module creates (or finds) the customer's account in GameCP using their email and a bcrypt-hashed password
Server provisioning — a game server is created with:
- The game template specified by the Game Config ID
- Automatic port assignment
- Optimal node selection (or the specified node)
- Any environment variable overrides from custom fields
Server ID stored — the GameCP server ID is saved to the WHMCS dedicatedip field for reliable retrieval
Customer notified — WHMCS sends the standard welcome email with server details

Lifecycle Operations

Suspend (Stop Server)

When a service is suspended in WHMCS (e.g., overdue invoice), the module sends a stop command to GameCP. The server is stopped but all data is preserved.

Unsuspend (Start Server)

When a service is unsuspended (e.g., invoice paid), the module sends a start command. The server resumes with all data intact.

Terminate (Delete Server)

When a service is terminated, the module sends a delete request to GameCP. The server and all associated data are permanently removed.

Install / Uninstall

The client area also provides buttons for:

Install — deploys the game files on an existing (configured) server
Uninstall — removes game files but keeps the server record

These are useful when Auto Deploy is disabled and the customer needs to configure settings before installation.

Single Sign-On (SSO)

The module provides seamless SSO integration:

Client Area: Customers click "Login to GameCP" and are redirected directly into their GameCP dashboard with automatic authentication
Admin Area: Admins can SSO into any customer's GameCP session for support

The SSO flow works by:

WHMCS calls the GameCP SSO token API with the customer's email
GameCP generates a one-time login URL with a JWT token
The customer is redirected to GameCP and automatically logged in
If the server ID is known, they land directly on their game server page

Client Area

The WHMCS client area page for a GameCP service displays:

Server status — running, stopped, installing, configured, or error states with color-coded badges
Online players — current and maximum player count (when available)
Current map — the active game map (when supported)
Resource usage — CPU percentage, memory usage (MB), and disk usage (MB)
Action buttons:
- Install Game Server — appears when the server is in a configurable state
- Uninstall Game Server — appears when a game is installed
- Login to GameCP — always visible, triggers SSO

Debug Logging

The module logs all operations to the WHMCS Module Log for troubleshooting:

Log Action	What It Logs
`CreateAccount_Debug`	Full parameter dump during provisioning
`ServerLookup_*`	Database credential lookups for server groups
`ApiCall`	All API requests with the full curl command

To view logs, go to Utilities > Logs > Module Log in the WHMCS admin panel.

Troubleshooting

Server Not Created

Verify the API Key is correct and starts with gcp_
Check that the Game Config ID is a valid MongoDB ObjectId
Ensure the GameCP server is reachable from the WHMCS server
Review the Module Log for detailed error messages

SSO Not Working

Confirm the customer's email matches between WHMCS and GameCP
Check that the hostname is set correctly on the WHMCS server entry
The SSO falls back to a plain redirect if the token API fails

Environment Variables Not Applied

Check the field name spelling — it must match the environment variable label (case-insensitive)
Reserved field names (Game Config ID, Node ID, etc.) are excluded from mapping
Review the Module Log for the configOverrides payload

Manual Setup Alert

WHMCS Integration