bookorbit
Applicationbookorbit/bookorbit
Self-hosted library and reading platform for ebooks, PDFs, audiobooks, and comics.
Overview
BookOrbit organizes your book collection and provides web readers for ebooks, PDFs, comics, and audiobooks with progress sync across Kobo and KOReader. It includes metadata enrichment, OPDS delivery, multi-user support with OIDC, and runs on Docker.
README Preview
\n\n# BookOrbit\n\nA self-hosted library and reading platform for ebooks, PDFs, audiobooks, and comics.\n\n[](https://github.com/bookorbit/bookorbit/releases)\n[](https://github.com/bookorbit/bookorbit/stargazers)\n[](https://github.com/bookorbit/bookorbit/actions/workflows/ci.yml)\n[](https://github.com/bookorbit/bookorbit/actions/workflows/release.yml)\n[](https://codecov.io/gh/bookorbit/bookorbit)\n[](https://crowdin.com/project/bookorbit)\n\n[](https://bookorbit.app)\n[](https://demo.bookorbit.app/magic?token=2d92cb900e184cf0eb8b11f72cffc6011673d1016e1b300d750eb3d76abc1572)\n[](https://github.com/bookorbit/bookorbit/pkgs/container/bookorbit)\n[](https://github.com/bookorbit/bookorbit/blob/main/docs/CONTRIBUTING.md)\n[](LICENSE)\n\n\n\n\n\n---\n\n## What is BookOrbit?\n\n**[BookOrbit](https://bookorbit.app)** organizes your books and reads them back to you anywhere: the web reader, a Kobo, or KOReader. Progress, highlights, and reading status move between all three, so you can start a chapter in one place and finish it in another.\n\nAround that core sit 14 metadata providers, reading statistics and achievements, OPDS and Send-to-Kindle delivery, multi-user accounts with OIDC/SSO, and automatic sync out to Hardcover, Readwise, and StoryGraph. All of it runs on infrastructure you control.\n\n[](https://bookorbit.app)\n\n## Live Demo\n\nTry the live instance before you install. No account required.\n\n[](https://demo.bookorbit.app/magic?token=2d92cb900e184cf0eb8b11f72cffc6011673d1016e1b300d750eb3d76abc1572)\n\n> **Note:** The demo includes a sample library of public domain books. Some administrative features are limited in the public demo. Self-hosting BookOrbit provides the full experience.\n\n## Features\n\n### Reading Experience & Sync\n\n- **Built-in Web Readers**: Ebooks (EPUB, KEPUB, MOBI, AZW3, AZW, FB2), PDFs, comics (CBZ, CBR, CB7), and audiobooks (M4B, MP3, M4A, OPUS, OGG, FLAC), with no extra plugins required.\n- **Three-Way Sync (Kobo + KOReader + BookO
FAQ (5)
TroubleshootingWhy can't I scroll to the top of comic pages in BookOrbit mobile landscape with Page Width fit mode?
This was a bug in BookOrbit 3.1.0 affecting the mobile comic reader in landscape mode when using "Page Width" fit mode. It was fixed in BookOrbit 3.3.0. Upgrade your Docker deployment to 3.3.0 or newer, then recreate the container. As a temporary workaround, use portrait orientation or select a different page fit mode.
TroubleshootingWhy does the Bookshelf tab disappear from the KOReader file browser menu bar after installing the BookOrbit plugin?
BookOrbit's bookorbit_menu_pin.lua rewrites settings/reader_menu_order.lua and settings/filemanager_menu_order.lua on every startup with a full copy of KOReader's built-in menu order. KOReader's MenuSorter:mergeAndSort replaces each whole list instead of merging, so tabs other plugins add later (e.g. bookshelf_tab) get dropped. Disabling BookOrbit's menu icon or deleting the file won't help since it's regenerated each launch. Workaround: 1) Open koreader/settings/filemanager_menu_order.lua in a text editor. 2) Delete the first line (-- bookorbit-menu-pin v3 (generated; ...)) so BookOrbit stops regenerating the file. 3) In the ["KOMenu:menu_buttons"] list, add "bookshelf_tab", right after "filemanager_settings". 4) Restart KOReader — the Bookshelf tab will reappear.
TroubleshootingHow do I fix BookOrbit audiobook progress not resuming in the web app or iOS app after refresh?
This was a bug in BookOrbit 3.1.0 where audiobook progress was recorded but not used when reopening the player or syncing to the iOS app. It is fixed in BookOrbit 3.3.0. Upgrade your Docker deployment to 3.3.0, for example: docker compose pull bookorbit && docker compose up -d. If using a plain Docker container, pull the 3.3.0 image and recreate the container. After upgrading, start playback, leave the player, and reopen the audiobook to verify that playback resumes from the saved position.
TroubleshootingHow to fix BookOrbit books disappearing and appearing as duplicate missing entries after importing a second book via Book Dock?
This happens in BookOrbit v3.1.0 when a library uses **Folder as Book** with a **flat file-naming rule**. If multiple imported EPUBs land in the same directory—such as the library root—BookOrbit associates the second import with the first book's database record. A later library scan separates the physical files, restores the first book, and leaves a duplicate "missing" entry for the second book. Metadata edits can also be lost because the scan refreshes metadata from the original files.
Workaround:
1. Go to **Settings > Library** and edit the Folder-as-Book naming rule so each book gets its own subdirectory. Add a path separator, for example:
{title}/<{title}|{originalFilename}> - <{authors:first}> - <{year}>
2. For books already imported into the library root, move each book file into its own folder.
3. Run **Settings > Library > Scan**.
4. Delete the phantom "missing" duplicate entry and reapply any metadata changes that were lost.
Alternatively, if you want to keep books in a flat directory, configure the library as **File as Book** instead of Folder as Book.
TroubleshootingWhy does the BookOrbit web EPUB reader skip two pages per key press in v3.4.0?
This is a known bug in v3.4.0 (Docker latest): in 'Pages' reading flow, a single ArrowRight keydown (or click-to-turn) advances ~0.3% of the book, i.e. about two screen pages, regardless of viewport width or column layout. Workaround: switch the reader's 'Reading flow' setting from 'Pages' to 'Scroll', which restores correct navigation. The bug affects EPUBs generally (reproduced with Standard Ebooks builds) on Windows/Chrome and is unrelated to key repeat or two-column spreads.