# Deploying Omnio Suite on cPanel

This package is self-contained — **no `npm install` is needed on the server**. The server bundle includes all dependencies.

## Database

**None needed for this phase.** Mail is read live over IMAP (it stays in the mailboxes on your server), sign-in credentials are AES-256-GCM encrypted into the user's browser cookie (the app server stores no state), and Docs/Sheets/Keep persist in the browser. Phase 2 (caching, search, settings) will use MySQL, which cPanel already provides.

## Requirements

- cPanel hosting with **"Setup Node.js App"** (CloudLinux / Passenger). Node **18+** (20 recommended).
- A mailbox on the same server (or any IMAP server reachable from it) to test with.

## WHM / server-admin setup (one-time, if "Setup Node.js App" is missing)

Log into cPanel for the account first and look for **Software → Setup Node.js App**. If it's already there, skip this section entirely.

If it's missing, in the **WHM terminal** (as root):

1. Check whether the server runs CloudLinux:
   ```
   cat /etc/os-release
   ```

2. **CloudLinux servers** — enable the Node.js Selector:
   ```
   yum install -y lvemanager lve-utils alt-nodejs20
   ```
   Then WHM → **CloudLinux LVE Manager → Options → Node.js** → enable version 20. "Setup Node.js App" appears in every cPanel account.

3. **Plain AlmaLinux/Rocky WHM (no CloudLinux)** — install Passenger + Node via EasyApache packages:
   ```
   yum install -y ea-ruby27-mod_passenger ea-nodejs20
   ```
   Then use WHM → **Software → Application Manager** to register the app (same fields as the cPanel flow below: application root, URL, `app.js`).

### Why this cannot affect your other websites

- Installing these packages adds an Apache module and a Node runtime — it does **not** change any existing site's configuration. Apache does a graceful restart (a few seconds, no dropped connections).
- The app runs **as the cPanel account's own user**, inside that account's home directory, counted against that account's CloudLinux resource limits (LVE). It cannot touch other accounts.
- Passenger only activates for the one URL you assign the app to. Every other domain and subdomain is served exactly as before.
- No ports are opened: Passenger proxies the app internally through Apache on the normal 80/443.
- Uninstalling is equally clean: delete the app in the UI, remove the folder.

### Practical tips

- Put the app on a **dedicated subdomain** like `app.omnio.email` or `webmail.omnio.email`. Avoid `mail.omnio.email` — cPanel reserves that hostname for mail service DNS, and reusing it can break mail client autodiscovery.
- Create the subdomain in cPanel → Domains first, run AutoSSL so it has HTTPS, then point the Node.js app's Application URL at it.
- Generate the session secret on the server: run `openssl rand -hex 32` in the terminal and paste the output into the `SESSION_SECRET` environment variable.

## Steps

1. **Upload & extract**
   - In cPanel → File Manager, create a folder outside `public_html`, e.g. `~/omnio`.
   - Upload `omnio-suite-cpanel.zip` into it and extract.

2. **Create the Node.js app**
   - cPanel → **Setup Node.js App** → *Create Application*:
     - Node.js version: 18 or 20
     - Application mode: **Production**
     - Application root: `omnio` (the folder you extracted into)
     - Application URL: choose the domain/subdomain (e.g. `mail.yourdomain.com`)
     - Application startup file: **`app.js`**
   - Click *Create*.

3. **Set environment variables** (same screen, "Environment variables")
   - `SESSION_SECRET` = a long random string (run `openssl rand -hex 32` locally, or mash the keyboard for 40+ chars). **Required** — it encrypts mailbox credentials in the session cookie.
   - `GEMINI_API_KEY` = your Gemini key (optional; AI features return simulated answers without it).

4. **Restart the app** and open the Application URL.

5. **Sign in with a real mailbox**
   - First create the mailbox in cPanel → **Email Accounts** (e.g. `komail@omnio.email` + a password) if it doesn't exist yet.
   - Open the app → *Launch Omnio Webmail* (or *Sign in*). The sign-in screen appears.
   - Enter the full email address and its mailbox password — that's the login; no separate Omnio signup exists.
   - The IMAP server is auto-detected as `mail.<your domain>`. If that doesn't resolve, expand **Server settings** and use `localhost` (when the mailbox lives on the same server — also the fastest option). IMAP port `993` (or `143` for localhost), SMTP `465` (or `25`/`587`).
   - Sign in. Your real inbox loads; opening, starring, deleting, and sending all operate on the actual mailbox. *Explore the demo workspace* is available for showing the product without a mailbox.

## How it works / security notes

- **Zero storage**: mail is fetched live over IMAP per request; nothing is stored server-side. Credentials are AES-256-GCM encrypted into an httpOnly cookie — the server keeps no session state.
- **Use HTTPS** for the application URL (AutoSSL is fine). Credentials transit only between the browser and your server.
- Sending uses your server's own SMTP (port 465, falling back to 587), so SPF/DKIM/deliverability are whatever your domain already has.
- TLS certificate validation to the IMAP host is relaxed (`rejectUnauthorized: false`) because shared hosts commonly serve `mail.<domain>` with the server-hostname certificate. Tighten this for production once hostnames are set up properly.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| "IMAP connection failed" | Check host/port; try `localhost` + port 143 with SSL off if the mailbox is on the same box; verify the mailbox password in cPanel → Email Accounts. |
| App won't start | Confirm startup file is `app.js` and mode is Production; check the app's `stderr.log` in the application root. |
| Sending fails | Some hosts block outbound 465/587 for other servers — if the mailbox is local, set SMTP host to `localhost`. |
| Blank page | Make sure the `dist/` folder uploaded completely (it contains `index.html` + assets). |

## Updating

Re-run `npm run package` locally, upload the new zip, extract over the old files, and hit *Restart* in Setup Node.js App.
