Skip to content

BookOrbit

How to deploy BookOrbit

Put your BookOrbit library online with Kobo and KOReader sync working from anywhere. There is no Docker, Postgres or reverse proxy to set up.

· $10 a month · 50 GB for books · Kobo, KOReader and OPDS

The short version

Deploy it on Zenith if

  • You want Kobo or KOReader to sync away from home. That needs a public HTTPS address.
  • You don't want to run Docker, Postgres with pgvector, and a reverse proxy.
  • Your library fits in 50 GB, or you can upload it.

Run it yourself if

  • Your books already sit on a home server and you want BookOrbit to read that folder in place.
  • Your collection is much bigger than 50 GB.

What you skip

BookOrbit's own install guide runs it with Docker Compose. These are the parts Zenith already handles.

On your own serverOn Zenith
DatabasePostgres 16 or newer with the vector, uuid-ossp, pg_trgm and unaccent extensionsIncluded
SecretsGenerate JWT_SECRET, a setup token and encryption keys, and keep them across upgradesIncluded
Web addressA domain, a reverse proxy, HTTPS, APP_URL and forwarded headers. Kobo sync fails if any of them disagreeIncluded
First sign-inCreate the admin account with the setup tokenIncluded
EmailConfigure an SMTP providerIncluded
Read-aloudRun the read-aloud worker as a second containerIncluded

Deploy BookOrbit

Choose where BookOrbit lives.
You can connect your own domain later.
-alex.zh.run
Lowercase letters, numbers, and hyphens · up to 32 characters
Checking availability
Use this address
Deploying BookOrbit
  1. Payment confirmed
  2. Address reservedbooks-alex.zh.run
  3. Starting app
  4. Checking availability
BookOrbit is live.
Your address is answering and the app is already set up.
Open BookOrbitGo to dashboard
  1. 1

    Click Deploy now on the BookOrbit page

    Open BookOrbit in the catalogue and click Deploy now. It costs $10 a month. Pay by card, or with Apple Pay or Google Pay where your browser offers them. If you don't have a Zenith account yet, you create one after paying.

  2. 2

    Choose an address

    Pick a name for your library. Use lowercase letters, numbers and hyphens, up to 32 characters. Your address becomes the name, a hyphen and your username, ending in .zh.run. Click Use this address.

  3. 3

    Wait for BookOrbit to go live

    A checklist shows payment, address, start-up and the availability check. When it reads BookOrbit is live, click Open BookOrbit.

  4. 4

    Sign in with Zenith

    Choose Zenith on the BookOrbit sign-in page. Your Zenith account is already the BookOrbit administrator, so there is no setup token or first-run wizard.

Add your books

Fiction
MiddlemarchEPUB
The OdysseyEPUB
Drop books hereEPUB, PDF, MOBI, AZW3, CBZ, M4B
Middlemarch.epub
The Odyssey.epub
View in Library
  1. 1

    Create your first library

    On the BookOrbit dashboard, click Create your first library. Give it a name and an icon, then add a folder inside /books, such as /books/ebooks. Only /books is kept on your storage, so don't pick a folder anywhere else.

    /books/ebooks
  2. 2

    Choose how files become books

    Pick Folder as Book if each book has its own folder, which is how Calibre stores them. Pick File as Book if all the files sit in one folder. You can't change this later. Click Create library.

  3. 3

    Upload a few books

    Click the Upload icon in the top bar and drop in EPUB, PDF, MOBI, AZW3, comic or audiobook files. Each file can be up to 500 MB. BookOrbit reads the title, author and cover in the background.

  4. 4

    Connect your library folder

    For a big collection, mount the library on your computer. Open BookOrbit in your Zenith dashboard, go to Files, then Protocols, and click Show connection details. Pick WebDAV, SMB or SFTP for Book library and copy the address. Connect with Go > Connect to Server in Finder or Map network drive in Windows, using the username and password shown. The same login works for every protocol. Copy your book folders in, then click Scan next to the library in BookOrbit under Settings > Libraries.

Sync your Kobo

BookOrbit sends books to a Kobo and syncs reading progress and highlights back. Only EPUB books sync.

Kobo eReader.conf
41
42
43[OneStoreServices]
44api_endpoint=https://storeapi.kobo.com
45
46
47
48
49
50
51
52
53
Settings/Kobo
Kobo Libra 2No books yetWaiting
  1. 1

    Pair a device in BookOrbit

    In BookOrbit, open Settings > Kobo, add a device and name it. BookOrbit shows a sync URL only once, so copy it now. It works like a password.

  2. 2

    Point the Kobo at your library

    Connect the Kobo to your computer by USB and open .kobo/Kobo/Kobo eReader.conf. The .kobo folder is hidden on macOS and Linux. Under [OneStoreServices], replace the api_endpoint line with your sync URL. Keep a single api_endpoint line and don't add quotes.

    [OneStoreServices] api_endpoint=https://books-alex.zh.run/api/v1/kobo/<your-device-token>
  3. 3

    Choose which books go to the Kobo

    Add books to a collection and turn on Sync to Kobo for it. Eject the Kobo, connect it to Wi-Fi and tap sync. Collections show up on the Kobo as tags.

Sync KOReader

  1. 1

    Create a KOReader login

    In BookOrbit, open Settings > KOReader and create a username and password. This login is separate from your Zenith sign-in.

  2. 2

    Install the plugin

    Click Download Plugin. The zip already contains your address and login. Unzip it, copy bookorbit.koplugin into koreader/plugins on the device, and restart KOReader.

  3. 3

    Turn on sync

    Open a book and go to Tools > BookOrbit Sync. Turn on Two-way highlight sync if you want highlights to move in both directions.

Browse from other reading apps

Apps such as Thorium Reader and Moon+ Reader can browse your library over OPDS. In BookOrbit, open Settings > OPDS, turn on the catalog server and create an OPDS account. Add the feed URL to your app and sign in with that account using Basic authentication.

Common questions

What happens to my Kobo if I add my own domain later?
BookOrbit switches its address to your domain. Pair the Kobo again from Settings > Kobo so the api_endpoint uses the new address.
How much space do I get?
50 GB.