Installing BookOrbit (from GitHub) with Portainer

[u100009]

TL;DR: setup of BookOrbit library management platform on Synology NAS with the help of Portainer.

Hi all,
This will be my very first post on the SynForum since I've been using my Synology NAS (DS1520+).

I've been using Calibre Desktop for quite a few years and was looking for something I could access easily from multiple devices and locations. Calibre lacks a good sync option for books and annotations, and though it has its own sync server, this only works mildly well.. I wanted something I could universally switch from one device to another and not have to worry whether my books were loaded or synced on that device. As I've been using Android phones, e-ink tablets (Android based too and Kobo readers), I was focusing on something that works also with KOReader, the open source ebook reader. I've failed to get KOReader work consistently and reliably on my Kobo device, as it required hacks to get it installed, and every once in a while, it would screw up my book database. I wanted also something that can sync and update books OTA, not having to plug a cable to load new books when added to my library..
In that sense, Calibre was doing a nice job with the Wireless server to transfer books, but it had to be repeated for each book and didn't work with Kobo's native reader.

I then came across recently to a Reddit post about BookOrbit, a whole new selfhosted library management system for not only ebooks, but also audiobooks, PDF's, comics, etc.. and it promised to resolve all the painpoints from other selfhosted systems which I had tried (and failed) to use in the past. I had tried Kavita and CWA (Calibre Web App), but didn't like them, despite the fact that CWA would somehow resolve the Kobo issue with wireless transfer, as it allowed to server as OPDS catalog. But there was no sync for the reading stats and progress..

So, BookOrbit promised all this, but here is the catch: the provided instructions on the GitHub site were not working with my Synology Container Manager, nor was I able to get a ready-to-use image from the registry to work, as it came with zero instructions on how to configure... I spent a solid 3-4 hours with the help of Gemini to try to get this working but kept runing into timeout issues or rejected connections from the Node.js component.

It took me not less than 16 different docker.compose.yml files to finally get a working container for BookOrbit and be able to login into the web interface. So far, the configuration allows me to login from my local network, but I plan at some extend to be able to access it from the outside with a VPN or some port redirections.

The biggest issue was the network isolation as BookOrbit required a Postgres SQL DB to be created (I didn't wanted this to hook up to any other existing PG DB as I wanted this to be as much isolated as possible), that's why it tooks so many trial & errors before getting there.

The code below I simple used in Portainer to create a new Stack (I named it bookorbit, but you can use the name you want) and then simply ran the deployment. It took a few minutes and was then able to connect to the HTML URL (you need to replace http://<YOUR_NAS_IP>:3000 with your real IP address).

The secret was to use a local loop address to bypass some Synology FW blocking (at least according to Gemini (?)) that prevented the container to connect to the PG database endpoint..

I'm looking forward to testing the new BookOrbit (GitHub - bookorbit/bookorbit: BookOrbit: Your Reading Space ) library which really seems to be a nice UI (you can have a glimpse at the demo page : BookOrbit )

Hope this helps someone else get up more quickly with BookOrbit.
Enjoy!

version: "3.8"

services:
  postgres-core:
    image: pgvector/pgvector:pg16
    container_name: bookorbit-db-core
    restart: unless-stopped
    user: "0:0"
    environment:
      - POSTGRES_USER=orbituser
      - POSTGRES_PASSWORD=mysecurepassword123
      - POSTGRES_DB=orbitdb
    ports:
      - "5449:5432"  # Changes external database port to avoid Synology conflicts
      - "3000:3000" # <-- This line opens port 3000 to your Synology network!
    volumes:
      - pgdata_core:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U orbituser -d orbitdb"]
      interval: 3s
      timeout: 3s
      retries: 5

  bookorbit:
    image: ghcr.io/bookorbit/bookorbit:latest
    container_name: bookorbit
    restart: unless-stopped
    network_mode: "service:postgres-core"
    environment:
      - APP_URL=http://<YOUR_NAS_IP>:3000
      - DATABASE_URL=postgres://orbituser:[email protected]:5432/orbitdb
      - JWT_SECRET=2df149b5c2a382e75a092bf25bbf893e4bfd7bbf8664ea65cda28efb36bcfaef  # <-- it is important that is a generated 64 bit hash key (see official guide for that)
      - SETUP_BOOTSTRAP_TOKEN=MySuperSecureToken123!
    volumes:
      - /volume4/docker/bookorbit/config:/config
      - /volume3/Book-library/BookOrbit:/books
    depends_on:
      postgres-core:
        condition: service_healthy

volumes:
  pgdata_core:
    driver: local

This post includes affiliate links. As an Amazon Associate, SynoForum.com may earn a commission if you make a purchase — at no extra cost to you.
It helps support our community! Learn more...

 

[u100009]

Addenda #1:
Though my BookOrbit web server was working and I managed to setup a new user account, the creation of the first library would not allow me to scan any books... some how it was returning an error in the Portainer log:

hostname=1ac2e1e728cb req={"id":"req-2p","method":"POST","url":"/api/v1/scanner/libraries/1/scan"} context=ScannerService msg=[scanner.walk_candidates] [fail] libraryId=1 path="/books" error="Permission denied reading folder, skipping: /books" - candidate walk warning

It seems that the /books folder in the container folder would not have the necessary permissions to grant a proper access to BookOrbit to read & write data into it. This command would fix it, plus some File Station permissions validation.

chown -R 1000:1000 /books && chmod -R 777 /books

After re-scanning the library, the books started to show up and I was in business.

 

[one-eyed-king]

chown -R 1000:1000 /books && chmod -R 777 /books

The chmod command would have been enough. What you did is the opposite of a "least priviliges" approach.

After re-scanning the library, the books started to show up and I was in business.

And now check /volume3/Book-library/BookOrbit on the NAS and see whether the data is persisted there or not.

 

[Telos]

While a "pretty" app, realize that this is heavily AI coded. Tested on my RPi, and abandoned.
BTW, compose is somewhat outdated. Ex., version is deprecated.

Also should be:

image: pgvector/pgvector:pg18, and...
- pgdata_core:/var/lib/postgresql/

Permissions messed per OEJ comment.

Apart from "pretty" this is stripped away calibre.