shelfd

A small self-hosted OPDS server for ebook archives.

Browse by subject, search from reader apps, and fill in covers and metadata automatically.

What It Does

• turns an ebook archive into an OPDS catalog
• gives you an explore-first browsing feed instead of search-only UX
• still supports OPDS search for clients like Foliate
• pulls metadata and covers from Open Library when available
• generates fallback covers when nothing better exists

Quick Start

Run with just:

just up

Or without just:

docker compose up --build

Then open:

• http://localhost:7451/opds

Stop:

just down

Or:

docker compose down

Config

The defaults are enough to get started, but these are the settings you will most likely care about:

• ARCHIVE_BASE: where your upstream archive lives
• ARCHIVE_NAME: display name shown in feeds
• APP_NAME: app name shown to OPDS clients
• PUBLIC_BASE_URL: public base URL for generated links
• DATABASE_URL: SQLite database location
• RUST_LOG: log level and filters

Endpoints

• GET /opds
• GET /opds/search?q=...
• GET /healthz

Dev

just up
just test
just lint
just fmt

License

MIT. See LICENSE.