Quickstart

Quickstart

This guide takes you from zero to your first grabbed book in under 10 minutes. It assumes you already have a download client (SABnzbd or qBittorrent) and at least one Newznab or Torznab indexer running somewhere on your network.

If you're migrating from Readarr, see Migrating from Readarr instead.

---

Step 1 — Run Bindery

Docker (recommended)

docker run -d \
  --name bindery \
  -p 8787:8787 \
  -v /path/to/config:/config \
  -v /path/to/books:/books \
  -v /path/to/downloads:/downloads \
  ghcr.io/vavallee/bindery:latest

Replace /path/to/config, /path/to/books, and /path/to/downloads with real paths on your host. The config directory holds the database and backups; the downloads path must match the folder your download client completes into.

Docker Compose

services:
  bindery:
    image: ghcr.io/vavallee/bindery:latest
    container_name: bindery
    ports:
      - 8787:8787
    volumes:
      - ./config:/config
      - /media/books:/books
      - /media/downloads:/downloads
    environment:
      - BINDERY_LOG_LEVEL=info
    restart: unless-stopped

Binary (Linux / macOS / Windows)

Download the archive for your platform from the latest release, extract, and run ./bindery (or bindery.exe on Windows). The database lands in a platform-appropriate location by default; the startup log line shows exactly where.

For full deployment details — Helm, UID/GID, path remapping, upgrades — see docs/DEPLOYMENT.md.

---

Step 2 — First-run setup

Open http://localhost:8787. The first page load redirects to /setup.

1. Enter a username and password (8 characters minimum).
2. Click Create account. Bindery creates the administrator account and signs you in immediately.

This screen appears exactly once. Subsequent visits redirect to /login if your session has expired.

---

Step 3 — Connect a download client

Go to Settings → Download Clients → Add.

SABnzbd

Field	Value
Protocol	SABnzbd
Name	Anything (e.g. "SABnzbd")
Host	IP or hostname of your SABnzbd instance
Port	8080 (SABnzbd default)
API Key	SABnzbd → Config → General → Security → API Key

Click Test — you should see the SABnzbd version in the response. Click Save.

qBittorrent

Field	Value
Protocol	qBittorrent
Name	Anything
Host	IP or hostname
Port	8080 (qBittorrent WebUI default)
Username / Password	Your qBittorrent WebUI credentials

Click Test, then Save.

You can add both clients if you use a mixed Usenet + torrent setup. Bindery routes Newznab results to SABnzbd and Torznab results to qBittorrent automatically.

---

Step 4 — Add an indexer

Go to Settings → Indexers → Add.

Newznab (Usenet — NZBGeek, NZBFinder, DrunkenSlug, NZBPlanet, etc.)

Field	Value
Protocol	Newznab
Name	Your indexer name
URL	Indexer base URL, e.g. https://api.nzbgeek.info
API Key	From your indexer account page
Categories	7020 (default — ebooks). Add 3030 if you want audiobooks.

Click Test, then Save.

Torznab (via Prowlarr or Jackett)

Field	Value
Protocol	Torznab
URL	Torznab feed URL from Prowlarr or Jackett
API Key	From Prowlarr or Jackett
Categories	7020 for ebooks, 3030 for audiobooks

You can add as many indexers as you like. Searches run against all of them in parallel and results are deduplicated before ranking.

Non-standard category IDs: Some indexers (e.g. SceneNZBs) use additional category IDs like 7120 for German books or 3130 for German audio. Add them to the Categories field comma-separated. Bindery routes 7xxx IDs to ebook searches and 3xxx IDs to audiobook searches.

---

Step 5 — Add your first author

Click Authors in the navigation, then Add Author.

As you type a name, Bindery queries OpenLibrary in real time and shows matching results below the input. Select the correct author.

Options at add time:

Option	Default	What it does
Monitor	On	Track all this author's works; newly-released books automatically become wanted
Search on add	On	Fire an immediate indexer search for wanted books. Uncheck when bulk-adding many authors.
Quality profile	Default	Format preference order (EPUB / MOBI / AZW3 / PDF) and cutoff rules
Metadata profile	Default	Language filter, popularity threshold, ISBN presence requirement

Click Add Author. Bindery fetches all their works from OpenLibrary in the background — typically 2–5 seconds. The author card shows a book count once the fetch completes.

---

Step 6 — Check the Wanted list

Click Wanted in the navigation. Books that are monitored and have no file yet appear here.

When you added the author with Search on add enabled, Bindery immediately fired searches for any wanted books. If any results scored above your quality profile's cutoff and no delay profile is holding them, they'll already be in the queue.

Manual search: Click the search icon on any row to open the interactive search for that book. Results are ranked by format quality, release tags (RETAIL / UNABRIDGED), year match, grab count, and size. Click Grab on the result you want. The button shows a spinner while the request is in flight and a ✓ on success.

---

Step 7 — Watch it land

Click Queue to see active downloads. Bindery overlays real-time SABnzbd or qBittorrent status — percentage complete, speed, remaining time.

When the download client marks the item complete, Bindery:

1. Matches the download to the book by NZO/torrent ID.
2. Moves (or copy+verifies+deletes across filesystems) the file to /books/ using your naming template.
3. Marks the book as Imported and records the event in History.

If anything goes wrong, the failure surfaces in History with the error detail inline.

---

What next

Topic	Guide
Set up format preferences and cutoffs	Quality profiles
Hold off grabbing for N hours to let better releases appear	Delay profiles
Score custom release tags (freeleech, RETAIL, etc.)	Custom formats
Send grab/import events to ntfy, Slack, Discord, or Home Assistant	Notifications
Put Bindery behind a reverse proxy with optional SSO	Reverse proxy & SSO
Import your Readarr library	Migrating from Readarr
OPDS: browse your library from KOReader / Moon+ Reader	OPDS
Calibre integration (post-import sync, drop folder)	Calibre integration
Permission denied, path remap, import failures	Troubleshooting

---

Common first-run issues

Nothing appears on the Wanted page after adding an author. The author's books may all be filtered out by the metadata profile — typically the default language filter (English) removes books whose OpenLibrary language field is empty or set to a different language. Open the author's detail page and check whether books show as "filtered." Adjust the metadata profile in Settings → Profiles → Metadata or pick a less strict profile when adding the author.

Test button fails on the download client. Check that the port and host are reachable from the Bindery container. If both containers are on the same Docker network you can use the container name as the host; otherwise use the host machine's IP. For SABnzbd, make sure the API key is copied from the Security section, not the NZB key.

Books grab but never import. The most common cause is a path mismatch between what the download client reports and what Bindery can see. If they're in separate containers mounted at different paths, set BINDERY_DOWNLOAD_PATH_REMAP. See Troubleshooting for the full diagnostic flow.

Grab button does nothing on the Wanted page. No indexer returned a result that passed the quality-profile cutoff. Open the interactive search (search icon on the book row) to see raw results and their scores. If results appear there but aren't auto-grabbed, the cutoff is filtering them — lower the cutoff in Settings → Profiles → Quality or grab manually.