Marginalia

A companion app for Kavita. Marginalia reads your Kavita database (read-only) and your library files, and adds discovery, achievements, Discord summaries, and library tooling on top. It does not replace Kavita and never writes to Kavita's database.

Requirements

• A running Kavita instance.
• Read access to Kavita's config directory (the folder containing kavita.db).
• Read access to your library folders.

Quick start

# 1. Grab the compose files
mkdir marginalia && cd marginalia
curl -O https://raw.githubusercontent.com/DieselTech/Marginalia/main/compose.yml
curl -O https://raw.githubusercontent.com/DieselTech/Marginalia/main/.env.example

# 2. Configure
cp .env.example .env
$EDITOR .env          # set your paths, timezone, and port

# 3. Run
docker compose up -d

Then open http://<host>:5000 (or whatever MARGINALIA_PORT you set).

⚠️ Path parity with Kavita (important)

Kavita stores absolute library paths in its database — whatever your Kavita container sees (e.g. /manga). Marginalia resolves series folders using those exact stored paths, so the container-side path of each library mount in compose.yml must match the path Kavita has for that library.

You set your own host paths in .env; keep the container paths in compose.yml (/manga, /comics, /books) identical to Kavita's. If a library doesn't resolve, this mismatch is almost always why.

Image tags

Images are published to the GitHub Container Registry:

ghcr.io/dieseltech/marginalia:latest     # newest release (what compose uses)
ghcr.io/dieseltech/marginalia:X.Y.Z      # pin a specific version

Both linux/amd64 and linux/arm64 are built, so it runs on x86-64 servers and on arm64 (Raspberry Pi, Apple-silicon, arm VPS) alike.

Bugs & issues

Please file issues at https://github.com/DieselTech/Marginalia/issues.