Turnpike/README.md

Turnpike

Self-hosted event attendee and volunteer management. One instance, one event.

Turnpike handles gate check-in, volunteer scheduling, and department coordination for events ranging from a single evening to a multi-day festival. It works offline — gate volunteers can check people in without a network connection and sync when connectivity returns.

Features

• Attendee management — CSV import (CrowdWork/Zeffy auto-detected), party-size tracking, search, check-in
• Volunteer scheduling — departments, shifts with capacity, conflict detection, drag-and-drop reordering
• Volunteer kiosk — token-authenticated self-service shift signup, no login required
• Gate check-in — full-screen UI with QR scanner, party check-in ("2/3 checked in"), volunteer dual check-in
• Schedule board — department leads and coordinators manage shift assignments with conflict awareness
• Role-based access — admin, coordinator, volunteer lead (department-scoped), gate
• Offline-first PWA — installs on phones/tablets, full offline check-in with background sync
• Real-time — check-ins and changes broadcast live via SSE
• SMTP email — send volunteer token links directly or export CSV for bulk email platforms
• Single binary — Go backend embeds the frontend; no runtime dependencies

Tech Stack

• Backend: Go, SQLite (WAL mode), JWT auth
• Frontend: Svelte 5, Dexie (IndexedDB), Vite
• Deployment: single static binary — no CGO, no external database

Quick Start

# Build (frontend + Go binary)
make build

# Run (creates admin user on first startup)
TURNPIKE_ADMIN_USER=admin TURNPIKE_ADMIN_PASSWORD=changeme ./turnpike

Open http://localhost:8180.

See docs/INSTALLATION.md for systemd, Docker, NixOS, and reverse proxy setup.

Configuration

Flag	Env var	Default	Description
--addr	—	0.0.0.0:8180	Listen address
--db	—	turnpike.db	SQLite database path
--secret	TURNPIKE_SECRET	auto-generated	JWT signing secret (persist across restarts)
--token-expiry	—	24	JWT lifetime in hours
--base-url	—	—	Public URL for volunteer token links
--smtp-host	—	—	SMTP server hostname
--smtp-port	—	587	SMTP port (587 = STARTTLS, 465 = implicit TLS)
--smtp-user	—	—	SMTP username
--smtp-password	—	—	SMTP password
--smtp-from	—	—	Sender email address
--smtp-from-name	—	—	Sender display name
—	TURNPIKE_ADMIN_USER	—	Bootstrap admin username (first run only)
—	TURNPIKE_ADMIN_PASSWORD	—	Bootstrap admin password (first run only)

User Roles

Role	Access
admin	Full access: attendee import, user management, SMTP settings, all departments and shifts
coordinator	All departments: volunteers, shifts, schedule board. No user management or settings
volunteer_lead	Own department only: volunteers and shifts scoped to assigned department
gate	Full-screen check-in UI with QR scanner. No access to other pages

See docs/USAGE.md for detailed workflow documentation.

Development

Prerequisites: Nix + direnv, or Go 1.24+ and Node.js 18+ installed manually.

git clone <repo-url>
cd turnpike
direnv allow   # activates Go + Node.js via flake.nix

Two-terminal dev setup:

# Terminal 1 — Go API server
go run . --db dev.db

# Terminal 2 — Vite dev server (proxies /api to :8180)
cd frontend && npm install && npm run dev

The Vite dev server runs on :5173 and proxies /api requests to the Go server on :8180.

Documentation

• Usage Guide — event setup, attendee import, volunteer kiosk, gate check-in, schedule board
• Installation Guide — building, deploying, systemd, Docker, NixOS, reverse proxy, backup

License

CC BY-NC-SA 4.0