Grimmory is a self-hosted digital library for ebooks, comics, documents, and audiobooks that runs on your own server under the AGPL-3.0 licence, built for readers who want their whole collection — files, metadata, reading progress, and sharing — in one place they control rather than spread across devices, apps, and cloud accounts.

What it is

Grimmory is a Java and Angular web application distributed as Docker images and backed by a MariaDB database. It ships as grimmory/grimmory on Docker Hub and ghcr.io/grimmory-tools/grimmory on the GitHub Container Registry, listening on port 6060, with a health endpoint at /api/v1/healthcheck and an optional OpenAPI export toggled by API_DOCS_ENABLED. Stable builds are published from semantic-release tags on main as vX.Y.Z plus latest, while nightly images are built from the develop branch. Storage is configured through DISK_TYPE, set to LOCAL by default or NETWORK when the library sits on network storage and Grimmory should not perform file operations.

The problem it solves is the loose collection: a folder tree of files that carries no covers, descriptions, reviews, or ratings, read through a separate app per format, with progress tracked in someone's head and books manually emailed to a Kindle. Grimmory replaces that arrangement by combining the library, the metadata source, the in-browser reader, the sync layer, and the delivery mechanism into one service, so the shelf and the reading state live together on infrastructure the operator owns.

Key capabilities

• Smart Shelves build custom and dynamic collections using rule-based filtering, tagging, and full-text search.
• Metadata Lookup pulls covers, descriptions, reviews, and ratings from Google Books, Open Library, and Amazon, with every field editable by hand.
• Built-in Reader opens PDFs, EPUBs, and comics in the browser with annotations, highlights, and reading progress tracking.
• Device Sync connects a Kobo, works with any OPDS-compatible app, and synchronises progress with KOReader.
• Multi-User support keeps shelves, progress, and preferences separate per user, with local or OIDC authentication.
• BookDrop watches a folder — mounted as ./bookdrop in the reference compose file — detects dropped files, enriches them, and queues them for import.
• One-Click Sharing sends any book to a Kindle, to an email address, or to another user from the interface.
• Supported formats cover EPUB, MOBI, AZW, AZW3, and FB2 for ebooks; PDF for documents; CBZ, CBR, and CB7 for comics; and M4B, M4A, MP3, and OPUS for audiobooks.

Who uses it and how

• Self-hosters running Docker Compose who want the library, the database, and the file storage inside their own network rather than a vendor's.
• Households and small teams that need per-user shelves and progress, using OIDC when an existing identity provider is already in place.
• Kobo owners and KOReader users who want reading position to follow them between devices without manual copying.
• Comics readers with CBZ, CBR, and CB7 archives who want the same shelf, search, and reader as their prose library.
• Audiobook listeners storing M4B, M4A, MP3, and OPUS files next to their ebooks instead of in a second application.
• Operators wiring up BookDrop so a watched folder becomes an automatic import queue rather than a manual catalogue chore.

Getting started

The documented path is Docker and Docker Compose: create a .env with the application, database, and storage variables, then bring up a compose file based on deploy/compose/docker-compose.yml using grimmory/grimmory:latest alongside lscr.io/linuxserver/mariadb:11.4.5. Full guides for OIDC setup, advanced configuration, and upgrades live at grimmory.org/docs.

How it compares

No paid product list accompanies this entry, so the honest comparison is with the adjacent tools the README already names: Kobo devices, OPDS-compatible reading apps, KOReader, and Kindle delivery. Grimmory does not compete with those clients — it sits underneath them as the server that holds the files, resolves metadata, and keeps progress consistent, so an existing Kobo, OPDS app, or KOReader install gains a shared, self-hosted backend instead of its own private view of the collection. Where a standalone reader owns one device's state, Grimmory makes the library the shared source of truth across all of them.

When to use it — and when not to

Anyone adopting Grimmory must operate more than one container: the application itself plus a MariaDB instance, with the database URL, user, password, and root password all supplied through environment variables, and persistent volumes for ./data, ./books, and ./bookdrop. Choosing DISK_TYPE=NETWORK disables file operations, so network storage forces a different operational model than the default local disk setup. It is a poor fit for someone who wants a hosted service with no server to maintain, no database to back up, and no compose file to keep current; the project carries 243 open issues and an AGPL-3.0 licence, which is fine for personal and self-hosted use but a constraint if the code is meant to be embedded in a closed product.

# Application
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC

# Database
DATABASE_URL=jdbc:mariadb://mariadb:3306/grimmory
DB_USER=grimmory
DB_PASSWORD=ChangeMe_Grimmory_2025!

# Optional: enable API docs + export OpenAPI JSON (defaults to false)
API_DOCS_ENABLED=false

# Storage: LOCAL (default) or NETWORK (disables file operations; see Network Storage section)
DISK_TYPE=LOCAL

# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!
MYSQL_DATABASE=grimmory

services:
  grimmory:
    image: grimmory/grimmory:latest
    # Convenience tag:
    # image: grimmory/grimmory:<release-version>
    # Alternative: ghcr.io/grimmory-tools/grimmory:<release-version>
    # To build from source instead: comment out 'image' and uncomment below
    # build: .
    container_name: grimmory
    environment:
      - USER_ID=${APP_USER_ID}
      - GROUP_ID=${APP_GROUP_ID}
      - TZ=${TZ}
      - DATABASE_URL=${DATABASE_URL}
      - DATABASE_USERNAME=${DB_USER}
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - API_DOCS_ENABLED=${API_DOCS_ENABLED}
      - DISK_TYPE=${DISK_TYPE}
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "6060:6060"
    volumes:
      - ./data:/app/data
      - ./books:/books
      - ./bookdrop:/bookdrop
    healthcheck:
      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
      interval: 60s
      retries: 5
      start_period: 60s
      timeout: 10s
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.4.5
    environment:
      - PUID=${DB_USER_ID}
      - PGID=${DB_GROUP_ID}
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${DB_USER}
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./mariadb/config:/config
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 10

docker compose up -d

services:
  grimmory:
    environment:
      - JDK_JAVA_OPTIONS=-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/data

just               # Show root + api + ui recipes
just test          # Run backend and frontend tests
just api test      # Run backend tests only
just ui dev        # Start the frontend dev server

graph LR
    A[Drop Files] --> B[Auto-Detect]
    B --> C[Extract Metadata]
    C --> D[Review and Import]

volumes:
  - ./bookdrop:/bookdrop