User Guide

Libris is a self-hosted book management system. It ingests EPUB files, enriches their metadata from Hardcover, organizes them into a structured library, serves them to e-readers via an OPDS catalog, and syncs your reading progress with KoReader. Everything runs on your own hardware -- no cloud accounts required beyond an optional Hardcover API token for metadata enrichment.

This guide walks through every part of the app, from first login to tracking your reading stats.

Initial Setup

When you start Libris for the first time, there are no accounts or API keys yet. The app redirects you to the Settings page and prompts you to create your first API key.

Enter a label for the key (e.g., "Web UI") and click Run Setup. A modal appears with your new API key -- copy it and store it somewhere safe. This is your only chance to see the raw key.

WARNING

The API key cannot be retrieved later. If you lose it, you will need to create a new one from the database.

After dismissing the modal, paste the key into the login form to authenticate. The app stores a session cookie so you stay logged in across visits.

TIP

The browser never sees your raw API key after login. Libris uses a Backend-for-Frontend pattern where the session cookie is exchanged for an authorization token server-side, keeping your key secure.

Multi-User Support

Libris supports multiple users, each identified by their own API key. The first key created during setup is automatically marked as admin.

Admin vs Regular Users

• Admin users can manage API keys (create, revoke), view system health, manage job queues, and see all server configuration.
• Regular users can browse and manage their own books, set up their own OPDS and KoSync credentials, and connect their own Hardcover account.

Each user's data is scoped to their API key -- books, reading progress, service credentials, and uploads are all isolated.

Creating Additional Users

From the Settings > API Keys tab, admins can create new keys for other users.

Give the new key a descriptive label (e.g., the person's name), then share the generated key with them. They log in by pasting the key on the Settings page, just like the initial setup.

Settings & Configuration

The Settings page is where you connect external services, check server health, and configure file paths. Admin users see seven tabs: Connections, API Keys, System, Jobs, Failed Jobs, Queues, and Paths. Regular users only see the Connections tab.

Connections

The Connections tab is where you wire up the services that make Libris useful beyond basic file storage.

OPDS Catalog -- This is how your e-readers access your library. The catalog URL and credentials are displayed here. You can set a dedicated username and password for OPDS clients, or leave them empty to fall back to API key authentication. Point your reader (KOReader, Calibre, Marvin, etc.) at the catalog URL shown on this page.

KoSync (Reading Progress) -- KoSync syncs your reading position across KoReader devices and back into Libris. The server URL is shown here, and you can set a username and password that your KoReader devices will use. In KOReader, go to Settings, then Cloud sync, then Progress sync, and select Custom server, entering the URL from this page.

Hardcover -- If you use Hardcover, you can connect your account by entering your API token. Libris will use Hardcover as a metadata source during ingestion and can sync your reading status to your Hardcover profile daily. Once connected, your username and connection status appear here. Hardcover tokens are stored with reversible encryption (AES-256 via Iron seal), so they are safe even if someone accesses the database.

TIP

Each user connects their own Hardcover account independently. Your Hardcover token is scoped to your API key and not visible to other users.

API Keys (Admin Only)

The API Keys tab lets admins manage all keys on the server. You can see each key's label, creation date, and admin status. Create new keys for additional users or revoke keys that are no longer needed.

System (Admin Only)

The System tab gives you a health check dashboard. You can verify that the database, Redis, and event bus are connected and see latency for each. Below that, the Job Queues section shows a breakdown of all background processing queues -- how many jobs are waiting, active, completed, failed, delayed, or paused.

This is the first place to look if something seems stuck. If a queue shows failed jobs, switch to the Failed Jobs tab to see error details and retry individual jobs.

Paths (Admin Only)

The Paths tab shows the library and inbox directories configured on the server. These are set via environment variables at deployment time and displayed here for reference.

The inbox path is where new book files land before processing. The library path is where organized books are stored in an Author/Title/ folder structure.

Adding Books

There are two ways to get books into the system.

Drop Files into the Inbox Folder

The simplest method: copy ebook files directly into the inbox folder on the server's filesystem. Libris watches this directory with a file watcher and automatically picks up new files. As soon as a file lands in the inbox, the ingestion pipeline kicks off -- computing checksums, detecting format, extracting embedded metadata, and querying external sources.

This approach works well if you have SSH access to your server or mount the inbox directory via NFS, SMB, or similar.

Upload Through the Web UI

From the Inbox page, click the Upload button in the top bar. A modal appears with a drag-and-drop zone where you can drop files or click browse to select them from your computer.

Only EPUB files are supported, with a maximum size of 100 MB per file. After uploading, the file enters the same ingestion pipeline as inbox-dropped files.

Inbox & Metadata Review

The inbox is the staging area where books live while their metadata is being gathered and reviewed. Every book passes through the ingestion pipeline before it reaches your library.

The Ingestion Pipeline

When a new file is detected, it moves through these stages automatically:

1. Detected -- The file is checksummed, its format is identified, and a database record is created. Duplicate files are caught here.
2. Parsed -- Metadata is extracted from the EPUB file (Dublin Core).
3. Metadata Fetched -- Hardcover is queried (if an API token is configured). Results are stored as metadata candidates.
4. Review -- The book is ready for you to review and approve.

If Libris cannot extract usable metadata from an EPUB -- for example because the file is corrupt or the embedded metadata is empty -- it will still move the book into Review, but without querying external sources using a junk fallback search. In that case, the review page will prompt you to enter metadata manually.

Inbox List

The inbox list shows all books currently being processed, along with their cover, title, format, status, and detection date. You can search, sort (newest or oldest first), and see at a glance which books need your attention.

Books with a Review status badge are waiting for you to pick their metadata and approve them.

Reviewing Metadata

Click on any book in the inbox to open the review page. This is where the metadata picker lets you build the best possible record for each book by combining information from multiple sources.

At the top of the page, you see the book's cover (if one was found), its current title and author, who uploaded it, the attached file, and how many metadata sources were found.

Below that, the Select Metadata section presents every field -- title, author, publisher, year, ISBN-10, ISBN-13, description, cover image, genres, series, and more. For each field, you see candidates from different sources:

• File -- Metadata extracted directly from the ebook file. Shown with a confidence percentage.
• Hardcover -- Data from the Hardcover API, also with a confidence score.
• Manual -- A free-text input where you can type any value yourself.

Select the best value for each field by clicking the radio button next to it. The currently selected option is highlighted. You can mix and match freely -- pick the title from the file, the author from Hardcover, and type in the genres manually.

When you are satisfied with your selections, click Approve in the top-right corner. The book is then organized: files are moved to the library in an Author/Title/ folder, the cover image is downloaded, approved metadata is embedded into the EPUB file, and the book becomes part of your library.

For damaged or metadata-empty EPUBs, you may see a manual-review warning and no suggested sources. That is intentional: Libris avoids attaching unrelated external metadata when it does not have enough trustworthy information to search.

If the metadata results look wrong or incomplete, click Rescan to re-query external sources. You can also delete the book from the inbox if it is not something you want to keep.

Library

Once a book is approved, it appears in your library. The library page offers two views and several ways to find what you are looking for.

Grid View

The default grid view displays book covers with the title and author underneath, plus compact language and uploader badges when that metadata is available. This is the most visual way to browse your collection.

List View

Toggle to list view for a compact table showing title, author, language, format, genres, uploader, and the date the book was added. This is useful when you have a large library and want to scan quickly.

Filtering and Search

The toolbar at the top of the library keeps search, sort, and view switching visible, and moves faceted filtering into a dedicated Filters panel. From there you can narrow the library by:

• Author filter -- Narrow results to a specific author.
• Genre filter -- Filter by genre.
• Language filter -- Filter by language code such as en or fr.
• Series filter -- Filter by series.
• Uploaded by filter -- Filter by the API key label of the uploader.
• Sort -- Sort by title (A-Z or Z-A), author, or date added.
• Search -- Full-text search across titles, authors, and other metadata. The search is typo-tolerant, so close matches still surface results.

Any active filters appear as removable chips above the results so you can see the current slice at a glance.

There is also a global search available from anywhere in the app via Ctrl+K (or the search button in the sidebar), which searches across both the library and navigation links.

Book Details

Click on any book in the library to open its detail page. This is the central hub for everything about a specific book.

The detail page shows:

• Cover image on the left.
• Title and author prominently at the top.
• Uploader attribution so you can see which API key label originally added the book.
• Genres as tag badges below the title.
• Details grid -- publisher, published year, language, page count, ISBN-13, ISBN-10, organized date, and added date.
• Reading Progress section showing sync data from KoReader (more on this below).
• Files section listing each file attached to the book, with format, size, and a Download button.

Actions Menu

The three-dot menu in the top-right corner of the detail page opens a dropdown with four actions:

• Edit metadata -- Opens a modal where you can manually edit every field.
• Refetch metadata -- Queries Hardcover again for updated metadata.
• Re-organize -- Moves the book's files to match the current title and author (useful after editing metadata).
• Delete -- Permanently removes the book and its files.

Editing Metadata

The Edit Metadata modal gives you direct control over every field: title, author, description, publisher, published year, language, page count, ISBN-10, ISBN-13, series, series number, genres (comma-separated), and tags.

After saving, the book's detail page updates immediately. If you changed the title or author, you may want to use Re-organize from the actions menu to update the folder structure on disk.

Reading Progress

When KoReader syncs progress via KoSync, the Reading Progress section on the detail page shows a progress bar with the device name (e.g., "KOReader Kindle"), the current percentage, the reading status, and when the last update happened.

Refetch Metadata

Sometimes you want to update a book's metadata after it is already in your library -- perhaps a new edition was published, or you want to pull in a better description or cover image. The Refetch Metadata workflow handles this without disrupting the book's place in your library.

Starting a Refetch

From the book detail page, open the actions menu and select Refetch metadata. A confirmation dialog explains what will happen: the app will query Hardcover for this book and let you review the results.

Click Fetch metadata to start. The dialog shows a loading state while the external APIs are queried.

Picking Updated Fields

Once results are back, the picker appears. It works just like the inbox review picker, but with one key difference: the first option for each field is Current, which represents the book's existing metadata. New candidates from Hardcover appear below.

Each source shows a confidence percentage. For every field, pick the value you prefer -- keep the current one, switch to an external source, or type a manual override. The Apply button at the bottom shows how many fields will be updated.

After applying, the book's metadata is updated in place. If the title or author changed, the book's files are automatically re-organized into the correct folder on disk.

Reading Progress & Stats

Libris tracks your reading progress automatically through KoReader's KoSync protocol. There is nothing to do manually -- just read on your KoReader device and progress syncs in the background.

How It Works

KoReader sends your reading position to the KoSync server built into Libris. The app derives your reading status from this data:

• Reading -- You have progress between 0% and 100%.
• Finished -- Progress reached 100%.
• Unread -- No progress recorded yet.
• Paused -- No progress update for a while.

Reading Status Page

The Reading page in the sidebar lets you browse your library filtered by reading status. Tabs across the top switch between Reading, Finished, Unread, and Paused. Each book shows its cover, progress percentage, the device it was last read on, and how recently it was updated.

The sidebar also shows count badges next to each status, so you can see at a glance how many books are in each state.

Stats Page

The Stats page provides reading analytics with several summary cards at the top: books finished (all time, this year, this month), your current reading streak and longest streak, and average time to finish a book.

Below the summary cards:

• Pages Read (Last 30 Days) -- A chart showing your daily reading activity.
• Genres (Finished Books) -- A color-coded bar chart breaking down the genres of books you have completed.

Hardcover Sync

If you have connected your Hardcover account in Settings, Libris syncs your reading status with Hardcover automatically once per day. You can also trigger a manual sync from the Hardcover section on the Connections settings tab.

The sync is bidirectional for status:

• Libris → Hardcover -- as you read in KOReader (or anywhere that reports back via KoSync), Libris computes your status (reading / finished / paused) and pushes it to Hardcover.
• Hardcover → Libris -- when you connect a Hardcover account, Libris pulls your existing statuses for any matched book and uses them as a fallback for books with no local reading data. This means a fresh Libris install with a large existing Hardcover library will immediately show your reading state across the library view, without you having to re-mark anything.

If you manually set a status on a book in Libris (from the book detail page), that override always wins locally until you clear it. Hardcover's "Did Not Finish" maps to Libris "paused".

Dashboard

The home dashboard gives you an at-a-glance overview of your entire library and reading activity.

At the top, four stat cards show:

• Total Books -- The number of organized books in your library.
• Awaiting Review -- How many inbox books need your attention.
• Processing -- Books currently moving through the ingestion pipeline.
• Library Size -- Total disk space used by your library files.

Below the stats:

• Currently Reading -- Books you are actively reading, showing cover thumbnails, progress bars with percentages, the device name, and when the book was last read. Click any book to jump to its detail page.
• Recently Added -- The latest books added to your library, displayed as cover cards. Click "View all" to go to the library.
• Pipeline Status -- Alerts for any failed jobs in the ingestion pipeline, with a direct link to view and retry them.

OPDS Catalog

Libris includes a built-in OPDS catalog server, which means any OPDS-compatible e-reader app can browse and download books directly from your library. This is one of the most useful features for day-to-day reading.

Supported Readers

Any app that supports OPDS feeds will work, including:

• KOReader -- Open-source reader for Kindle, Kobo, Android, and more.
• Calibre -- Desktop library manager with OPDS browsing.
• Marvin -- iOS reading app.
• Moon+ Reader, FBReader, and many others.

Connecting a Reader

1. Go to Settings > Connections in the Libris web UI.
2. Note the Catalog URL shown in the OPDS section.
3. Set a dedicated username and password for OPDS access.
4. In your reader app, add a new OPDS catalog and enter the URL and credentials.

What You Can Browse

The OPDS catalog supports:

• All books -- A paginated feed of your entire library.
• Recently added -- New additions to your library.
• By genre -- Browse books grouped by genre.
• By author -- Browse books grouped by author.
• Search -- Full-text search from within your reader app.

Books are available for direct download from the catalog in their original format. The same credentials apply to both browsing and downloading -- e-readers send them automatically on every request.

TIP

Each user has their own OPDS credentials. In a multi-user setup, each person sees only the books in their own library.

Keyboard Shortcuts

Libris includes keyboard shortcuts for quick navigation:

Shortcut	Action
Ctrl+K	Open global search
G then H	Go to Home
G then I	Go to Inbox
G then L	Go to Library
G then S	Go to Settings
Escape	Back to parent page