BookOrbit: Self-Hosted Reading Platform with Three-Way Sync

What BookOrbit Manages and Who Needs It

BookOrbit organizes ebooks (EPUB, KEPUB, MOBI, AZW3, AZW, FB2), PDFs, comics (CBZ, CBR, CB7), and audiobooks (M4B, MP3, M4A, OPUS, OGG, FLAC) in a library you host on your own server. The problem it solves is fragmentation: progress made on one reading surface does not follow you to another unless something actively synchronizes it. BookOrbit handles that synchronization between its built-in web reader, Kobo e-readers, KOReader running on other devices, and a native iPhone app. Around that core it adds 14 metadata providers for enriching book records, reading statistics and achievements, multi-user accounts with OIDC and SSO support, and automated export to external services including Hardcover, Readwise, and StoryGraph. The intended user is a reader who owns a substantial ebook or audiobook library and is comfortable running Docker on a NAS, home server, or VPS.

Three-Way Sync: Web Reader, Kobo, and KOReader

The README describes the sync as bidirectional: progress and annotations flow from Kobo devices and KOReader into BookOrbit, and changes made in the BookOrbit web reader flow back out. Picking up on one surface where you left off on another, including highlights and deletions, is the stated goal. For KOReader users, BookOrbit ships an on-device plugin that provides a catalog browser with search, download, and status and rating management alongside full progress and annotation sync. Highlights gathered from the web reader, KOReader, and Kobo merge into one searchable hub; you can filter by color, style, and source, and export to Markdown, CSV, or JSON. Apple Watch support, added in v3.0.0, allows downloaded audiobooks to play independently offline with progress reconciliation when the watch reconnects. The sync extends to third-party services: Hardcover receives status, progress, reading dates, and ratings on configurable triggers; StoryGraph gets status and progress; and Readwise receives new highlights as you create them from both the web reader and synced devices.

Docker Compose Quick Start

The README provides a documented quick-start sequence. Create a working directory, download the example environment file and compose definition, then edit the required values:

mkdir bookorbit && cd bookorbit
mkdir -p books data/app data/postgres
curl -fsSLo .env https://raw.githubusercontent.com/bookorbit/bookorbit/main/.env.example
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/bookorbit/bookorbit/main/docker-compose.yml

The .env.example file shows the five required values:

APP_URL=http://your-server-ip:3000
BOOKS_HOST_PATH=./books

POSTGRES_PASSWORD=
JWT_SECRET=
SETUP_BOOTSTRAP_TOKEN=

The README recommends generating secrets with openssl rand -hex 24 (for the database password) and openssl rand -hex 32 (for JWT_SECRET). Then start the stack:

docker compose up -d

Open the server address in a browser and complete setup using the SETUP_BOOTSTRAP_TOKEN. The compose file shows that the app container runs as read-only with tmpfs for /tmp and drops all Linux capabilities except the minimum set needed to manage file ownership. On a NAS or any host where book files are owned by a user other than UID 1000, set PUID and PGID to match that owner.

Metadata Providers and Library Management

BookOrbit queries 14 metadata providers: Google Books, Open Library, Amazon, Goodreads, Kobo, Hardcover, Audible, Audnexus, Libro.fm, and iTunes for general titles, plus ComicVine for comics, RanobeDB for light novels, and Aladin and Lubimyczytac for Korean and Polish catalogs. Cover art comes from a separate set of sources including iTunes, DuckDuckGo, and AudiobookCovers. Smart Scopes let you build dynamic, rule-based saved filters; multiple libraries isolate content with per-library scan rules and format priorities. For hands-free importing, setting a Book Dock drop folder lets BookOrbit scan and ingest files automatically. OPDS support makes the library accessible from any OPDS-compatible reading app, and Send-to-Kindle delivery pushes files to a Kindle via email. The breadth of metadata providers is a concrete difference from simpler tools like Calibre, which has fewer built-in providers and requires plugins for many sources.

Reading Statistics, Goals, and Multi-User Support

BookOrbit tracks daily reading time, heatmaps, and streaks. It adds yearly goals, monthly challenges, and over 50 achievements across five categories. A Reading DNA feature profiles your reading style from your actual session history. For households or small teams sharing an instance, BookOrbit supports multi-user accounts with granular per-user permissions and isolated reading data. OIDC integration with Authentik, Keycloak, and Authelia is documented for SSO setups. The multilingual interface supports community-translated languages managed through Crowdin. These features place BookOrbit closer to a full reading management system than to a simple file server; they also mean the surface area for breakage after an upgrade is larger than a simpler self-hosted tool.

The iOS and Apple Watch App

The native BookOrbit app, available on the App Store, connects directly to a self-hosted BookOrbit server. It reads ebooks, PDFs, and comics; streams or downloads audiobooks; and supports text-to-speech and offline reading. The README states it requires BookOrbit v3.0.0 or later and iOS 26 or later. Apple Watch features require watchOS 26 or later. The watch app allows downloaded audiobooks to play without the iPhone present; progress reconciles when the devices reconnect. The app is distinct from the BookOrbit web reader: administrative features available in the web interface are not replicated in the app, and the demo instance notes some administrative features are limited in the public demo. The README does not document an Android app.

License Obligations and Practical Limits

BookOrbit is licensed under AGPL-3.0-only. That means anyone who modifies and runs the software as a network service must make the modified source available under the same license. For a private self-hosted instance with no external users this is rarely a concern, but organizations offering BookOrbit as a hosted service to others would need to publish their modifications. The ADDITIONAL_TERMS.md file in the repository modifies some terms; anyone deploying BookOrbit in a context that might trigger AGPL obligations should read both files. The project has no documented rollback procedure for failed upgrades. The README does not address database migration failures or how to restore from a backup after an upgrade goes wrong. The TTS (text-to-speech) feature is provided through an optional Kokoro sidecar container, which is not started by default; it requires adding the --profile tts flag to compose commands.

Editorial conclusion

BookOrbit suits readers who want a self-hosted alternative to cloud services like Kindle or Audible and who need progress sync across web, Kobo, KOReader, and iPhone. It is the wrong choice for anyone who cannot maintain a server, who needs an Android app (the README documents only iOS and Apple Watch clients), or who is not prepared for AGPL-3.0 obligations when building on top of it. Before deploying, verify that your book files are owned by UID 1000 or set PUID and PGID in the environment file; getting those values wrong is, according to the README, the most common cause of permission errors on first scan.

Frequently asked questions

Official sources

1. bookorbit/bookorbit on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases