Quest Board

Quest Board is a self-hosted TTRPG campaign hub for groups who want scheduling, Discord coordination, session memory, and campaign lore in one place instead of spread across calendars, chat logs, and wikis.

Read This First

• Production Operations
• Development Guide
• OIDC and Discord Integrations
• API Reference
• Roadmap — open work is tracked in Forgejo milestones and issues
• Completed Roadmap Work

Everything above is for whoever runs the deployment. The guides for GMs and players ship inside the app, at /help/gm and /help/player — public routes, so a link works before the reader has an account. Their source is webapp/frontend/src/help/.

What It Does

• OIDC sign-in with providers like Authentik, Keycloak, and Google
• Session scheduling with vote, direct, and tentative modes, plus per-session voting grids and GM confirmation flows
• Campaign-level reminder scheduling with Discord delivery, configurable offsets, and webhook or bot-backed notifications
• Discord reaction voting, attendance RSVP, account linking, and bot commands like /next, /recap, /note, /ask, and /record
• Voice session recording with attributed per-speaker capture, backend transcription, review/approval workflow, and AI-generated summaries
• Session pages with private player notes, GM-shared notes, calendar export links, attendance tracking, and responsive dashboards
• Campaign journals that combine session history, recap content, and public notes into a readable campaign record
• Campaign milestones for tracking major events, linked sessions, dates, and long-term progress beats
• Campaign analytics for attendance, participation, and session cadence
• A campaign wiki with article pages, relationships, structured sidebar fields, timeline events, aliases, version history, and search
• Player-character wiki support with owner roles, private character notes, campaign-page linking, and player-editable public character pages
• Lore pipeline automation that turns approved session recordings into reviewable wiki proposals, relationship updates, and campaign-memory tooling
• A GM Workbench of campaign-grounded AI tools — read-aloud descriptions, rumor mills, random tables, loot parcels, instant NPCs, session prep sheets, and story-arc suggestions — all reviewed before anything reaches your canon
• A Session Reference Shelf for live play: a spatial board of generated content and pinned wiki entries that holds the positions you drop them in, with glance-readable cards, a "now playing" spotlight, Ctrl-K retrieval, named scenes you swap between, and per-card notes for tonight
• Reveal-to-table, which shows a card's player-safe layer to your players in Quest Board or as a Discord embed while the rest of the card stays GM-only
• An end-of-session sweep that turns tonight's improv into canon deliberately — promote to the wiki via an AI draft, carry forward to next session, or discard — and a warm cold-open that starts the next session with a recap, the loops still open, and the cards you carried

Production Quick Start

1. Clone and configure

git clone https://git.rhoving.com/rbrooks/Quest-Board.git quest-board
cd quest-board
cp .env.example .env

Update .env for your real deployment values. At minimum:

• set APP_URL and QUESTBOARD_PUBLIC_URL to your public URL
• set OIDC_REDIRECT_URI to https://your-domain/auth/callback
• set strong values for SECRET_KEY, POSTGRES_PASSWORD, POSTGRES_MIGRATE_PASSWORD, and BOT_API_KEY
• configure your OIDC provider settings
• add DISCORD_BOT_TOKEN if you want bot features enabled

The full environment reference lives in .env.example.

2. Start the stack

docker compose up -d

Or:

make up

3. Run the guarded migration workflow

make migrate-safe

This is the preferred production migration path. It:

• runs a schema sanity preflight
• writes an immediate pg_dump snapshot under /app/backups
• applies alembic upgrade head

4. Put it behind a reverse proxy

Quest Board expects external TLS termination. Point your reverse proxy at the frontend HTTP port exposed by the stack.

5. Finish app configuration

• sign in through your OIDC provider
• configure Admin -> Bot Settings
• configure campaign-level Discord settings if needed

See docs/OPERATIONS.md and docs/INTEGRATIONS.md for the detailed production setup steps.

Privacy / Data Retention

Quest Board can capture voice sessions, so it lets you decide how long the raw audio and the derived transcripts are kept. Policies are set instance-wide in Admin -> Settings and can be overridden per campaign; a campaign that leaves a field unset inherits the instance default.

• Audio — delete_after_processing (recommended default), retain_days (keep the raw per-speaker recordings for N days after processing, then delete), or retain_indefinitely.
• Transcripts — retain_indefinitely (default) or retain_months (clear the transcript text N months after processing; summaries and wiki/lore entries are always kept).

The recommended posture is transcript-only: keep the searchable transcript and summary, but delete the raw audio once it has been processed. A daily retention task enforces these policies.

Note: delete_after_processing removes the raw recording as soon as the transcript and summary are saved, which means a session can no longer be re-transcribed. If you may want to reprocess audio (e.g. after tuning Whisper), use retain_days with a window that suits you instead.

Updating Production

git pull
docker compose up -d --build

Migrations now run automatically: a one-shot migrate service applies alembic upgrade head in the correct order before backend, worker, and beat start, so they never serve against an old schema. No manual migrate step.

The automatic path does not take a pre-migration backup. Before a major upgrade, snapshot the database first (while the current stack is still running):

make backup-now        # or `make migrate-safe` to also preflight + migrate now
git pull
docker compose up -d --build

Useful Make Targets

make help

Common operations:

• make up
• make down
• make logs
• make migrate
• make migrate-safe
• make backup-now
• make set-admin EMAIL=user@example.com

Container Images

Each tagged release publishes versioned backend, frontend, and bot images to the Forgejo container registry (git.rhoving.com/rbrooks/quest-board-*), so you can pin a deployment to exactly what was tested and roll back with a tag change instead of rebuilding from source. See docs/OPERATIONS.md → Running from Published Images.

Notes

• Review the code before running it in production. This project has been developed with AI coding assistance and may contain mistakes.
• Development instructions have moved to docs/DEVELOPMENT.md.
• Integration setup details have moved to docs/INTEGRATIONS.md.