# ProSensia Cloud — Namecheap Deployment Guide

## Prerequisites
- Namecheap Starter Plus (or higher) hosting
- cPanel access
- Node.js available (Namecheap supports Node.js via Phusion Passenger)
- MySQL database created in cPanel

---

## Step 1 — Create MySQL Database (cPanel)

1. Login to cPanel → **MySQL Databases**
2. Create database: `prosensia_db`
3. Create user: `prosensia_user` with a strong password
4. Add user to database → grant **All Privileges**
5. Note down: hostname (`localhost`), database name, username, password

---

## Step 2 — Set Up HiveMQ Cloud MQTT Broker (Free)

1. Go to **console.hivemq.cloud** → Create free account
2. Create a free cluster (serverless tier — 100 connections, TLS included)
3. Under **Access Management** → create credentials:
   - Username: `prosensia`
   - Password: (strong password)
4. Note the **Cluster URL**: `xxxx.s1.eu.hivemq.cloud`
5. Your MQTT URL will be: `mqtts://prosensia:PASSWORD@xxxx.s1.eu.hivemq.cloud:8883`

---

## Step 3 — Upload Files

### Option A: cPanel File Manager
1. Zip the entire `NamecheapVersion/` folder contents
2. Upload to your domain's `public_html` or a subdirectory (e.g., `public_html/app/`)
3. Extract in place

### Option B: FTP/SFTP
```
Host: your-domain.com
Protocol: SFTP
Port: 22
```
Upload contents of `NamecheapVersion/` to desired directory.

---

## Step 4 — Configure Environment Variables

1. In cPanel → **Node.js** app setup, or create a `.env` file in the `server/` folder:

```env
NODE_ENV=production

# MySQL (from Step 1)
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_cpanel_username_prosensia_user
DB_PASS=YourStrongPassword123
DB_NAME=your_cpanel_username_prosensia_db

# HiveMQ Cloud (from Step 2)
MQTT_BROKER_URL=mqtts://prosensia:PASSWORD@xxxx.s1.eu.hivemq.cloud:8883
MQTT_USERNAME=prosensia
MQTT_PASSWORD=YourMqttPassword

# Session
SESSION_SECRET=generate-64-char-random-string-here

# App
PORT=3000
DATA_DIR=/home/your_cpanel_username/data
```

**Generate SESSION_SECRET** (run in any terminal):
```bash
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
```

---

## Step 5 — Create MySQL Tables

1. In cPanel → **phpMyAdmin** → Select your database
2. Click **SQL** tab
3. Open `server/schema.sql` from this folder
4. Paste the entire contents and click **Go**

All tables will be created automatically.

---

## Step 6 — Set Up Node.js App in cPanel

1. cPanel → **Setup Node.js App**
2. Click **Create Application**
3. Settings:
   - **Node.js version**: 18.x or 20.x
   - **Application mode**: Production
   - **Application root**: `public_html/app/server` (wherever you uploaded)
   - **Application URL**: your domain or subdomain
   - **Application startup file**: `index.js`
4. Click **Create**
5. In the app panel → click **Run NPM Install**
6. Click **Start App**

---

## Step 7 — Configure ESP32 Devices

Update each ESP32 device firmware `.env` / config with:
```
MQTT_BROKER=xxxx.s1.eu.hivemq.cloud
MQTT_PORT=8883
MQTT_USER=prosensia
MQTT_PASS=YourMqttPassword
MQTT_USE_TLS=true
SERVER_URL=https://your-domain.com
```

Or use the ProSensia portal's **Device Settings** → **Provision** to push these over-the-air.

---

## Step 8 — Initial Admin Setup

1. Visit `https://your-domain.com`
2. Go to `/setup` to create your admin account
3. Enter activation code from ProSensia to activate the license
4. Start pairing devices

---

## Subdomain Setup (Recommended)

For a clean URL like `app.yourdomain.com`:

1. cPanel → **Subdomains** → Create `app.yourdomain.com`
2. Point document root to `public_html/app`
3. Set the Node.js app URL to `app.yourdomain.com`
4. cPanel → **SSL/TLS** → Install Let's Encrypt for the subdomain

---

## Troubleshooting

### App won't start
- Check Node.js version is 18+
- Verify `.env` file has no extra spaces around `=`
- Check cPanel error logs: **Logs** → **Error Log**
- Run `npm install` again from cPanel Node.js panel

### MySQL connection refused
- Confirm DB_HOST is `localhost` (not an IP) for Namecheap
- Double-check username format: `cpanelusername_dbusername`
- Verify user has all privileges on the database

### MQTT not connecting
- Test broker URL in HiveMQ console's built-in client
- Confirm `mqtts://` (not `mqtt://`) for TLS
- Port `8883` (not 1883) for TLS

### ESP32 devices not reporting
- Ensure device firmware has correct MQTT broker URL
- Check HiveMQ console → Connected clients
- Use Device Settings → Test MQTT in the app

---

## Backup

- Automated JSON backups run daily (stored in `DATA_DIR/backups/`)
- Manual backup: Dashboard → Settings → Backup → Run Now
- Download backups from the Backup page

---

## Performance Tips for Shared Hosting

The server is already optimized for shared hosting:
- **MySQL connection pooling** (10 connections max)
- **Gzip compression** on all API responses
- **Rate limiting** (600 req/min ingest, 300 req/min general)
- **express-mysql-session** for scalable session storage
- Schedule engine and MQTT are event-driven (no polling loops)

If CPU limits are hit, reduce telemetry frequency on ESP32 devices
(default is every 10s; 30s is fine for most deployments).