Grimoire - Self-Hosted TTRPG Library Manager

Website · Documentation · Live Demo · Join our Discord

[!TIP] Looking for a group to play with? I also built findtabletop.games, a free way to find tabletop RPG groups and players. Grimoire handles your library; findtabletop.games helps you find the table.

A self-hosted web app for your tabletop RPG library. Point it at a folder of PDFs, maps, tokens, audio, and 3D models, and Grimoire turns it into a searchable library you can read from any device - every page of every book indexed, including scanned ones.

It runs as a single Docker container against a directory you already own, and by default never writes to it.

Features

Library

• Library browser - Organizes your collection by game system from the folder structure, with card, compact, and list layouts.
• Full-text search - Every page of every PDF is indexed with SQLite FTS5. Also finds books by title, author, or publisher, and maps, tokens, audio, and models by filename, folder, or tag. Narrow with title:, author:, tag: and friends - see Searching your library.
• Sort, filter, and saved presets - Filter on genre, system family, edition, dice/materials, tags, favourites, and explicit content. Tag filters are boolean groups (Building AND store OR shop), and named presets save to your account with one default per view.
• Shared tags - One tag catalog across every resource type, with a Tags page to rename, merge, delete, and browse by tag, and per-tag downloads.
• Metadata editor - Rich metadata for systems and books, drawn from curated lists you manage in Settings → Metadata. Parent systems group related lines ("Cyberpunk" + "Red" → "Cyberpunk Red").
• Bulk actions - Multi-select books, maps, tokens, audio, and models, then bulk tag, add to a campaign, or edit metadata via a carousel.
• Duplicate detection - An admin scan finds byte-identical files, near-identical titles, overlapping page text, and gridded/gridless map pairs. Nothing is ever deleted automatically; you review each group side by side and merge copies without losing bookmarks, favourites or campaign links.

Reading

• Page-by-page viewer - PDFs rendered server-side as images for fast mobile viewing, with pinch-to-zoom, swipe navigation, and spread mode.
• Bookmarks - Per-user page and text-selection bookmarks with inline highlights.
• Favorites - Star systems, books, maps, tokens, audio, and models from a card, a list row, or the item's own page.
• OPDS catalog - A personal feed URL per user, to connect e-reader apps directly to your library.

Maps

• Map gallery - Browse battlemaps by folder with tag filtering, grid metadata, and full-res download. Image, PDF, animated (.webm/.mp4), and Universal VTT maps all display in-app; large maps load through a downscaled preview while downloads stay untouched.
• UVTT editor - Export any image map as a Universal VTT file, drawing the walls, doors, and lights a virtual tabletop uses for dynamic lighting. Opens existing .uvtt files on the geometry they already carry.

Tokens

• Token browser - Browse and tag character tokens and portrait assets.
• Token editor - Turn any picture into a VTT-ready token: position the art, pick a frame and output size, and export it. See Token editor.

Audio

• Audio library - Ambient tracks, soundscapes, music, and effects (MP3, OGG, Opus, FLAC, WAV, M4A, AAC) and audiobooks (M4B) with chapter navigation, reading embedded duration, tags, and album art.
• Global player - A persistent pop-out player that keeps playing as you navigate, with a queue you can reorder and a repeat toggle.
• Soundboard - A floating, draggable grid of one-tap pads that play over the player and each other, with per-pad loop toggles and a configurable grid up to 8×15.
• Saved sets - Name and keep playlists and boards. They live on your account rather than one browser, so a board built at home is there at the table.

Campaigns

• Campaigns - Track GM-run and personal campaigns with character art and sheets, linked resources, and scheduling.
• Wiki - A markdown notes wiki with deep linking, Markdown/JSON/LegendKeeper import and export.
• Wiki note templates - Start a page from a community template, write your own, or upload a Markdown file or .zip. Templates belong to the campaign, so downloaded ones are yours to edit. See Wiki note templates.

Administration

• Book restrictions - Restrict a book, system, or category to GMs and admins or admins only. Restricted content is hidden outright - from library, search, downloads, favourites, and OPDS - since the title and cover are the spoiler. See Restricting books.
• Grimoire Codex DB - Look books and systems up in the built-in community catalogue, link them, and send corrections back. Turned on with a Grimoire Codex DB API token. See Grimoire Codex DB.
• Community add-ons - Install community metadata scrapers to fill in system and book details from external sources, reviewing a field-by-field diff before anything is written. See Community add-ons.
• Character sheets - A schema-driven character builder: install a sheet for your system, build characters against it, browse a content catalogue, and give each table its own ruleset of allowed content. Sheets are per user, so no admin approval is involved. Import characters from Forge Steel, Pathbuilder and other tools through community importers. See Character sheets.
• Themes and light mode - Light, dark, or system, plus installable colour themes (including a WCAG AAA High Contrast palette). Themes are per user, so no admin approval is involved. See Themes.
• Docker ready - One command to run, mount your library directory, done. Works on desktop, tablet, and phone.

Who it's for

Grimoire is for people who have bought a lot of TTRPG material and want it in one place. If your collection is a folder of PDFs from twenty Humble Bundles and three Kickstarters, spread across a NAS and a laptop, this is the problem it solves.

• Players and GMs who want their books searchable from the table - on a phone, a tablet, or the laptop already open for notes.
• GMs running a campaign, who need the map, the token, the statblock, and last session's notes in the same place, and who need some of it hidden from the players.
• Self-hosters, who would rather run one Docker container against a folder they own than upload their library to somebody else's service.

It is not a store, a pirate tool, or a PDF editor. Grimoire reads a library you already have, and by default never writes to it.

Requirements

Docker, a folder of TTRPG files, and somewhere to run it - a NAS, a home server, a spare mini-PC, or your desktop. It is happy on a Raspberry Pi and scales up to libraries of thousands of books.

Screenshots

Library and browsing

Systems	System detail

Search	Tag browser

Favourites

Reading

Book view with table of contents	In-book search

Maps, tokens, and models

Maps	Tokens

Token editor	3D models

Universal VTT map editor	Token vision preview

Audio

Audio page with soundboard and playlist

Campaigns

Campaign overview	Campaign notes wiki

Quick Start

New to Docker? See the Docker Installation Guide for a step-by-step walkthrough for Windows, macOS, and Linux.

1. Organize your library

Create a library/ folder with this structure:

library/
├── books/
│   └── Dungeons and Dragons 5e/
│       ├── core/
│       │   ├── Players Handbook.pdf
│       │   ├── Dungeon Masters Guide.pdf
│       │   └── monsters/              ← subfolder within a category
│       │       ├── Monster Manual.pdf
│       │       └── Mordenkainen's Monsters.pdf
│       ├── supplements/
│       ├── adventures/
│       │   ├── Curse of Strahd/       ← adventure path subfolder
│       │   │   ├── Curse of Strahd.pdf
│       │   │   └── Strahd DM Screen.pdf
│       │   └── Lost Mine of Phandelver/
│       │       └── Lost Mine of Phandelver.pdf
│       ├── character-sheets/
│       ├── handouts/
│       └── homebrew/
├── maps/
│   └── Sunken Temple (22x22)/
│       ├── Sunken Temple Basement.png
│       └── The Sunken Temple.png
├── tokens/
│   └── Monsters/
│       └── goblin.png
├── audio/
│   └── Ambient/
│       ├── cover.jpg
│       └── tavern-night.mp3
└── models/
    └── Goblins/
        ├── Presupported/
        │   └── goblin-archer.stl
        └── Unsupported/
            └── goblin-archer.stl

See Library structure for the full layout, category rules, and the marker files that group systems together.

2. Run with Docker Compose

Copy the default compose file, set your volume paths, then start:

cp docs/docker/docker-compose.yml docker-compose.yml
# Edit docker-compose.yml and set the volume paths
docker compose up -d
open http://localhost:9481

On first launch you'll be prompted to create an admin account, or you can pre-seed users automatically (see Pre-seeding users).

3. Pull from DockerHub (or GHCR)

docker pull hunterreadca/grimoire:latest

Or pin to a specific release:

docker pull hunterreadca/grimoire:1.5.0

Release and nightly tags are mirrored to the GitHub Container Registry, if you'd rather pull from there:

docker pull ghcr.io/hunter-read/grimoire:latest

Image variants: the default tags (latest, 1.5.0, …) include the Tesseract OCR engine so image-only PDFs are searchable (see OCR). If you don't need OCR and prefer a smaller image, use the matching -slim tag (e.g. hunterreadca/grimoire:latest's slim counterpart :slim, or a pinned :1.5.0-slim), which omits Tesseract.

4. Minimal docker-compose.yml

services:
  grimoire:
    image: hunterreadca/grimoire:latest
    ports:
 - "9481:9481"
    volumes:
 - /path/to/your/library:/app/library   # add ":ro" to keep it read-only (see Volumes)
 - /path/to/grimoire/data:/app/data

5. Example compose files

Ready-to-use compose files for common setups are in docs/docker/:

Each file has inline comments explaining the options. Copy and edit the one that fits your setup:

cp docs/docker/docker-compose.valkey.yml docker-compose.yml
# Edit the volume paths, then:
docker compose up -d

6. Container health

The image ships a HEALTHCHECK that probes the unauthenticated GET /api/health endpoint. It verifies the app is serving on port 9481 and can reach the database (and Valkey, when configured), so docker ps shows (healthy) / (unhealthy) rather than just "running". Orchestrators can gate startup on it:

depends_on:
  grimoire:
    condition: service_healthy

Persistent data

The database, search index, and rendered thumbnails are all stored under DATA_PATH (the /app/data volume). Back this directory up to preserve your library metadata and user accounts.

Upgrading

Pull the new image and restart (docker compose pull && docker compose up -d). Database schema changes are applied automatically on startup via Alembic - no manual action is required when upgrading, including from versions that predate Alembic. On first run under the new system, an existing database is detected and stamped at the correct baseline, so only genuinely new migrations run thereafter. Back up DATA_PATH before upgrading, as always.

Running from source

Prefer to build the image yourself or run Grimoire directly on the host (Python 3.12+, Node 22+) without Docker? See Running from source.

Documentation

📖 docs.grimoirecodex.org

The documentation site is the best place to read all of this - searchable, with a sidebar, and including an interactive Compose Generator that builds a docker-compose.yml, a Podman Compose file, or systemd Quadlet units from your answers.

See also the website, the live demo, and our Discord.

This page covers what Grimoire is and how to install it. Everything else lives in docs/ alongside the code - the same material the documentation site publishes, kept in the repo so it versions with the release you are running:

Setting up

Using it

Administration

Reference

The live API is also self-documenting while the server is running: /api/docs (Swagger UI), /api/redoc, and /api/openapi.json.

Contributing

Grimoire is open source and contributions are welcome - bug reports, feature ideas, docs, and code.

See CONTRIBUTING.md for full details on reporting issues, submitting pull requests, and setting up a local development environment.

To report a security vulnerability privately, see SECURITY.md.

License

GNU General Public License v3.0 - see LICENSE for details.