Take control of your digital library.
BookBoss is a self-hosted digital library manager built in Rust. It provides a web-based interface for organising and browsing your e-book collection, backed by a flexible database layer that supports PostgreSQL, MySQL, MariaDB, and SQLite.
- Browse your book library with cover art, title, author, series, and publisher
- View book detail pages with full metadata (description, genres, tags, language, publication date, page count, identifiers)
- Browse all authors with a dedicated authors listing page
- View author detail pages listing all their books
- Browse all series with a visual series listing page (fanned cover art, book count)
- View series detail pages listing all books in a series
- Sort books by date added, title, and author
- Search bar with support for
author:,title:,series:,genre:,tag:refinements - Edit book metadata (title, author, series, publisher, genres, tags, description, identifiers, cover)
- Bulk edit metadata across multiple selected books
- Delete books from the library
- Download book files directly from the book detail page
- Keyboard shortcuts for common operations
- Real-time UI updates via Server-Sent Events (SSE)
- Drop books into a watched folder — BookBoss scans and picks them up automatically
- Metadata extracted from EPUB files automatically
- Parallel metadata enrichment from external providers (Hardcover, OpenLibrary, GoogleBooks) with title+author similarity scoring
- Review incoming books before they enter the library (approve or reject)
- Cover art fetched automatically from the most confident provider match
- Manual scan trigger from the UI
- Create manual shelves and add/remove books via drag-and-drop
- Create smart shelves with filter rules (e.g. "all books with read status Active")
- Smart shelves update automatically as books and reading state change
- Track reading status per book (Unread, Reading, Paused, Rereading, Read, Abandoned)
- Record reading progress percentage, personal rating, times read, and notes per book
- Per-user — each user has their own reading state and progress
- Set reading status individually or in bulk across selected books
- Register Kobo e-readers to your account
- Each device gets a companion smart shelf — books on the shelf sync to the device
- Incremental sync — only sends new or changed books each time
- Cover art served to the Kobo automatically
- EPUB and KEPUB format support with in-house EPUB-to-KEPUB conversion
- Reading position and progress synced between Kobo and BookBoss
- Reset sync state to force a full re-sync
- Copy device sync URL to clipboard from the profile page
- Kobo-initiated book removal handled with user-defined actions
- OPDS 1.x catalog server with Atom XML feeds
- Browse all books, by author, by series, or by shelf
- Search books via OpenSearch
- Per-user OPDS password (auto-generated, regeneratable from profile page)
- Compatible with any OPDS client (KOReader, Librera, Moon+ Reader, etc.)
- User registration and login
- Admin first-run setup
- Multi-user support — each user has their own reading state, shelves, and devices
- Virtual libraries — each user can maintain their own subset of books independent of other users
- Capability-based permissions (Approve Imports, Edit Book, Delete Book, OPDS Access)
- Genre and tag management with per-entry book counts
- Library management (admin)
- User management (admin)
- System messages log for background task diagnostics (admin)
- Health task dashboard showing scheduled task status with manual trigger support (admin)
- Admin setting to also create MOBI-format files
See the full documentation for detailed setup and usage guides.
- Install tools:
just install-tools - Configure:
just config(edit encryptedconfig.sops.env) - Create database:
just create-database - Run:
just run
The application will be available at http://localhost:8080 by default. On
first launch you will be prompted to create an administrator account.
Configuration is loaded from environment variables with the BOOKBOSS__ prefix:
| Variable | Purpose |
|---|---|
BOOKBOSS__DATABASE__DATABASE_URL |
SeaORM connection string (Postgres / MySQL / SQLite) |
BOOKBOSS__ENCRYPTION_SECRET |
Used for encrypting OPDS passwords in the database |
BOOKBOSS__LIBRARY__LIBRARY_PATH |
Where approved book files are stored |
BOOKBOSS__IMPORT__BOOKDROP_PATH |
Drop e-book files here to trigger the import pipeline |
BOOKBOSS__FRONTEND__LISTEN_IP |
Server listen address (default 0.0.0.0) |
BOOKBOSS__FRONTEND__LISTEN_PORT |
Server listen port (default 8080) |
BOOKBOSS__FRONTEND__BASE_URL |
Public base URL (default http://0.0.0.0:8080) |
BOOKBOSS__METADATA__HARDCOVER_API_TOKEN |
API token for Hardcover metadata provider |
BOOKBOSS__METADATA__GOOGLEBOOKS_API_TOKEN |
API token for Google Books metadata provider |
BOOKBOSS__OIDC__DISCOVERY_URL |
OIDC discovery URL (enables SSO when all 3 are set) |
BOOKBOSS__OIDC__CLIENT_ID |
OIDC client ID registered with the IdP |
BOOKBOSS__OIDC__CLIENT_SECRET |
OIDC client secret registered with the IdP |
BOOKBOSS__OIDC__BUTTON_LABEL |
SSO login button label (default: Sign in with SSO) |
Connection string formats:
postgres://user:password@host:port/database
mysql://user:password@host:port/database
sqlite:path/to/file.db
Secrets are encrypted with sops — never commit plaintext secrets.
When BOOKBOSS__OIDC__DISCOVERY_URL, CLIENT_ID, and CLIENT_SECRET are all
set, BookBoss enables an additional "Sign in with SSO" button on the login
page. Username/password login remains available regardless. Tested with
Kanidm.
Register BookBoss with your IdP using:
- Redirect URI:
<base_url>/auth/oidc/callback - Scopes:
openid email - Grant type:
authorization_code(with PKCE)
The IdP must release the email claim, and a BookBoss user must exist with
that exact email address (case-sensitive match).
For kanidm, I used the setup:
kanidm group create 'bookboss_users'
kanidm group add-members bookboss_users <user>
kanidm system oauth2 create bookboss '<machine>' <base_url>
kanidm system oauth2 set-landing-url bookboss '<base_url>/auth/oidc/callback'
kanidm system oauth2 update-scope-map bookboss bookboss_users email openid
kanidm system oauth2 enable-pkce bookboss
kanidm system oauth2 get bookboss
# Need to copy this secret to BOOKBOSS__OIDC__CLIENT_SECRET
kanidm system oauth2 show-basic-secret bookboss
- Rust 1.85+ (nightly toolchain for formatting/clippy)
- mise — manages tool versions
- just — task runner
- Node.js 24+ (for Tailwind CSS, managed by mise)
- An existing PostgreSQL or MySQL instance (for those database backends)
| Command | Description |
|---|---|
just build |
Build the project |
just run |
Run the application |
just fmt |
Format code (Rust + Prettier) |
just clippy |
Run Clippy lints |
just quick-test |
Component tests + Postgres/SQLite integration tests |
just test |
Run all tests |
just component-tests |
Unit/component tests only |
just integration-tests |
All integration tests (requires Colima) |
just insta |
Run snapshot tests with cargo-insta |
just docs-serve |
Serve documentation locally |
just deps |
Update Rust crate dependencies |
just changelog |
Regenerate CHANGELOG.md |
Integration tests use Docker containers managed by Colima:
colima start
just integration-tests
colima stopBookBoss follows hexagonal (ports & adapters) architecture. All dependencies point inward toward the core domain — the core crate has no knowledge of adapters.
crates/
├── core/ # Domain: business logic, models, port traits
├── api/ # Adapter: gRPC interface
├── database/ # Adapter: SeaORM persistence (Postgres / MySQL / SQLite)
├── formats/ # Adapter: e-book formats (EPUB, OPF, KEPUB conversion)
├── frontend/ # Adapter: Dioxus web UI, OPDS server, Kobo sync
├── import/ # Adapter: library scanner + import job handler
├── metadata/ # Adapter: external metadata providers (Hardcover, OpenLibrary, GoogleBooks)
├── storage/ # Adapter: local filesystem library store
├── utils/ # Shared utilities
├── bookboss/ # Binary: wires adapters to ports
└── integration-tests/
See the full documentation for architecture details and contributor guides.
MIT