Organizers create a "hunt" and generate printable QR code cards
Players scan hidden QR codes to earn points — first find gets the most points
Leaderboards track top players per hunt and globally

Point System

Scan Order	Points
1st scan	500
2nd scan	250
3rd scan	100
4th+	50

Players earn points only once per package. Re-scanning lets you update the package hint.

Tech Stack

Node.js + Express
SQLite via better-sqlite3
EJS templates
PDFKit + qrcode for printable QR sheets
Docker deployment via Portainer

Quick Start (Development)

cp .env.example .env
npm install
node src/setup-admin.js admin yourpassword
npm run dev

Visit http://localhost:3000

Docker Deployment

The project deploys via Gitea Actions → Docker build → Portainer stack update.

# Build locally
docker build -t loot-hunt .

# Run
docker run -p 3000:3000 -v loot-data:/app/data \
  -e SESSION_SECRET=your-secret \
  -e BASE_URL=https://loot-hunt.com \
  loot-hunt

# Create admin user inside container
docker exec -it loot-hunt node src/setup-admin.js admin yourpassword

Environment Variables

Variable	Description	Default
`PORT`	Server port	`3000`
`NODE_ENV`	Environment	`production`
`BASE_URL`	Public URL (for QR codes)	`http://localhost:3000`
`SESSION_SECRET`	Session encryption key	(required)
`DB_PATH`	SQLite database path	`./data/loot-hunt.db`
`UPLOADS_DIR`	Image uploads directory	`./data/uploads`
`TRUST_PROXY`	Trust reverse proxy headers	`false`

Project Structure

src/
├── app.js              # Express application entry point
├── setup-admin.js      # CLI tool to create/promote admin users
├── config/
│   └── database.js     # SQLite initialization & schema
├── middleware/
│   └── auth.js         # Auth & admin middleware
├── models/
│   └── index.js        # All database operations
├── routes/
│   ├── auth.js         # Login/register/logout
│   ├── admin.js        # Hunt management & PDF download
│   ├── loot.js         # QR scan handling, image upload, hints
│   └── hunts.js        # Public hunt profiles & leaderboards
├── utils/
│   └── pdf.js          # QR code PDF generation
└── views/              # EJS templates