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= 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.