From 00441f57878be6c8f6f1f7eccd0bb71ca432b486 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Wed, 17 Jun 2026 16:41:48 +1000 Subject: [PATCH] Add step-by-step setup guide to README --- README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 80 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1976cbc..5a02d5c 100644 --- a/README.md +++ b/README.md @@ -23,25 +23,96 @@ To regenerate the JSON from a spreadsheet: python3 scripts/extract_ghosts.py path/to/Ghost_Data.xlsx data ``` -## Setup +## Step-by-step setup -Requires Node 18+ and `build-essential` on Ubuntu (so `better-sqlite3` can compile its native module): +This walks through a fresh deploy on the Ubuntu server, behind the existing nginx (which already terminates HTTPS). + +### 1. Prerequisites + +Node 18 or newer, plus the build toolchain so `better-sqlite3` can compile its native module: ```bash -sudo apt-get install -y build-essential +node --version # expect v18+; install via nvm or nodesource if missing +sudo apt-get update +sudo apt-get install -y build-essential python3 +``` + +`build-essential` is required — without it `npm install` fails while compiling `better-sqlite3`. + +### 2. Get the code and install dependencies + +```bash +git clone https://gitea.hideawaygaming.com.au/jessikitty/newbury-nights.git +cd newbury-nights npm install -cp .env.example .env # then edit JWT_SECRET and admin creds -npm run seed # creates the DB, seeds ghosts/sets, bootstraps admin +``` + +`npm install` compiles the native SQLite module, so it may take a minute on first run. + +### 3. Configure environment + +```bash +cp .env.example .env +``` + +Then edit `.env` and set, at minimum: + +- `JWT_SECRET` — a long random string (e.g. `openssl rand -hex 32`). This signs login tokens; treat it like a password. +- `ADMIN_USER` / `ADMIN_PASS` — the bootstrap admin login created on first seed. You'll change the password from the admin panel right after. +- `PORT` — defaults to `3000`; change if that port is taken. + +### 4. Seed the database + +```bash +npm run seed +``` + +This creates `db/newbury.sqlite`, loads the 111 ghosts / 36 abilities / 17 sets from `data/*.json`, and creates the admin user. Expected output ends with something like `Seed complete: { ghosts: 111, abilities: 36, sets: 17, rosterLinks: 153 }`. + +Re-running `npm run seed` is safe — it only seeds ghost/set data when the `ghosts` table is empty, so it never clobbers admin edits. It always ensures an admin user exists. + +### 5. Start the app + +```bash npm start ``` -The app listens on `PORT` (default 3000) over plain HTTP — **nginx terminates HTTPS in front of it**. `app.set('trust proxy', 1)` is set so secure cookies work behind the proxy. +You should see `Newbury Nights listening on http://127.0.0.1:3000`. Test it locally: -Re-running `npm run seed` is safe: it only seeds ghost/set data when the `ghosts` table is empty, so it won't clobber admin edits. It always ensures an admin user exists. +```bash +curl http://127.0.0.1:3000/healthz # -> {"ok":true} +curl http://127.0.0.1:3000/api/scan/NN-70419 # -> Wrecked Shrimp Boat roster + Captain Archibald +``` + +For production, run it under a process manager so it restarts on reboot/crash — e.g. `pm2 start server.js --name newbury-nights`, or a systemd unit. Pass the env vars through whatever manager you use. + +### 6. Put nginx in front (HTTPS) + +Camera and gyro APIs only work in a secure context, so the site must be served over HTTPS. Copy the example server block and adjust `server_name` and certificate paths: + +```bash +sudo cp deploy/nginx.conf.example /etc/nginx/sites-available/newbury-nights +# edit server_name + ssl_certificate paths to match your domain/certs +sudo ln -s /etc/nginx/sites-available/newbury-nights /etc/nginx/sites-enabled/ +sudo nginx -t && sudo systemctl reload nginx +``` + +The app runs plain HTTP on `127.0.0.1:PORT`; nginx terminates TLS and forwards to it. `app.set('trust proxy', 1)` is already set so secure cookies work behind the proxy. + +### 7. First login and lock-down + +1. Open `https://your-domain/admin`. +2. Sign in with the `ADMIN_USER` / `ADMIN_PASS` from your `.env`. +3. Go to the **Account** tab and change the password immediately. +4. Under **Ghosts**, upload billboard GIFs and enable/disable ghosts. Under **Sets**, edit scan codes and rosters. + +### 8. Play + +Open `https://your-domain/` on a phone. Use **Scan a Set** (camera QR or type a code like `NN-70419`), **Free Hunt** for a quick random session, or **Ghost Index** to browse the roster. Allow camera and motion access when prompted. ## nginx -See `deploy/nginx.conf.example` for a reverse-proxy block. Camera and gyro APIs require a secure context, so the site must be served over HTTPS (which nginx already handles for you). +See `deploy/nginx.conf.example` for the full reverse-proxy block referenced in step 6. ## API quick reference @@ -68,5 +139,6 @@ scripts/extract_ghosts.py xlsx -> data/*.json scripts/seed.js seed DB from data/*.json + bootstrap admin data/ ghosts.json, abilities.json, sets.json public/ index.html (game), admin.html, css/, js/ +deploy/ nginx.conf.example uploads/ uploaded ghost billboards (gitignored) ```