Kobo, KOReader, and web progress share one record
BookOrbit catalogs ebooks, PDFs, comics, and audiobooks, supplies built-in readers, and gives each user private progress and history. Its defining feature is three-way continuity among the web app, Kobo devices, and KOReader. Highlights, annotations, deletions, and reading position can move between surfaces instead of staying on the device that opened the file.
That device story is the reason to choose BookOrbit over a generic OPDS server. The KOReader plugin can browse and search the catalog, download books, update ratings, and exchange progress and annotations. Kobo support also synchronizes reading state. If you alternate between a Kobo at night, KOReader elsewhere, and a browser at work, the server addresses a specific nuisance.
The rest of the product is broad. It offers 14 metadata providers, multiple libraries, smart collections, OPDS, Send-to-Kindle, drag-and-drop upload, reading statistics, goals, achievements, and per-user permissions. OIDC integrations cover Authentik, Keycloak, and Authelia. Hardcover, StoryGraph, and Readwise connections can send selected reading data to outside services.
What happened when we ran it
Our sandbox installed commit 5ec34ae in 20 seconds. Pnpm added 1,641 packages and used 1,187 MB on disk. The root workspace had no build script or target, so the harness skipped that step rather than inventing a command. We used Node 22 in an unprivileged Debian container with 3 CPUs, 8 GB of RAM, and no secrets.
Vitest exited 1 after 425 seconds. It reported 10,645 passed, 15 failed, and 8 skipped out of 10,668 tests. The final log repeatedly names calibre-web-automated-snapshot.connector.test.ts, then reports a recursive server test failure. The supplied tail does not show the assertions, expected values, or cause, so we cannot say whether fixtures, environment, or code caused those 15 failures.
The checkout was 93.1 MB with 3,657 files and about 573,304 source lines. It has 10 CI workflow files, a Dockerfile, Compose, and monorepo workspaces, though no top-level tests directory. No dependency-audit result was supplied. Installation was quick for 1,641 packages; the 425-second verification loop was not clean.
Compose needs 3 secrets and correct library ownership
The official quick start creates books, application-data, and PostgreSQL directories, then downloads .env and docker-compose.yml. Required configuration includes POSTGRES_PASSWORD, JWT_SECRET, and SETUP_BOOTSTRAP_TOKEN, plus the application URL and mounted books path. The setup wizard runs after both containers are healthy.
NAS permissions are the predictable trap. The README calls incorrect PUID and PGID values the most common cause of first-scan permission errors when media is not owned by UID 1000. Reverse proxying, HTTPS, external databases, and OIDC sit beyond the short path. Backing up only the books misses PostgreSQL and app state; backing up only the database misses the media.
The AGPL-3.0 license suits a community-hosted service. A company that modifies BookOrbit and provides it over a network should review the source-offer obligations. Home users will care more about storage ownership, secret rotation, database upgrades, and whether a restore keeps device sync identities intact.
A changed book file can retain the old KOReader hash
Open issue 926 describes a central sync edge case. After a book is edited outside BookOrbit, such as a Calibre metadata or cover change, a rescan can update size and modification time while leaving the old file hash. KOReader calculates the new file's hash and then reports that the book is absent from the BookOrbit library.
That report is specific enough to build an acceptance test: copy a book into a trial library, download and sync it, alter the file externally, rescan, download again, and verify progress plus annotations. Do this before letting BookOrbit become the sole record for a library that Calibre or another tool continues to edit. A current backup cannot prevent a mismatched identifier, but it makes recovery less frightening.
Release v2.7.0 fixed another history problem: rebuilding a library no longer silently drops KOReader device history, according to the release notes. It also lets an operator retire a device without erasing its synced data. Those repairs show active attention to the core workflow, while issue 926 remains a reason to test external edits.
Book Dock and Grimmory migration need manual audits
Book Dock watches a folder for automated intake. Issue 967 reports finalized books that do not appear until a manual scan, followed by duplicate-looking missing entries or removed metadata. The report uses version 2.5.0 and remains open. Large imports should begin with a representative batch, then compare file paths, editions, covers, series order, and metadata before scaling up.
Issue 1055 is narrower. In version 2.6.0, a Grimmory migration can validate its media path, finish with 0 failures, and still skip every matched cover because one executor recognizes only the booklore source type. The report includes a BookLore-type workaround, but a green status with 0 imported covers is precisely why migration results need item counts and visual checks.
Version 2.7.0 adds Audiobookshelf and Calibre-Web Automated imports, yet our 15 failing tests are in the latter snapshot connector. The test log does not prove migration is broken for users. It does justify testing a stopped snapshot with copied data and checking matched books, reading state, covers, and the final report before deleting the source system.
August 26 activity comes with a 300-item queue
GitHub recorded the last push on August 26, 2026. Release v2.7.0 arrived on August 23, and the repository showed 3,261 stars with 300 open issues and pull requests combined. The release also fixes Kobo sync retries, metadata merges, scanner path identity, permissions, and reading-history handling. This is a busy active project, not a settled appliance.
BookOrbit earns a trial for households that will use its cross-device state, not merely its cover grid. Start with copied media and separate credentials, then rehearse a database-plus-media restore. A passive Calibre archive or audiobook-first household can choose a narrower server and avoid many of these synchronization decisions.