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 server | On Zenith | |
|---|---|---|
| Database | Postgres 16 or newer with the vector, uuid-ossp, pg_trgm and unaccent extensions | Included |
| Secrets | Generate JWT_SECRET, a setup token and encryption keys, and keep them across upgrades | Included |
| Web address | A domain, a reverse proxy, HTTPS, APP_URL and forwarded headers. Kobo sync fails if any of them disagree | Included |
| First sign-in | Create the admin account with the setup token | Included |
| Configure an SMTP provider | Included | |
| Read-aloud | Run the read-aloud worker as a second container | Included |
Deploy BookOrbit
- Payment confirmed
- Address reservedbooks-alex.zh.run
- Starting app
- Checking availability
- 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
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
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
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
- 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/booksis kept on your storage, so don't pick a folder anywhere else./books/ebooks - 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
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
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.
- 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
Point the Kobo at your library
Connect the Kobo to your computer by USB and open
.kobo/Kobo/Kobo eReader.conf. The.kobofolder is hidden on macOS and Linux. Under[OneStoreServices], replace theapi_endpointline with your sync URL. Keep a singleapi_endpointline and don't add quotes.[OneStoreServices] api_endpoint=https://books-alex.zh.run/api/v1/kobo/<your-device-token> - 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
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
Install the plugin
Click Download Plugin. The zip already contains your address and login. Unzip it, copy
bookorbit.kopluginintokoreader/pluginson the device, and restart KOReader. - 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.