# cPanel deployment — HR Expo 2026 API

This bundle is intended to be extracted directly into the cPanel Node.js
application root. After extraction, `app.js` and `package.json` must be in
that folder; do not leave them inside an additional nested directory.

## 1. Create the cPanel Node.js application

In **cPanel → Setup Node.js App**:

1. Select Node.js 20 or a newer available LTS version. The application was
   verified with Node.js 22.
2. Set the application root to the folder containing `app.js`.
3. Set the startup file to `app.js`.
4. Set the application to production mode.
5. Use the port assigned by cPanel/Passenger. The application reads it from
   `PORT`.

The bundle contains production dependencies in `node_modules`. If cPanel
requires dependencies to be rebuilt, run `npm install --omit=dev` from the
application root.

## 2. Configure environment variables

Copy `.env.example` to `.env` only if the cPanel Node.js application does not
provide environment variables through its interface. Replace every placeholder
and keep `.env` outside source control.

Required values include:

- `DB_HOST`, `DB_USER`, `DB_PASS`, and `DB_DATABASE`
- `SECRETKEY` — a long, random production secret
- `MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURE`, `MAIL_USER`, and `MAIL_PASS`
- `BADGE_QR_BASE_URL` — the public URL handled by the frontend/profile page
- `HREX_FRONTEND_ORIGIN` — the allowed frontend origin or comma-separated list

The HREX defaults are already in `.env.example`, including:

- `EVENT_NAME=HR Expo 2026`
- `EVENT_START_DATE=2026-09-22`
- `EVENT_END_DATE=2026-09-23`
- `EVENT_LOCATION=SMX Convention Center Manila, Mall of Asia Complex, Pasay City`
- `MAIL_FROM_NAME=HR Expo`
- `SUPPORT_EMAIL=operations@aftcorpph.com`

Do not copy a production `.env` from an older archive. It may contain secrets
and old Coconut event settings.

## 3. Prepare the database

Create the target MySQL/MariaDB database and user in cPanel, grant the user all
required privileges on that database, and then import `sql/schema.sql` through
phpMyAdmin for a new database.

For an existing database:

1. Make a verified backup first.
2. Apply `sql/migrations/20260824_registration_labels_and_active_email.sql`
   only if the database does not already contain `registrants.normalizedEmail`.
3. Apply `sql/migrations/20260907_hrex_2026_registration_form.sql` to update
   the active Purpose of Visit field and add the required privacy-consent
   checkbox without deleting registration, QR, badge, attendance, or email-log
   records.

The application calls `connection.sync()` at startup for missing tables, but
the schema and migrations above are still required for the HREX form and for
safe upgrades of an existing production database.

## 4. Create staff accounts

After the database connection variables are available, run the included seed
script from the application root with strong passwords:

```bash
node scripts/seed-staff.js admin <strong-password> admin "Admin User"
node scripts/seed-staff.js badge_printer <strong-password> badge_printer "Counter 1"
node scripts/seed-staff.js scanner <strong-password> scanner "Entrance Scanner 1"
```

The script creates an account only when that username does not already exist.

## 5. Start and verify

Restart the cPanel Node.js application after setting environment variables and
database contents. Check the application health endpoint:

```bash
curl https://your-api-host.example/
```

The expected response is a successful JSON response identifying the HR Expo
2026 API. The existing API paths, roles, registration sources, QR workflows,
resend behavior, badge issuance, attendance behavior, and Excel import route
remain unchanged.

## Security exclusions

The deployment zip intentionally does not contain `.env`, database dumps,
tests, or development-only verification files. Never upload real database
exports or SMTP/JWT credentials to source control or share them in the zip.
