What is Grimoire?

Grimoire is a self-hosted web application for organizing a personal tabletop RPG collection. Point it at a directory of PDFs, maps, tokens, audio files, and 3D models, and it creates a searchable library you can reach from any device. Each PDF page is indexed with SQLite FTS5, including scanned books via OCR. The software provides a page-by-page reader with pinch-to-zoom and spread view, a map gallery with Universal VTT editing for dynamic lighting, a token editor for making VTT-ready tokens, and an audio library with a persistent player and soundboard. Campaign features include a markdown wiki, character sheets, and scheduling. The app runs in a single Docker container, mounts your existing library read-only by default, and supports OpenID Connect for single sign-on with providers such as Keycloak, Authentik, and Auth0. The project uses the GPL-3.0 license.

Should you self-host Grimoire?

Grimoire scores 52/100 on selfhost.directory (how scoring works) and ranks #6 of 12 in Book Management. It has 300 GitHub stars.

It shipped 10 stable releases in the past year. The latest, v1.9.2, came out on 23 October 2026. New versions land roughly every 7 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is GPL-3.0-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is bookorbit (73/100, 5 872 stars). It scores higher overall, so compare the two before you pick. See Grimoire vs bookorbit side by side.

Features

Audio library with global player and soundboard
Book restrictions
Campaign Management
Character sheets
Community add-ons
Duplicate Detection
Full-text PDF search
Grimoire Codex DB
Library browser
Map gallery with UVTT editor
OPDS Catalog
OpenID Connect Authentication
Page-by-page PDF viewer
Token editor

How to configure Grimoire

ALLOW_PASSWORD_AUTHENTICATIONtrueWhether to allow username/password login (can be disabled when OIDC is configured)
Whether to allow username/password login (can be disabled when OIDC is configured)
values: true, false
BASE_URLhttp://localhost:9481The public address you open Grimoire at (e.g., http://localhost:9481 or https://grimoire.example.com)
The public address you open Grimoire at (e.g., http://localhost:9481 or https://grimoire.example.com)
DATA_PATH/dataPath to the data folder inside the container (database, search index, thumbnails)
Path to the data folder inside the container (database, search index, thumbnails)
DISABLE_EXTERNAL_ADD_ON_INSTALLfalseDisable fetching themes, note templates, and add-ons from community repository
Disable fetching themes, note templates, and add-ons from community repository
values: true, false
LIBRARY_PATH/libraryPath to the library folder inside the container
Path to the library folder inside the container
OIDC_ADMIN_GROUPadminGroup name that grants admin role
Group name that grants admin role
OIDC_CLIENT_SECRETOpenID Connect client secret (stored encrypted under SECRET_KEY)
OpenID Connect client secret (stored encrypted under SECRET_KEY)
OIDC_GM_GROUPgmGroup name that grants GM role
Group name that grants GM role
OIDC_PLAYER_GROUPplayerGroup name that grants player role
Group name that grants player role
OIDC_TOKEN_ISSUERExact iss value your IdP puts in tokens
Exact iss value your IdP puts in tokens
PGIDGroup ID to run the container as (LinuxServer convention)
Group ID to run the container as (LinuxServer convention)
PUIDUser ID to run the container as (LinuxServer convention)
User ID to run the container as (LinuxServer convention)
SECRET_KEYKey used to sign login sessions; auto-generated if omitted
Key used to sign login sessions; auto-generated if omitted
STARTUP_SCANtrueWhether to scan the library on startup
Whether to scan the library on startup
values: true, false
VALKEY_URLRedis/Valkey connection URL for caching and multi-worker coordination
Redis/Valkey connection URL for caching and multi-worker coordination
WORKERS1Number of worker processes
Number of worker processes

FAQ

Can I make the scroll wheel zoom instead of turning pages?

Yes, in Settings → Preferences → Reader → Scroll wheel, choose Zoom to make scrolling zoom in/out, or Nothing to disable scrolling behavior.

Every restart starts a long library scan

Grimoire scans on startup to pick up files added while down. Set STARTUP_SCAN=false to disable startup scanning; new files will still appear via file watching or manual rescan.

How do I configure OIDC with Google?

Create a Google Cloud OAuth client with the authorized redirect URI, then configure Grimoire with the Google issuer URL, client ID/secret, and RS256 signing algorithm. Use email matching with auto-register off for a personal library.

How do I configure OIDC with Authentik?

Create groups in Authentik (grimoire-admin, grimoire-gm, grimoire-player, nsfw), create custom scope mappings for groups and permissions, configure the OAuth2/OIDC provider with those scopes, then set up Grimoire with the issuer URL, client ID/secret, groups claim, and advanced permissions claim.

A folder is skipped by the scan, and the file manager shows � in its name

The folder name is not valid UTF-8 (often from Windows legacy code pages). Rename it on the share to valid UTF-8, then rescan.

I forgot my admin password. How do I reset it?

Run a one-liner inside the container to hash a new password and update the database directly.

Grimoire won't start and the log mentions SECRET_KEY

The SECRET_KEY is set to a known placeholder value. Either delete the SECRET_KEY line from your compose file to let Grimoire generate one, or set a custom random value with openssl rand -hex 32.