Configuration

Everything narratorr-requests connects to — narratorr itself and your notifiers — is configured on the admin Settings page, not in environment variables. The page has a left-nav with five sections: General, Narratorr, eBooks, Notifications, and System. Secret values are stored encrypted at rest (the at-rest key is derived from SETTINGS_KEY, or from SESSION_SECRET when that’s unset).

The Narratorr connection and every notifier have a Test button that validates the current form values without saving, so you can confirm something works before committing it. Each card saves on its own — a Save button appears once you’ve changed a value (the Add/Edit-notifier dialog is the exception: its Add / Save button is always there).

General — Public URL & default quota

Set the Public URL to where the app is reached (e.g. https://requests.example.com). It’s used to deep-link notifications back to the request queue / users page, so an admin can jump straight from a ping to the thing that needs action. Leave it blank and notifications simply omit the link.

This section also sets the app-wide default request quota — the rolling-window cap that applies to every user who hasn’t been given a per-user override (see Managing quotas); admins are always unlimited. Two modes:

Mode	Effect
No default cap	Unlimited requests for everyone without a per-user override.
Limit requests	A positive cap over a friendly window — day / week / month, mapped to a fixed 1 / 7 / 30-day rolling window (not a calendar period).

There’s no DEFAULT_REQUEST_QUOTA environment variable — this lives entirely in Settings so it can change without a redeploy.

Narratorr connection

The lifeline — required for search and requests to work. Two fields:

Field	Notes
Server URL	narratorr’s full base URL, including the scheme — and the port when it isn’t the scheme default (e.g. http://narratorr:3000). Add a subpath if narratorr sits behind a reverse-proxy (e.g. http://host:3000/lib).
API key	From narratorr → Settings → Security. Masked once saved; leave blank to keep the current key.

1. Enter the Server URL and API key.
2. Click Test — it validates the current values (using the stored key if you left the API key blank). Fix anything until it passes.
3. Save.

Internal hosts are expected here

Unlike user-supplied cover URLs, the narratorr connection is trusted server-to-server admin config, so internal/private hosts (narratorr, localhost, 10.x, …) are intentionally allowed — that’s the normal sidecar setup.

Disconnecting

There’s no enable/disable toggle — narratorr is either configured or not. To disconnect, blank the Server URL and Save; that clears the connection and its stored key.

eBooks

Gates the companion-eBook features (Get eBook → download / Send to Kindle).

Enable ebook support — offer the eBook edition alongside the audiobook, ready to download or send to Kindle. This is an AND with narratorr’s own side: the connected narratorr must also have eBook support enabled (it advertises the capability over /api/v1) and actually keep companion EPUBs paired with imported books. While either half is off, users see no eBook UI at all — no disabled buttons, no errors, just absent.

Kindle sender

Saving eBook support on reveals the Kindle sender — which of your Email (SMTP) notifiers Kindle delivery sends from (eligible ones listed as name — from address). Until a sender is selected and confirmed, Kindle delivery is unavailable — users can still download.

Kindle delivery always sends from this one fixed mailbox, because every user must add that exact address to their own Amazon approved-senders list (the app walks them through it — see Setting up Send to Kindle). That’s why the app is deliberately sticky about the sender’s identity:

• On Save, the app confirms the notifier’s current From address and pins it as the address users allowlist.
• If that notifier’s From changes later, Kindle delivery pauses with an alert here until you Reconfirm sender — it never silently follows the new address, since that would break every user’s Amazon allowlist at once.
• Fixing the same notifier in place (host, password, …) needs no re-save here. Anything that changes which notifier sends — deleting and recreating it, or selecting a different one — needs a save here (delivery stays paused until then).

Notifiers

On the Notifications section you add any number of notifiers — there’s no fixed set of channels. Click Add Notifier, pick a type, choose the events it fires on, and fill in its fields. Each saved notifier has Edit, its own Test (sends a real sample), and Delete; a notifier whose type the app no longer recognizes is delete-only. There’s no enable/disable toggle — a notifier is live by existing; delete it to stop it.

Notifier events are admin-facing — they go to you, the admin — and fire only on the events you select. The Email (SMTP) notifier additionally serves as the delivery channel for requester opt-in emails (approved / denied / ready-to-listen, chosen per user in the account modal): those go to each requester’s own contact address, not the admin recipient (with several email notifiers, requester emails use the first usable one in stored order). An email notifier can also be selected as the Kindle sender — the mailbox Send to Kindle delivers from, independent of which notifier handles requester emails.

Event	Fires when
New request	A user requested a book and it’s awaiting your review.
New signup	A new user signed up and is awaiting approval.
Request failed	An approved request couldn’t be acquired — so you can step in (manual search, deny, refund).

Types

Type	Key fields
ntfy	Server URL (required — https://ntfy.sh for the hosted service, or your self-hosted base URL), topic, optional access token, optional priority.
Email (SMTP)	Host / port, an implicit-TLS toggle (465 vs STARTTLS on 587), optional username / password, a From address, and the admin recipient (for admin events only — requester opt-in emails go to each user’s own address over this same SMTP config).
Discord	A Discord webhook URL (optionally include the cover image).
Slack	A Slack incoming-webhook URL.
Telegram	Bot token + chat ID.
Pushover	App token + user key.
Gotify	Server URL + app token.
Webhook / Discord	A generic JSON POST to any URL — the escape hatch for anything not listed (the same URL field also accepts a plain Discord webhook).

How secrets are handled

Every secret — the narratorr API key and all notifier credentials (tokens, keys, and capability webhook URLs) — is never returned to the browser. A saved secret shows masked (•••••••• (unchanged)). On save:

• Leave a secret blank → the stored value is kept.
• Type a new value → it replaces the stored one.
• Tick “Clear stored value” (offered only on an already-saved optional secret) → it’s removed. Required secrets (webhook URLs, tokens) can’t be cleared — replace them, or delete the notifier. The narratorr API key has no clear control either: blank the Server URL and Save to drop the whole connection.

The Test button follows the same rule, so testing an existing connector with the secret left blank uses the stored secret — you don’t have to re-enter it just to test.

System Information

A read-only section for a quick server/environment snapshot — no configuration here:

Field	Shows
Version	The running build (branch@shortsha, e.g. main@a1b2c3d — dev for a local build).
Built	The image build timestamp.
Node.js	The Node.js runtime version.
OS	The host/container OS.
Database Size	The SQLite database file size.
narratorr	The connected narratorr’s version + reachability, sourced from narratorr’s own /api/v1/system — at a glance, without leaving Settings.