ATTENDANCE DASHBOARD — NAMECHEAP cPanel DEPLOYMENT
=================================================

This folder is a complete Node.js application:

  server.js            the app
  .next/               build output + static chunks
  node_modules/        already installed (no npm install needed)
  public/              brand assets and fonts
  schema.sql           the MySQL tables (import once, in step 2)

It needs no build step and no SSH. Everything below is done from cPanel.

Sizes: about 26 MB unpacked, 6 MB zipped, roughly 1600 files and folders. Check
your plan's disk and inode limits if you are close to them.


WHAT YOU NEED BEFORE STARTING
-----------------------------
1. A Namecheap plan with "Setup Node.js App" (Node.js Selector) and MySQL.
2. A subdomain for this app, e.g. attendance.fakhris.com. Use a dedicated
   subdomain: the app owns the whole document root.
3. The terminal's serial number, if you plan to use ADMS push (step 7).


STEP 1 — Create the database
----------------------------
cPanel -> MySQL Databases

  a) New Database:            attendance
     Full name becomes:       YOURCPUSER_attendance     (note it down)
  b) MySQL Users -> Add New User
     Username:                attendance
     Password:                generate a strong one, copy it somewhere safe
     Full username becomes:   YOURCPUSER_attendance     (note it down)
  c) Add User To Database:    select the user and the database
     Privileges:              ALL PRIVILEGES

You now have three values: database name, username, password. All three go into
DATABASE_URL in step 5. On cPanel the host is always `localhost`.


STEP 2 — Import the tables
--------------------------
cPanel -> phpMyAdmin

  a) Left sidebar: click YOURCPUSER_attendance (do not click "information_schema")
  b) Top tab: Import
  c) Choose File: schema.sql  (inside this folder)
  d) Character set: utf-8
  e) Go

Expected result: "Import has been successfully finished".

Check that five tables exist: admin_users, attendance_logs, devices, employees,
ingest_batches. The file uses CREATE TABLE IF NOT EXISTS, so it is safe to run a
second time — but it never drops data, so it cannot repair a damaged table.

If employee names later show as ??? in the app, the tables were created with a
latin1 charset. Check in phpMyAdmin -> Operations that the database collation is
utf8mb4_unicode_ci, and re-create the database with that collation if not.


STEP 3 — Create the Node.js application
---------------------------------------
cPanel -> Setup Node.js App -> Create Application

  Node.js version          26.x (this build was made with Node 26.12)
                           If your plan predates 26, 22.x also runs it.
  Application mode         Production
  Application root         attendance
  Application URL          attendance.fakhris.com
  Application startup file server.js

Click Create.

Application root is a folder in your home directory, NOT public_html. cPanel
creates it and wires the subdomain to it. The app's files are never served
directly as static files, which is what you want.


STEP 4 — Upload the code
------------------------
cPanel -> File Manager

  a) Go to /home/YOURCPUSER/attendance  (the folder from step 3)
  b) Upload fakhris-attendance.zip
  c) Right-click the zip -> Extract -> Extract Files
  d) Delete the zip afterwards

IMPORTANT — the folder must not be nested. After extracting, this must be true:

  /home/YOURCPUSER/attendance/server.js
  /home/YOURCPUSER/attendance/.next/
  /home/YOURCPUSER/attendance/node_modules/

Mac and Windows both default to wrapping the archive in an extra folder. If you
see /home/YOURCPUSER/attendance/fakhris-attendance/server.js, open that inner
folder, select everything, Move it up one level into `attendance`, then delete
the empty folder.

Keep the `tmp` folder that cPanel creates in the app root; it is used to restart
the app.


STEP 5 — Environment variables
------------------------------
cPanel -> Setup Node.js App -> your app -> Environment variables

Add each row below. This bundle does not read .env files, so the panel is the
only place these live. After adding them, press Restart.

  HOSTNAME
    0.0.0.0
    Required. cPanel sets HOSTNAME to the server's own name, and the app would
    try to bind to that address and fail with a 503. This pins it.

  ADMIN_EMAIL
    you@fakhris.com
    The single login account.

  ADMIN_PASSWORD_HASH
    scrypt$........
    Generate it on your own machine:  npm run hash -- 'your-password'
    (on Windows:  npm run hash -- "your-password")
    Copy the whole value after ADMIN_PASSWORD_HASH=. It contains $ characters;
    that is normal, paste it verbatim. The password itself is never stored.

  SESSION_SECRET
    a long random string
    Generate:  openssl rand -base64 32
    Changing this later signs everybody out. That is also how you force a
    sign-out if a laptop is lost.

  DATABASE_URL
    mysql://YOURCPUSER_attendance:DB-PASSWORD@localhost:3306/YOURCPUSER_attendance
    Replace both names and the password with the values from step 1.
    If the password contains @ : / or ?, URL-encode it (@ becomes %40).

  INGEST_KEY
    long random string
    Only needed for the LAN collector (step 8). Not needed for ADMS push or for
    CSV import.

  ADMS_SERIALS
    MB20VL-001
    Optional but recommended: the comma-separated list of device serials allowed
    to push. Empty means any device that knows the URL can post punches. Fill it
    in after step 7 has proved the device works.

  OFFICE_TIMEZONE          Asia/Dhaka
  OFFICE_UTC_OFFSET_MINUTES 360
  OFFICE_START             09:00
  OFFICE_END               17:00
  GRACE_MINUTES            10
  OUT_GRACE_MINUTES        15

The last six have defaults matching the current shift, so they can be omitted.
Set them explicitly if the shift ever changes. OFFICE_UTC_OFFSET_MINUTES must
match the timezone: Dhaka is +360 all year, so no daylight saving is involved.


STEP 6 — Restart and check
--------------------------
cPanel -> Setup Node.js App -> Restart (or create an empty file named
`restart.txt` inside the app's tmp folder).

Open https://attendance.fakhris.com/login — the branded login page should load
with the hero photograph.

Then check that the app is reading the database rather than demo data: sign in.
An empty register (no names) means the database is connected. If you see sample
employees such as "Rahim Uddin", DATABASE_URL is not being applied — recheck
step 5 and restart.

Next: sign in, open Employees -> Import CSV, and load the staff list
(PIN, Name, Department). Punches for PINs that do not exist still arrive; they
show up as "Unknown PIN" in the punch log and can be named later.


STEP 7 — Point the terminal at the app (ADMS push)
--------------------------------------------------
This is the preferred path: the device calls out to the website, so no port
forwarding and no office PC is involved.

On the MB20 VL:  Menu -> Comm -> Cloud Server Setting (or ADMS / WebServer)

  Server Address     attendance.fakhris.com
  Server Port        80
  Enable Domain Name On
  Server Path        /iclock

Leave the proxy settings empty. Save, then reboot the terminal or wait for its
next push (the app asks for one every 10 seconds during the handshake).

Verify from any computer:

  curl "https://attendance.fakhris.com/iclock/cdata?SN=MB20VL-001&options=all"

You should get a short settings block starting with
"GET OPTION FROM: MB20VL-001". That reply tells the device where to push.

The protocol has no authentication, so once punches are arriving set
ADMS_SERIALS to the real serial and restart. From then on other devices are
refused with 403.

Note: many budget terminals only speak plain HTTP, so port 80 is the safe
choice. If yours supports HTTPS, use 443 and leave the path the same.


STEP 8 — Alternative: the LAN collector
---------------------------------------
Only needed if the terminal has no Cloud Server/ADMS menu. A PC in the office
pulls records over port 4370 and posts them to /api/ingest.

On that PC (Node.js 20+):

  set DEVICE_IP=192.168.0.201
  set INGEST_URL=https://attendance.fakhris.com/api/ingest
  set INGEST_KEY=<the INGEST_KEY from step 5>
  node sync.mjs

Schedule it once a day, e.g. Windows Task Scheduler at 18:00, after the last
shift ends. Nothing needs to be open on the router: the PC dials out, the app
never dials in. `collector/sync.mjs --dry-run` prints what the device holds
without uploading, which is the quickest way to prove the device is reachable.

Android/Termux works too, see collector/android/README.md in the source repo.


STEP 9 — Backups
----------------
phpMyAdmin -> select the database -> Export -> Quick, SQL -> Go, once a month.
That single file restores every punch and employee record. Keep a copy of this
zip next to it; the two together rebuild the whole system.


UPDATES
-------
1. Build and pack on your machine:  npm run build && npm run pack
2. Upload the new zip into the app root and extract it over the old files.
   Answer "overwrite" — do not delete the folder first, or you lose tmp/ and the
   cPanel wiring.
3. Setup Node.js App -> Restart.
`schema.sql` in the new zip shows what the database looks like; if a new table or
column appears, import the new file (it only adds missing tables — tell whoever
built the change if a column was added, since that needs an ALTER).


TROUBLESHOOTING
---------------
503 "Web application could not be started"
  Read stderr.log in the app root. The usual causes:
  - HOSTNAME not set to 0.0.0.0 (step 5)
  - Application startup file is not server.js
  - files nested one folder too deep (step 4)
  - Node.js version too old for the build

Login page loads, but every password is rejected
  The hash was generated from a different password, or it was truncated when
  pasted. Regenerate with `npm run hash -- 'password'` and paste the full value.

Login appears to do nothing (page just reloads)
  You are on http://. The session cookie is marked Secure, so the browser drops
  it on a plain-HTTP page. Use https:// — cPanel's AutoSSL issues a certificate
  for the subdomain automatically within an hour of creating it. Check
  SSL/TLS Status in cPanel if the padlock is missing.

Sample employees appear instead of your staff
  DATABASE_URL is empty or ignored. It must start with mysql:// and point at
  localhost. Restart after changing it.

Dashboard 500 / "Table ... doesn't exist"
  Step 2 did not run on the right database, or the database user lacks
  privileges. Re-check the database name inside DATABASE_URL.

Device shows "Connecting" / no punches
  - The curl handshake in step 7 must return text; if it 404s, the path is
    wrong (it must be /iclock, not /iclock/cdata).
  - Try port 80 with HTTPS off; many terminals have no TLS support.
  - Once punches arrive, set ADMS_SERIALS; until then, the app logs each
    unknown serial in stderr.log.

Wrong times (punches 6 hours off)
  OFFICE_UTC_OFFSET_MINUTES must be 360 for Asia/Dhaka. Device clocks carry
  local time with no zone, so this value is what converts them to UTC.

Forgot the password
  Generate a new hash locally (npm run hash), replace ADMIN_PASSWORD_HASH,
  restart.
