Add step-by-step setup guide to README

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)
 ```