# WHMCS installation

Install the HexaHost GameCloud provisioning and addon modules on WHMCS 8.x+.

## Prerequisites

- WHMCS with SSL (HTTPS admin and client area)
- GameCloud control plane deployed (`deploy/compose/compose.prod.yml`)
- `BILLING_PROVIDER=whmcs` on GameCloud
- Matching credentials prepared (`WHMCS_INTEGRATION_ID`, `WHMCS_API_SECRET`)

## Package contents

Source tree: `integrations/whmcs/`

| Component | WHMCS path |
|-----------|------------|
| Server module | `/modules/servers/hexagamecloud/` |
| Addon module | `/modules/addons/hexagamecloud/` |
| Hooks | `/includes/hooks/hexagamecloud.php` |

Build a distributable ZIP:

```bash
cd integrations/whmcs/packaging
./build-package.sh
```

## Installation steps

### 1. Copy server module

```bash
cp -r integrations/whmcs/modules/servers/hexagamecloud /path/to/whmcs/modules/servers/
```

**Setup → Products/Services → Servers → Create New Server**

- Type: **HexaHost GameCloud**
- Hostname: `api.example.net` (GameCloud API host only — no path)
- Username / Password: leave empty (credentials are per-product module settings)

### 2. Copy addon module

```bash
cp -r integrations/whmcs/modules/addons/hexagamecloud /path/to/whmcs/modules/addons/
```

**Setup → Addon Modules → HexaHost GameCloud → Activate**

Configure global settings — see [configuration](configuration.md).

### 3. Install hooks

```bash
cp integrations/whmcs/hooks/hexagamecloud.php /path/to/whmcs/includes/hooks/
```

Hooks enable daily event polling and optional auto-reconciliation.

### 4. Configure GameCloud

On the control plane `.env.prod`:

```env
BILLING_PROVIDER=whmcs
WHMCS_INTEGRATION_ID=prod-whmcs-main
WHMCS_API_SECRET=<same-as-addon>
INTEGRATION_MTLS_ENABLED=true
```

Restart API after changes.

### 5. Verify connectivity

In WHMCS: **Addons → HexaHost GameCloud → Dashboard**

Expected: green health, catalog plan count, zero pending critical events.

## File permissions

WHMCS web user must read module PHP files. Do not make `lib/` or `templates/` web-writable.

## Multi-environment

Use separate `WHMCS_INTEGRATION_ID` values for staging and production GameCloud installations. Never point staging WHMCS at production GameCloud.

## Related

- [Configuration](configuration.md)
- [Products](products.md)
- [Security](security.md)
- [Addon module](../addon-module.md)