Skip to content

KOReader E-Reader OPDS Sync over Tailscale

Complete guide for configuring Calibre-Web's OPDS 1.2 catalog feed and integrating KOReader on e-ink devices over an encrypted Tailscale mesh network.

1. System Architecture

flowchart LR
    subgraph EReader ["E-Ink Client (KOReader)"]
        KO["📖 KOReader OPDS Client"]
    end

    subgraph TailscaleMesh ["Tailscale Encrypted Mesh"]
        TS["Tailscale WireGuard Engine (MagicDNS: 'homelab')"]
    end

    subgraph Host ["Ubuntu Homelab Server"]
        CW["📚 Calibre-Web Container (:8083)"]
        DB[("metadata.db (Calibre SQLite)")]
        Storage["/srv/storage/media/books\n(EPUB Library)"]
    end

    KO -->|HTTP Basic Auth over Tailscale| TS
    TS -->|WireGuard Tunnel| CW
    CW --> DB
    CW --> Storage
  • Catalog Standard: OPDS 1.2 (Open Publication Distribution System) Atom XML standard.
  • Authentication Strategy (Option A): HTTP Basic Auth with a dedicated reader account. Entered once in KOReader and cached permanently on device.
  • Zero-Idle Baseline: Calibre-Web runs 24/7 with a lean memory footprint (~60–100 MB RAM, ~0% idle CPU).

2. Server Configuration (Calibre-Web)

First-Time Initialization

  1. Ensure your library database (metadata.db) is present: 
    make init-calibre-db
  2. Start the core stack or Calibre-Web container: 
    make up
# or single service:
docker compose up -d calibre-web
  3. Open http://<server-ip>:8083 in your browser.
  4. In the initial setup prompt, confirm Location of Calibre database is /books and click Save.
  5. Log in with the default administrator credentials:
  6. Username: admin
  7. Password: admin123 (Immediately update your admin password under the profile icon).

To preserve separate reading progress, custom shelves, and prevent accidental catalog edits from e-ink screens: 1. Go to Admin → Add User. 2. Set: * Username: reader * Password: A simple, memorable passcode (e.g., reader123 or your personal PIN). 3. Under User Rights, enable: * [x] Download eBooks * [x] View eBooks in browser (optional) * [ ] Admin rights (leave unchecked) 4. Click Save.

Verify OPDS Feed is Enabled

  1. Go to Admin → Edit Basic Configuration → Server Configuration.
  2. Verify Enable OPDS Feed is checked (/opds).
  3. Click Save.

3. KOReader Setup on E-Ink Devices

Step 1: Open OPDS Catalog

  1. On your e-reader, launch KOReader.
  2. Tap the top menu bar to open the main menu.
  3. Tap the Search (Magnifying Glass) icon.
  4. Select OPDS Catalog.

Step 2: Add New Catalog

  1. Tap the Hamburger menu (≡) on the top left.
  2. Tap + Add new catalog (or Add catalog).
  3. Fill in the catalog details:
  4. Catalog Name: Homelab Calibre-Web
  5. Catalog URL:
    • If using MagicDNS: http://homelab:8083/opds
    • If using Tailscale IP: http://100.x.y.z:8083/opds
    • If using local home Wi-Fi: http://192.168.1.x:8083/opds
  6. Username: reader
  7. Password: reader123 (or your configured password)
  8. Tap Save.

Step 3: Browse and Download Books

  1. Tap into your newly added Homelab Calibre-Web catalog.
  2. You will see navigation categories:
  3. By Authors: Browse alphabetical list of authors (e.g. Dr. B. R. Ambedkar, Brandon Sanderson).
  4. Recent / New: Newly added acquisitions.
  5. Categories / Tags: Filter by genres and tags.
  6. Series: Books grouped by sequence.
  7. Search: Live title/author keyword search.
  8. Tap on any title to view book details, synopsis, and cover artwork.
  9. Tap Download. KOReader will save the .epub directly into your e-reader's storage directory (e.g. /mnt/onboard/ on Kobo or /sdcard/Books/ on Android).

4. Tailscale Network Access for E-Readers

E-Reader Device Type Connection Method Configuration Steps
Android E-Readers
(Onyx Boox, Meebook, Bigme, Likebook)		 Native Tailscale Client 1. Install Tailscale APK from F-Droid or Google Play.
2. Log into your Tailnet.
3. In KOReader, use http://homelab:8083/opds directly anywhere in the world.
Linux E-Readers (Home Wi-Fi)
(Kobo Clara/Libra/Sage, Kindle, PocketBook)		 Direct LAN IP When connected to your home Wi-Fi, KOReader connects directly to the server's local IP: http://192.168.1.x:8083/opds.
Linux E-Readers (Remote / Travel)
(Kobo / Kindle via phone hotspot)		 Tailscale Subnet Router 1. Enable subnet routing on your homelab host:
sudo tailscale up --advertise-routes=192.168.1.0/24
2. Approve route in Tailscale Admin Console.
3. Connect e-reader through phone hotspot with Tailscale active.

5. Ingestion Pipeline & CLI Automation

Ingesting EPUB Files via CLI

To add any .epub file into your Calibre library, extract metadata, and register it in metadata.db:

# Probe metadata and inspect cover art without importing
make probe-ebook file="path/to/book.epub"

# Ingest book into active Calibre library
make ingest-ebook file="path/to/book.epub"

Ingesting via Discord (#ebook-intake)

Drag and drop any .epub or .pdf file into your #ebook-intake channel in Discord: 1. The Discord bot reacts with ⏳. 2. The pipeline extracts metadata, cover art, and writes the entry into Calibre's metadata.db. 3. The reaction updates to ✅, and the book is instantly ready for download in KOReader!

Verifying Catalog Health

Run the automated OPDS verification check at any time: 

make verify-opds