Calibre integration

Bindery does not replace Calibre — it feeds it. After Bindery renames and moves a downloaded file into your root folder, it can optionally tell Calibre to add the new book to its library so that Calibre Content Server, Calibre-Web, or a reader app pulling from Calibre's DB sees it immediately.

There are three modes, set per-install under Settings → Calibre:

Mode	What Bindery does after import	When to pick it
`off`	Nothing — the book sits in the Bindery root folder only.	You don't use Calibre. (Default for new installs.)
`calibredb`	Shells out to `calibredb add --with-library <path>` on the imported file.	`calibredb` is on the Bindery container's `PATH` and the library dir is writable.
`plugin`	POSTs the book path to the Bindery Bridge plugin running inside a Calibre container.	Calibre runs in a separate pod/container with no shared binary.

`calibredb` mode

Requirements

The calibredb binary must be reachable in $PATH inside the Bindery process. In the distroless container this means mounting a sidecar image or switching to a Calibre-bundled Bindery image (none published; build your own with a multi-stage Dockerfile, or run Bindery on bare metal alongside Calibre).
The Calibre library directory (the one containing metadata.db) must be writable by the Bindery UID (65532 in the default image).

Settings

Setting	Meaning
`calibre.mode`	`calibredb`
`calibre.library_path`	Path to the Calibre library root (the dir with `metadata.db`)

Failure behaviour

If calibredb add returns non-zero, Bindery logs the failure and does not back out the rename. The book is in the Bindery root folder; you can re-run the add manually.

Plugin mode (cross-container / Kubernetes)

The plugin mode is the recommended approach for Kubernetes deployments where Bindery and Calibre run in separate pods with no shared binary or sidecar.

┌────────────────┐   POST /v1/books   ┌──────────────────────────────┐
│    Bindery     │ ─────────────────► │  Calibre + Bindery Bridge    │
│  (Go process)  │                    │  plugin (HTTP on :8099)       │
└────────────────┘                    └──────────────────────────────┘
        │                                        │
        │  shared NFS / PVC                      │ db.new_api.add_books()
        ▼                                        ▼
   /media/BOOKS/                         Calibre metadata.db

Both containers must mount the same book library volume. Bindery moves the file first, then tells Calibre where it landed via HTTP. A Calibre failure cannot orphan a downloaded book.

Step 1 — Install the Bindery Bridge plugin

Option A: manual (desktop Calibre)

Download calibre-bridge-vX.Y.Z.zip from bindery-plugins releases.
In Calibre: Preferences → Plugins → Load plugin from file → select the .zip.
Restart Calibre.

Option B: kubectl exec (container / PVC)

The Calibre GUI file picker only sees paths inside the container — you can't browse to a zip on your laptop. Install directly into the running pod instead:

# Download into the container
kubectl exec -n <namespace> deployment/<calibre-deployment> -- \
  wget -q -O /tmp/calibre-bridge.zip \
  https://github.com/vavallee/bindery-plugins/releases/download/v-calibre-bridge-X.Y.Z/calibre-bridge-vX.Y.Z.zip

# Install (calibre-customize is part of the linuxserver/calibre image)
kubectl exec -n <namespace> deployment/<calibre-deployment> -- \
  calibre-customize -a /tmp/calibre-bridge.zip

# Restart the pod to activate
kubectl rollout restart deployment/<calibre-deployment> -n <namespace>

After restart the plugin HTTP server starts automatically.

Option C: Kubernetes init-container (GitOps)

The charts/calibre-plugin-installer Helm chart in bindery-plugins injects an init-container that downloads and installs the plugin before Calibre starts. See docs/installation.md in that repo for full setup.

Step 2 — Configure the plugin

Open Calibre → Preferences → Plugins → User plugins → Bindery Bridge → Customize:

Setting	Recommended value	Notes
Listen port	`8099`	Any free port works
Bind host	`0.0.0.0`	Required for cross-pod access; `127.0.0.1` only works on bare-metal
API key	(generate one)	Click Generate in Bindery → Settings → Calibre, or run `openssl rand -hex 32`

After saving, the dialog restarts the HTTP server in-place — no Calibre restart needed.

Verify the plugin is listening:

kubectl exec -n <namespace> deployment/<calibre-deployment> -- \
  ss -tlnp | grep 8099
# Expected: LISTEN 0 5 0.0.0.0:8099

Step 3 — Expose port 8099 in Kubernetes

# Add to your Calibre Service spec.ports
- name: plugin
  port: 8099
  targetPort: 8099
  protocol: TCP

Step 4 — Configure Bindery

In Bindery: Settings → Calibre:

Field	Value
Mode	`plugin`
Library path	Path to the Calibre library root inside Bindery's container (e.g. `/media/BOOKS`)
Plugin URL	`http://calibre.<namespace>.svc.cluster.local:8099`
Plugin API key	The key you set in Step 2 — paste it here, or click Generate to create a new one

Click Test connection — it calls GET /v1/health and returns the plugin version and Calibre version on success.

Plugin mode failure behaviour

Scenario	Bindery behaviour
Plugin returns `201`	Calibre book id stored on the Bindery book row
Plugin returns `409` (duplicate)	Existing Calibre id recorded; no error
Plugin returns `503` (library swap)	Retried once after 1 s; failure logged if still 503
Plugin unreachable / timeout	Import is not rolled back — the book is in the library. Failure logged. Re-trigger via Settings → Calibre → Test or wait for next auto-import

See docs/CALIBRE-PLUGIN.md for the complete plugin setup reference.

Library import

If you already have a Calibre library and want Bindery to adopt it, point Bindery at the library via Settings → Library → Import from Calibre. Bindery will:

Read Calibre's metadata.db.
For each book, resolve the author + title against Bindery's metadata providers (OpenLibrary / Google Books / Hardcover).
Create matching author and book rows, linking to the original file path.
Record the Calibre book id so future updates stay in sync.

This is a one-way import. Changes to metadata in Calibre after the import are not synced back to Bindery.

Choosing a mode — quick decision tree

Do you run Calibre?
├── no   → mode: off
└── yes
    └── Can Bindery exec calibredb against the library dir?
        ├── yes  → mode: calibredb   (simpler, single step)
        └── no   → mode: plugin      (HTTP bridge, cross-container)

Known limitations

No metadata sync-back — if you edit cover/title/author in Calibre, Bindery doesn't notice. Re-run the library import to refresh.
No format conversion — Bindery doesn't invoke ebook-convert. Whatever format the indexer served is what ends up in both libraries.
Shared volume required for plugin mode — both Bindery and Calibre must mount the same library path. Bindery moves the file first; the plugin path it POSTs must resolve inside the Calibre container.

Calibre integration

Calibre integration

calibredb mode

Requirements

Settings

Failure behaviour

Plugin mode (cross-container / Kubernetes)

Step 1 — Install the Bindery Bridge plugin

Option A: manual (desktop Calibre)

Option B: kubectl exec (container / PVC)

Option C: Kubernetes init-container (GitOps)

Step 2 — Configure the plugin

Step 3 — Expose port 8099 in Kubernetes

Step 4 — Configure Bindery

Plugin mode failure behaviour

Library import

Choosing a mode — quick decision tree

Known limitations

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`calibredb` mode