📚 Shelfmark: Book Search & Request Tool

Note

This is a fork of calibrain/shelfmark that adds the automation the upstream project intentionally left out — Hardcover wishlist sync, automatic downloading, and Audiobookshelf library-aware de-duplication. All original functionality is preserved and full credit goes to the original authors; upstream is in maintenance mode. See Fork Additions for what's different.

Shelfmark is a self-hosted web interface for searching and requesting books and audiobooks across multiple sources. Bring your own sources, metadata providers, and download clients to build a single hub for your digital library. Supports multiple users with a built-in request system, so you can share your instance with others and let them browse and request books on their own.

Works great alongside the following library tools, with support for automatic imports:

• Calibre
• Calibre-Web
• Calibre-Web-Automated
• Grimmory
• Audiobookshelf

✨ Features

• One-Stop Interface - A clean, modern UI to search, browse, and download from multiple configured sources in one place
• Multiple Sources - Configurable web, torrent, usenet, and IRC source support
• Audiobook Support - Full audiobook search and download with dedicated processing
• Flexible Search - Search metadata providers (Hardcover, Open Library, Google Books) for rich book and audiobook discovery, or query configured sources directly
• Multi-User & Requests - Share your instance with others, let users browse and request books, and manage approvals with configurable notifications
• Authentication - Built-in login, OIDC single sign-on, proxy auth, and Calibre-Web database support
• Real-Time Progress - Unified download queue with live status updates across all sources
• Network Flexibility - Configurable proxy support, DNS settings, and optional Cloudflare handling for protected sources

🔱 Fork Additions

This fork adds an optional automation pipeline on top of upstream Shelfmark, configurable under Settings → Hardcover Sync. Everything here is off by default and opt-in:

• Hardcover Wishlist Sync - Automatically pull books from a Hardcover reading shelf (e.g. "Want to Read") into Shelfmark as requests, on a schedule (configurable in minutes or hours) or on demand via a "Sync now" button. Synced requests carry full metadata and cover art.
• Automatic Downloads - Auto-approve and download synced books, selecting the best release from a drag-to-reorder source priority list. A strict title/author/audiobook-format (and seeder) match guard avoids grabbing the wrong file; anything without a confident match is left as a pending request for manual review.
• Library-Aware De-duplication - Check your Audiobookshelf library before adding or downloading a book and skip anything you already own. Fails open (proceeds) if Audiobookshelf is unreachable, so the pipeline never stalls.

Tip

Designed to pair with ShelfBridge. ShelfBridge syncs your Audiobookshelf listening progress up to Hardcover; this fork closes the loop in the other direction — pulling your Hardcover "Want to Read" shelf down into your library and skipping anything you already own. Run both and Hardcover becomes a single hub: mark a book "Want to Read" and it lands in your library automatically; finish listening and your Hardcover status updates on its own.

These build on Shelfmark's existing request and download systems; with all of them disabled, the app behaves exactly like upstream.

🖼️ Screenshots

Home screen

Search results

Multi-source downloads

Download queue

🚀 Quick Start

Prerequisites

• Docker & Docker Compose

Installation

1. Download the docker-compose file:

   curl -O https://raw.githubusercontent.com/InfiniteAvenger/shelfmark/main/compose/docker-compose.yml

2. Start the service:

   docker compose up -d

3. Open http://localhost:8084

Open the web interface, then configure the sources and settings you want to use.

Volume Setup

volumes:
  - /your/config/path:/config # Config, database, and artwork cache directory
  - /your/download/path:/books # Downloaded books
  - /client/path:/client/path # Optional: For Torrent/Usenet downloads, match your client directory exactly.

Tip: Point the download volume to your CWA or Grimmory ingest folder for automatic import.

Note: CIFS shares require nobrl mount option to avoid database lock errors.

Non-root container mode

• Start the container as 1000:1000 with Docker user: "1000:1000" or docker run --user 1000:1000.
• For Kubernetes, set runAsUser: 1000, runAsGroup: 1000, and runAsNonRoot: true together.
• PUID/PGID keep the default root startup flow.
• Mounted paths must already be writable by 1000:1000.
• USING_TOR=true requires root startup.

⚙️ Configuration

Search Modes

Direct

• Queries configured sources directly

Universal (recommended)

• Search via metadata providers (Hardcover, Open Library, Google Books) for richer results
• Aggregates releases from multiple configured sources
• Full audiobook support

Environment Variables

Environment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.

Variable	Description	Default
FLASK_PORT	Web interface port	8084
INGEST_DIR	Book download directory	/books
TZ	Container timezone	UTC
PUID / PGID	Runtime user/group for the default root-startup flow (also supports legacy UID/GID)	1000 / 1000
SEARCH_MODE	direct or universal	universal
USING_TOR	Enable Tor routing (requires root startup)	false

See the full Environment Variables Reference for all available options.

Some of the additional options available in Settings:

• Prowlarr - Configure indexers and download clients to download books and audiobooks
• Additional audiobook sources - Configure additional sources for audiobook discovery
• IRC - Add details for IRC book sources and download directly from the UI
• Library Link - Add a link to your Calibre-Web or Grimmory instance in the UI header
• File processing - Customiseable download paths, file renaming and directory creation with template-based renaming
• Network Settings - Custom proxy support (SOCKS5 + HTTP/S) and configurable DNS
• Format & Language - Filter downloads by preferred formats, languages and sorting order
• Metadata Providers - Configure API keys for Hardcover, Open Library, etc.

🐳 Docker Variants

Standard

docker compose up -d

The full-featured image with all network capabilities included.

Tor Routing

Optional Tor support for network privacy:

curl -O https://raw.githubusercontent.com/InfiniteAvenger/shelfmark/main/compose/docker-compose.tor.yml
docker compose -f docker-compose.tor.yml up -d

Notes:

• Requires root startup
• Requires NET_ADMIN and NET_RAW capabilities
• Timezone is auto-detected from Tor exit node
• Custom DNS/proxy settings are ignored when Tor is active

Lite

A lighter image without the built-in browser automation. Ideal for:

• External services - Already running FlareSolverr or similar for other applications
• Alternative sources - Using Prowlarr, IRC, or other configured sources
• Audiobooks - Using Shelfmark primarily for audiobooks

curl -O https://raw.githubusercontent.com/InfiniteAvenger/shelfmark/main/compose/docker-compose.lite.yml
docker compose -f docker-compose.lite.yml up -d

If you need browser-based access with the Lite image, configure an external resolver in Settings.

🔐 Authentication

Authentication is optional but recommended for shared or exposed instances. Multiple authentication methods are available in Settings:

1. Single Username/Password

2. Proxy (Forward) Authentication

Proxy auth trusts headers set by your reverse proxy (e.g. X-Auth-User). Ensure Shelfmark is not directly exposed, and configure your proxy to strip/overwrite these headers for all inbound requests.

3. OIDC (OpenID Connect)

Integrate with your identity provider (Authelia, Authentik, Keycloak, etc.) for single sign-on. Supports PKCE flow, auto-discovery, group-based admin mapping, and auto-provisioning of new users.

4. Calibre-Web Database

If you're running Calibre-Web, you can reuse its user database by mounting it:

volumes:
  - /path/to/calibre-web/app.db:/auth/app.db:ro

Multi-User Support

With any authentication method enabled, Shelfmark supports multi-user management with admin/user roles. Users can have per-user settings for download destinations, email recipients, and notification preferences. Non-admin users only see their own downloads and can submit book requests for admin review. Admins can configure request policies per source to control whether users can download directly, must submit a request, or are blocked entirely.

Health Monitoring

The application exposes a health endpoint at /api/health (no authentication required). Add a health check to your compose:

healthcheck:
  test: ["CMD", "curl", "-sf", "http://localhost:8084/api/health"]
  interval: 30s
  timeout: 30s
  retries: 3

Logging

Logs are available via:

• docker logs <container-name>
• /var/log/shelfmark/ inside the container (when ENABLE_LOGGING=true)

Log level is configurable via Settings or LOG_LEVEL environment variable.

Development

# Quality checks
make checks              # Run ALL static analysis (frontend + Python)
make python-checks       # Run Ruff, BasedPyright, and Vulture
make install-python-dev  # Sync Python runtime + dev tools with uv

# Frontend development
make install     # Install dependencies
make dev         # Start Vite dev server (localhost:5173)
make build       # Production build
make frontend-typecheck  # TypeScript checks

# Backend (Docker)
make up          # Start backend via docker-compose.dev.yml
make down        # Stop services
make refresh     # Rebuild and restart
make restart     # Restart container

The frontend dev server proxies to the backend on port 8084.

License

MIT License - see LICENSE for details.

⚠️ Disclaimer

Shelfmark is a search interface that displays results from external metadata providers and sources. It does not host, store, or distribute any content. The developers are not responsible for how the tool is used or what is accessed through it.

Users are solely responsible for:

• Ensuring they have the legal right to download any material they access
• Complying with copyright laws and intellectual property rights in their jurisdiction
• Understanding and accepting the terms of any sources they configure

Use of this tool is entirely at your own risk.

Support

For issues or questions about this fork, please file an issue on GitHub. For issues with upstream Shelfmark, see calibrain/shelfmark.