# Deploying to a cPanel subdomain

This walks through putting COMS on a subdomain of your existing domain
(e.g. `coms.yourdomain.com`) using cPanel's **Setup Node.js App** tool,
which most shared-hosting plans that support Node.js provide.

**Before you start:** confirm your hosting plan actually supports Node.js.
Log into cPanel and look for a **"Setup Node.js App"** icon (usually under
Software). If it's not there, your plan doesn't support Node — you'd need
to either upgrade your plan or ask your host to enable it. Node 18 or 20
support is fine; anything older may not run this app.

## How this deploys

The backend (Express) serves both the API *and* the built frontend from a
single Node process — that's what most shared-hosting Node setups expect
(one app, one port, one process), and it avoids needing a reverse proxy or
a second app slot. So there's nothing running on your server except one
Node app; the folder layout you'll upload looks like this:

```
coms.yourdomain.com/        ← your subdomain's folder
├── backend/                 ← this is the "Application root" in cPanel
│   ├── src/
│   ├── package.json
│   └── (no node_modules — cPanel installs these for you)
└── frontend/
    └── dist/                ← pre-built static files, NOT the frontend source
```

## Step 1 — Build the frontend on your own computer

Do this locally first, not on the server — cPanel's Node environment is
meant for running the app, not building it, and Vite (the build tool) is a
dev-only dependency that a production `npm install` may skip.

```bash
cd frontend
npm install
npm run build
```

This creates `frontend/dist/` — a folder of plain HTML/CSS/JS. That's the
only part of `frontend/` you'll upload; you don't need `frontend/src`,
`frontend/node_modules`, or any of the frontend's own config files on the
server.

## Step 2 — Create the subdomain

In cPanel: **Domains** → **Create A New Domain** (or **Subdomains**,
depending on your cPanel version) → enter the subdomain (e.g. `coms`) →
it'll show the full result (`coms.yourdomain.com`) and a document root
folder it's about to create. Let it use the default folder location.
Submit.

## Step 3 — Set up the Node.js app

Go to **Setup Node.js App** → **Create Application**:

- **Node.js version:** pick the latest available (18 or 20)
- **Application mode:** Production
- **Application root:** browse to the subdomain folder from Step 2, then
  into it — you want this pointing at where `backend/` will live, e.g.
  `coms.yourdomain.com/backend`
- **Application URL:** select `coms.yourdomain.com` from the dropdown
- **Application startup file:** `src/server.js`

Click **Create**. Don't run NPM install yet — there's nothing uploaded.

## Step 4 — Upload the code

Using cPanel's **File Manager** (or FTP/SFTP if you prefer):

1. Navigate to the `coms.yourdomain.com` folder created in Step 2.
2. Upload the whole `backend/` folder (source only — no `node_modules`,
   COMS's `.gitignore` already excludes it) so you end up with
   `coms.yourdomain.com/backend/src/...`.
3. Upload `frontend/dist/` (just that folder, renamed/kept as `dist`) into
   a `frontend/` folder alongside `backend/`, so you end up with
   `coms.yourdomain.com/frontend/dist/index.html`.

The two folders (`backend/` and `frontend/`) need to sit side by side —
the backend looks for the built frontend one level up from itself, at
`../../frontend/dist`.

## Step 5 — Install dependencies

Back in **Setup Node.js App**, find the app you created and click
**Run NPM Install**. This installs everything listed in
`backend/package.json` inside `backend/node_modules`.

**If it fails on `sharp`:** this package (used to render chart images for
Excel exports) ships prebuilt binaries for common platforms, but some
locked-down shared hosts block the download or lack the tools to compile
it from source. If `npm install` errors out here, check whether your host
provides an SSH/Terminal option in cPanel (under Advanced) — running
`npm install` from an actual terminal usually gives a clearer error and
more retry options than the web interface. If it genuinely can't install,
let me know and I can swap that dependency for a pure-JS alternative that
doesn't need native compilation.

## Step 6 — Start it

Still in **Setup Node.js App**, click **Restart** (or **Start**, if this
is the first run) on your application.

## Step 7 — Check it

Visit `https://coms.yourdomain.com`. You should see the COMS dashboard,
loaded with the same demo/seed data the app ships with. If you get a
blank page or an error, check the app's log file (there's a **Log** link
next to it in Setup Node.js App).

cPanel usually auto-issues a free SSL certificate for new subdomains
(AutoSSL) within a few minutes to a few hours of creation — if `https://`
doesn't work right away but `http://` does, that's why; check **SSL/TLS
Status** in cPanel if it's still not there after a day.

## A note on memory (Directory's dataset)

The Directory page's dataset (`backend/src/data/directorySchoolsFull.json`,
the full DepEd nationwide school list) is ~43MB on disk and gets parsed
into memory once when the app starts, and `db.json` itself is ~50MB+ once
that collection is seeded in. That's fine for any host with at least
512MB–1GB of RAM available to the Node process, which covers most paid
shared-hosting Node plans, but a very constrained/free tier could struggle
or get OOM-killed on startup. If the app fails to start or the log shows a
memory error, that's the first thing to check with your host.

## Carrying over your data (optional)

The app stores its data in one file: `backend/src/data/db.json`. A fresh
deploy starts with empty seed data. If you've already been using this app
locally and want that same data on the live site, upload your local
`db.json` to `coms.yourdomain.com/backend/src/data/db.json` (overwriting
the one that gets created on first run) *before* restarting the app in
Step 6, then restart.

## Making a change later

Whenever you (or I) update the app: rebuild the frontend locally
(`npm run build` again), re-upload `backend/src` (if it changed) and
`frontend/dist`, then click **Restart** in Setup Node.js App. Your
`db.json` isn't touched by any of this, so your data carries forward
automatically — just don't overwrite that one file.
