Compendium

A library card catalog system for physical items — books, vinyl records, DVDs, CDs.

Features

• Catalog — add items by ISBN / UPC / MusicBrainz ID / TMDb ID / title search (Google Books / Open Library, MusicBrainz, TMDb) or manually for obscure items; search and browse works and copies; faceted discovery (media type, decade, availability)
• Recoverable work deletion — deleting a work moves it (copies, loan/hold history, notes, creator links, curated-list memberships) to a trash, restorable from Recently Deleted, compendium work trash, or the API; blocked while copies are on loan or carry outstanding fines; holds are cancelled; trashed works auto-purge after a configurable retention window (COMPENDIUM_TRASH_RETENTION_DAYS, default 90 days)
• Circulation — checkout, checkin, loan renewal with category-aware per-media-type loan policies; lost / damaged / claims-returned states; self-checkout kiosk mode; library hours and holiday calendar so due dates never land on closed days and overdue fines skip closed days
• Holds — patron reservation queue; immediate promotion when a copy is available; suspend/resume; auto-expiry via maintenance command
• Fines — configurable per-policy overdue rates with caps and grace periods; lost/damaged fees; threshold-based checkout/hold blocking; pay/waive workflow; per-patron and bulk overdue assessment
• Notifications — outbox-pattern email delivery (hold-ready, due-soon, overdue) drained by a cron-invoked CLI; admin viewer + retry; per-patron opt-out; configurable retention
• Reports — checkouts/month, popular works, dormant items (weeding list), current overdues; CSV export; Chart.js trendlines
• Patrons & cards — patron categories (Adult/Child/Staff/Teacher seeded), card expiry with maintenance auto-deactivation, optional 1:1 patron↔user link for self-service
• Bulk import/export — round-trippable CSV; MARC21 binary + MARCXML import/export; LibraryThing TSV import; GoodReads CSV import; Discogs collection-CSV import (all with lenient encoding for messy real-world exports)
• Backup/restore — portable JSONL tarballs; backend-agnostic (SQLite ↔ Postgres); doubles as a DB migration path
• Labels — Avery-template item labels (spine / pocket) and patron cards (full / sticker) as PDFs. Spine templates: avery-5167-spine (½" narrow face), avery-5160-spine (1" medium face, rotated), avery-5160 (flat wrap-around, centered text), avery-22805/avery-22806 (square classification labels). Live in-page SVG preview updates as you change kind/template/fields — no PDF round-trip needed.
• Curated lists — librarian-editable named collections of Works ("Staff picks", "Summer reads") with slugs, per-work annotations, public/private and featured toggles; featured lists appear as a shelf on the OPAC landing page; public browse at /ui/lists
• Auth — five preset roles (ReadOnly, Patron, Librarian, SystemAdmin, Administrator) plus custom roles via the admin UI; JWT for API, cookie-based for web UI
• Audit log — synchronous trail of administrative mutations (Librarian + system tier); queryable via web UI, CLI, or REST
• DB-editable settings — most configuration knobs (library name, fines, kiosk timeout, SMTP, retention, configurable nav shortcuts, etc.) editable from the UI / CLI / API; env vars still win as a break-glass
• Remote phone scanner — pair a phone to the circulation desk via QR code; the phone camera dispatches scans to the desk in real time without installing an app. Supports checkout, checkin, and catalog-lookup modes. Pairing is ephemeral: a short-TTL claim secret lives in the QR; after the phone claims it, the secret rotates to a session cookie; the librarian can unpair from the desk at any time. Requires HTTPS on both the server and the phone browser (secure context for camera). Settings: public_base_url (DB-editable, env COMPENDIUM_PUBLIC_BASE_URL) and scan_session_minutes (DB-editable, env COMPENDIUM_SCAN_SESSION_MINUTES, default 60).
• Circulate by ISBN/UPC — checkout, checkin, and renew accept a book's printed ISBN barcode (or a disc's UPC) in place of a Compendium item label, so home and classroom libraries don't need to print labels. With several copies of the same title on loan, checkin asks the desk which copy came back rather than guessing. Toggle with the circulation_scan_isbn_enabled setting (env COMPENDIUM_CIRCULATION_SCAN_ISBN_ENABLED, default on) at Admin → Settings → Circulation.
• Web UI — HTMX + Jinja2 browser interface with catalog search, circulation desk (camera-based barcode scanning), patron self-service, light/dark/auto theme; per-user nav shortcut overrides via browser localStorage
• REST API — FastAPI; consumed by the web UI and available for integrations
• CLI — full librarian + sysadmin workflow without running a server, including stdin/stdout (-) for backup, import/export, and labels

Install

# Install the CLI as a standalone tool (recommended for production)
uv tool install compendium-ils           # SQLite only
uv tool install "compendium-ils[postgres]"  # + Postgres support

# Or with pip
pip install compendium-ils
pip install "compendium-ils[postgres]"

The installed command is compendium.

Quick start

Quick start (Docker)

One command — needs only Docker with the compose plugin:

curl -fsSL https://raw.githubusercontent.com/statyk/compendium/master/install.sh | sh

This scaffolds a ./compendium/ deployment (compose file, nginx, generated secrets) and starts it. Already have the package installed? compendium init ./compendium does the scaffold step alone. See docs/deployment.md for details.

Prerequisites

Python 3.11.4 or newer. (Backup restore uses the tarfile data filter from PEP 706, which was backported to 3.11.4.)

Debian / Ubuntu

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-dev build-essential
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

RedHat / CentOS / Fedora

sudo dnf install -y python3 python3-devel gcc
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

macOS

brew install python uv

Run

# Install dependencies
uv sync --extra dev

# Initialise the database (creates ./compendium.db with SQLite by default)
uv run compendium db init

# Create an Administrator account
uv run compendium user add --username admin --role Administrator

# Add a book by ISBN (looks up metadata from Google Books when key is set, else Open Library)
uv run compendium item add --isbn 9780441013593

# Add a patron
uv run compendium patron add --name "Alice Example"

# Start the server (web UI at http://localhost:8000/ui/catalog)
uv run compendium serve

Log in at http://localhost:8000/ui/login with the username and password you set above.

CLI reference

Run compendium --help for the full command tree, or compendium <group> --help for the subcommands of a specific group.

Catalog & cataloging

Circulation

Patrons & accounts

Reporting & labels

Operations

File-argument commands (backup, restore, import, export, labels spine/pocket/barcode/patron-card/patron-sticker) accept - for stdin/stdout. Status messages are routed to stderr in stdio mode so they don't corrupt binary output.

Every list/show command accepts --format table|json (table is the default; the reports group also keeps --format csv). table renders a readable rich table; json prints stable, script-friendly JSON to stdout — snake_case keys, ISO-8601 UTC datetimes, integer cents — with any notices sent to stderr instead, so output stays pipeable. For example:

compendium loan list --format json | jq '.[].due_at'

Web UI

Start the server with compendium serve and open your browser to http://localhost:8000/ui/catalog.

"Audience" lists the minimum preset that can access each route. Administrator can access everything. SystemAdmin gets the System-tier rows; slimmed Librarian gets librarian-tier rows but not System-tier.

Guest catalog search is enabled by default (toggle via /ui/admin/settings/general or COMPENDIUM_GUEST_SEARCH_ENABLED=false).

ISBN/UPC circulation fallback is enabled by default (toggle via /ui/admin/settings/circulation or COMPENDIUM_CIRCULATION_SCAN_ISBN_ENABLED=false).

REST API endpoints

The API is mounted at the root. Authenticate with POST /auth/login and pass the result as Authorization: Bearer <token>. Interactive docs live at http://localhost:8000/docs when the server is running.

Below is a high-level inventory grouped by concern; the OpenAPI document is the source of truth for parameters and bodies.

The "min permission" column lists the lowest preset role that's allowed. Administrator (wildcard) covers everything. Slimmed Librarian covers librarian-tier endpoints; SystemAdmin covers user/role/system-tier endpoints.

Configuration

Compendium settings come from three layers, in order of precedence:

1. Environment variable (COMPENDIUM_<KEY>) — break-glass override, wins over everything.
2. site_setting table — DB-backed, editable from /ui/admin/settings/*, the CLI (compendium settings ...), or the API (PATCH /settings/{key}). Changes take effect on the next page render — no restart.
3. Registry default — fallback hard-coded in services/settings_registry.py.

Most settings (library name, theme, fine thresholds, hold/overdue defaults, kiosk timeout, SMTP host/port/from, retention) are DB-editable. A handful stay env-only because they're either secrets or required before the DB is reachable:

For everything else, run compendium settings list to see the current value, source (env vs db/default), and per-key help text. The web admin UI shows the same with an "⚠ Overridden by env var" indicator on rows where an env var is currently masking the DB value.

See docs/deployment.md for full deployment guidance, or docker/README.md for the bundled Docker Compose setup (app + Postgres + nginx with auto-generated self-signed TLS).

Docker quick start

A pre-built multi-arch image (linux/amd64 + linux/arm64) is published to GitHub Container Registry on every release:

cd docker
cp .env.example .env && $EDITOR .env   # set passwords and JWT secret
docker compose pull
docker compose up -d

Image: ghcr.io/statyk/compendium — tags latest, X.Y.Z, X.Y are published for each release. Pin a version in .env with COMPENDIUM_IMAGE=ghcr.io/statyk/compendium:1.0.2.

PostgreSQL

SQLite is the default and fine for home or classroom use (up to ~10k items). For larger collections or multiple concurrent writers, use PostgreSQL:

uv sync --extra postgres

Then set:

COMPENDIUM_DATABASE_URL=postgresql+psycopg://compendium:<password>@localhost:5432/compendium

and run compendium db init to apply migrations. Full setup (creating the role and database, TLS, backups) is in docs/deployment.md.

Scheduled maintenance

Several maintenance commands need to run on a cadence — most importantly the email outbox drain (send-queued-notifications), without which queued notifications never go out. Install the bundled crontab via:

scripts/install-cron.sh

By default this writes the project path into the crontab and points logs at $HOME/.local/state/compendium/maintenance.log. Override either with flags:

scripts/install-cron.sh --project-dir /opt/compendium --log-file journal
scripts/install-cron.sh --log-file /var/log/compendium/maintenance.log

--log-file journal routes output to the systemd journal (view with journalctl -t compendium-maintenance -f). For paths the installer can't create unprivileged (e.g. /var/log/...), it prints the one-time sudo command and exits without touching the crontab.

See docs/crontab.sample for the full schedule and docs/compendium.service.sample for running the daemon under systemd.

Running tests

uv run pytest -q

Tests are split into tests/unit/ (no DB, mock repos) and tests/integration/ (SQLite in-memory).

Browser tests (E2E)

Browser tests run against a real compendium serve subprocess in Chromium. They are excluded from the default pytest run and require a one-time install:

uv sync --extra e2e
playwright install chromium

Then:

uv run pytest -m e2e

Expected wall time: 30–60 seconds. Tests live in tests/e2e/. The test_csp_no_console_errors.py test is the keystone: it navigates to every major page and asserts no console errors, which catches CSP/HTMX loading regressions that unit tests miss.

Layout

src/compendium/
├── domain/        # models, enums, permissions, errors
├── repositories/  # base protocols + SQLAlchemy implementations
├── services/      # business logic (catalog, circulation, holds, patrons, policies, auth, audit)
├── api/           # FastAPI routes + Pydantic schemas + JWT auth
├── web/           # HTMX + Jinja2 web UI + CSRF protection
├── cli/           # Typer CLI commands
├── config/        # settings, seed data
└── db/            # engine factory, session lifecycle

Changelog

Release-by-release changes are recorded in CHANGELOG.md.

License

MIT (to be finalised before first release).