# cPanel / CloudLinux deployment for wa.modulecrafter.com

## Recommended layout

```text
/home/CPANEL_USER/
  public_html/
  wa.modulecrafter.com/        <-- Node application root
    src/server.js              <-- cPanel startup file
    package.json
    .env                       <-- private
    src/
    views/
    public/
    migrations/
    scripts/
    storage/
      sessions/                <-- private linked-device auth state
      logs/
```

The subdomain can remain outside `public_html`. Express exposes only `public/` as static content.

## New install

### 1. cPanel requirements

Use CloudLinux **Setup Node.js App** (or Passenger/Application Manager) with Node.js 20 or newer.

Linked-device mode needs a persistent Node process and outbound socket connections. If a shared host repeatedly sleeps/kills persistent connections, use a VPS for the QR worker/app.

### 2. DNS/SSL

Create:

```text
wa.modulecrafter.com
```

Enable AutoSSL and set:

```dotenv
APP_URL=https://wa.modulecrafter.com
COOKIE_SECURE=true
TRUST_PROXY=1
```

### 3. MySQL

Create the database/user with cPanel MySQL Database Wizard and grant the user access to the database.

Use your actual cPanel-prefixed values:

```dotenv
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=cpuser_modulecrafter_wa
DB_USERNAME=cpuser_modulecrafter_wa
DB_PASSWORD=...
```

### 4. Upload and `.env`

Upload this package into:

```text
/home/CPANEL_USER/wa.modulecrafter.com
```

Create `.env` from `.env.example`. Generate strong values for at least:

```dotenv
APP_KEY=...
PROVISIONING_SECRET=...
DB_PASSWORD=...
```

Generate secrets with:

```bash
openssl rand -hex 32
```

Keep `APP_KEY` stable. It is required to decrypt stored provider credentials.

Recommended permissions:

```bash
chmod 600 .env
chmod 700 storage storage/sessions storage/logs
```

### 5. Setup Node.js App

Use:

```text
Node.js version:         20+
Application mode:        Production
Application root:        wa.modulecrafter.com
Application URL:         https://wa.modulecrafter.com
Application startup file: src/server.js
```

CloudLinux may inject `PORT`; the gateway accepts that automatically.

### 6. Terminal initialization

Use the exact activation command shown by cPanel. A common example is:

```bash
source ~/nodevenv/wa.modulecrafter.com/20/bin/activate
cd ~/wa.modulecrafter.com
npm install
npm run migrate
npm run create-admin -- --email=admin@example.com
```

The create-admin script prints a generated password when one was not supplied. Store it securely and do not paste it into tickets/chat logs.

Restart the Node app from cPanel.

### 7. Health check

Open:

```text
https://wa.modulecrafter.com/healthz
```

Expected:

```json
{"ok":true,"app":"ModuleCrafter WA","version":"4.0.0"}
```

### 8. First functional checks

1. Login to the gateway.
2. Create a Linked Device channel.
3. Scan QR or use phone pairing.
4. Send a test message.
5. Restart the Node app and confirm the linked session restores.
6. Open **Platform Admin -> Plans** and confirm the commercial plan seeds exist.

## Existing v1 install

Use [`UPGRADE_V1_TO_V2.md`](UPGRADE_V1_TO_V2.md). The important rule is: **preserve `.env` and `storage/sessions`**.

## WHMCS seller integration

After the gateway is healthy, install:

```text
integrations/whmcs/provisioning_module/modules/servers/modulecrafterwa/
```

into your seller WHMCS and use the same `PROVISIONING_SECRET` configured in `.env`.

Do not put `PROVISIONING_SECRET` into any customer-facing WHMCS addon.

## Queue worker behavior

The web application includes a conservative in-process worker. Settings:

```dotenv
MESSAGE_WORKER_INTERVAL_MS=1500
MESSAGE_WORKER_CONCURRENCY=5
MESSAGE_MAX_ATTEMPTS=4
QR_SEND_MIN_INTERVAL_MS=1000
```

There is also:

```bash
npm run worker
```

for bounded queue draining, useful as a fallback cron if a specific shared host pauses timers. Do not run many overlapping workers on low-resource hosting.

## Official Meta Cloud API

Create an Official channel and configure WABA ID, Phone Number ID, access token, webhook verify token, and preferably App Secret.

Each channel has its own callback:

```text
https://wa.modulecrafter.com/webhooks/meta/CHANNEL_ID
```

Configure that callback in the Meta app and subscribe to the required WhatsApp webhook fields. Meta policy/consent/template/quality/throughput rules still apply.

## Troubleshooting

Check:

- cPanel Passenger/Node logs
- MySQL credentials and privileges
- `.env` values in the application root
- SSL validity
- `storage/sessions` write permissions
- outbound HTTPS to Meta
- persistent socket support for Linked Device

Never expose `.env`, API tokens, provisioning secret, Meta credentials, or session files while troubleshooting.

## v4 upgrade note

For an existing v3 installation, use `docs/UPGRADE_V3_TO_V4.md`. Preserve `.env`, `storage/sessions`, and your database. After replacing code run:

```bash
source ~/nodevenv/wa.modulecrafter.com/20/bin/activate
cd ~/wa.modulecrafter.com
npm install
npm run migrate
npm test
```

Restart the CloudLinux application and verify `/healthz` reports `4.0.0`. Replace the seller provisioning module and customer Sender addon with their v4 folders so they use the v4 contracts and worldwide phone normalization.

For extra privacy on cPanel, keep the included `storage/.htaccess`, set `.env` to restrictive permissions, and consider configuring `MEDIA_STORAGE_ROOT`/`QR_SESSION_ROOT` to directories outside the subdomain document root.