Self hosted Ebook and Audiobook management system
Shelfarr
A self-hosted ebook and audiobook request and management system for the *arr ecosystem.
Think Jellyseerr, but for books. Your users request ebooks and audiobooks; Shelfarr searches your indexers and direct sources, downloads the best release and delivers it to Audiobookshelf — the same request-and-automate workflow the video stack gets from Jellyseerr + Sonarr/Radarr.
Website · Documentation · Settings Reference
/api/v1Books created solely for a failed upload are kept for retries. Replacing the match or deleting the unfinished upload removes that creation only if it is still unused and unacquired; existing or adopted books are preserved.
Manual upload recovery screenshots: Desktop · Mobile.
The following integrations are opt-in and disabled by default:
Both features are designed to preserve existing installations: upgrades add new, default-disabled configuration without changing existing providers or encryption keys. Review the linked guides before enabling a beta integration.
…A secret key is auto-generated on first run and saved to the data volume.
The Compose example sets SOLID_QUEUE_IN_PUMA=1. Puma starts one separate
bin/jobs supervisor for searches, downloads, and scheduled tasks, including
when multiple web workers are configured. It stops the supervisor on shutdown
or restart. If the supervisor exits unexpectedly, Puma shuts down too so the
container's restart policy can recover job processing. Unset this variable
when running bin/jobs as a separately managed service.
The current Compose example also starts the internal Audible Backup companion, powered by Libation. It stays idle until an administrator enables the beta integration, exposes no host port, and requires no Audible account for users who leave it disabled. Existing installations must merge the companion service and volumes from the current Compose example once before enabling Audible Backup; see the Audible Backup guide.
Visit http://localhost:5056 — the first user to register becomes admin.
| Variable | Default | Description |
|---|---|---|
PUID |
1000 |
User ID for file permissions. Should match the owner of your mounted volumes |
PGID |
1000 |
Group ID for file permissions. Should match the group of your mounted volumes |
CHOWN_ON_START |
auto |
Control startup ownership fixes for both standard containers. auto (default) adjusts only when needed, always fails on adjustment errors, and never skips chown calls for pre-permissioned/root-squashed volumes. The Audible companion still rejects group/world-accessible private state or credential/token files. |
TRUST_NFS_UID_SQUASH |
false |
Set to true only on an NFS export using all_squash (remaps every client's UID to one shared identity — most NAS UIs expose this as something like "map all users") and that no untrusted client can mount. This does not prove a file was written by this container — it tells Shelfarr to trust that the export is effectively single-tenant so its ownership safety checks aren't defeated by the squash. |
SHELFARR_SETTING_ALLOW_NONATOMIC_NFS_DIRECTORY_PUBLICATION |
false |
Allows directory imports when NFS rejects atomic no-replace renames. Enable only for a single-writer export. The fallback checks that the destination is absent before plain rename(2), but NFS cannot make those two operations atomic; a concurrently created empty destination directory could be replaced. This can also be enabled under Admin → Settings → Downloads → Output Paths. |
HTTP_PORT |
80 |
Internal container port. Change if port 80 is in use (e.g., behind gluetun) |
TZ |
UTC |
IANA time zone used for displayed timestamps (e.g., America/New_York) |
RAILS_MASTER_KEY |
Auto-generated | Encryption key for secrets. Auto-generated on first run if not set |
RAILS_RELATIVE_URL_ROOT |
/ |
Base path for running behind a reverse proxy at a sub-path (e.g., /shelfarr) |
SHELFARR_VERSION |
latest |
Pin both Shelfarr images to one OCI image version, without a leading v (for a GitHub release shown as vYYYY.MM.DD.N, use YYYY.MM.DD.N) |
LIBATION_BOOKS_PATH |
Docker named volume | Optional host path for retained Audible backup copies; useful for large libraries |
Audible Backup additionally requires the audiobook output filesystem to support advisory locks, hard links within that same mount, and Unix mode changes. Keep Shelfarr's .shelfarr-staging directory on the audiobook output filesystem and run the documented preflight before connecting Audible. mergerfs/libfuse mounts with a umask= mode override need a compatible underlying bind or a coordinated mount correction; do not bypass the check. See the Audible Backup storage requirements and filesystem preflight.
Filesystem race defenses assume every process running as Shelfarr's PUID is trusted. A malicious process with the same UID can modify any library file that Shelfarr itself can modify; isolate untrusted download tools under a different UID and grant only the narrow shared-directory access they need.
FlareSolverr runs a browser against remote pages. If you enable it for Anna's Archive, isolate its container with egress rules that deny private, loopback, link-local, and cloud metadata networks; Shelfarr cannot validate browser subrequests made inside FlareSolverr.
Example with custom port:
environment:
- HTTP_PORT=8080
ports:
- "5056:8080" # Map to the custom portExample running at a sub-path (e.g., behind a reverse proxy at /shelfarr):
environment:
- RAILS_RELATIVE_URL_ROOT=/shelfarrOIDC and webhook settings can be managed by environment variables. Use SHELFARR_SETTING_ plus the uppercased setting key, for example SHELFARR_SETTING_OIDC_CLIENT_SECRET or SHELFARR_SETTING_WEBHOOK_URL.
Supported setting keys:
oidc_enabled, oidc_auto_redirect, oidc_provider_name, oidc_issuer, oidc_client_id, oidc_client_secret, oidc_scopes, oidc_link_existing_users, oidc_auto_create_users, oidc_default_role, webhook_enabled, webhook_url, webhook_token, webhook_events, webhook_topic.
Example with the client secret supplied by your deployment secret store:
services:
shelfarr:
environment:
SHELFARR_SETTING_OIDC_ENABLED: "true"
SHELFARR_SETTING_OIDC_ISSUER: "https://auth.example.com"
SHELFARR_SETTING_OIDC_CLIENT_ID: "shelfarr"
SHELFARR_SETTING_OIDC_CLIENT_SECRET: "${OIDC_CLIENT_SECRET}"The env value takes precedence while set and is cast using the setting type. Nothing is written back to the database; removing the variable falls back to the stored value, or the default if none exists. Env-managed keys are read-only in Admin -> Settings. Other settings are not overridable, and unsupported SHELFARR_SETTING_* variables are ignored with a boot-time warning.
After logging in, go to Admin → Settings:
| Setting | Description |
|---|---|
| Indexer | Prowlarr, Jackett or Newznab/NZBHydra2 URL + API key for searches |
| Download Clients | qBittorrent, Decypharr, Deluge, Transmission, SABnzbd or NZBGet (Admin → Download Clients) |
| Output Paths | Where to place completed audiobooks/ebooks |
| Library Platform | Audiobookshelf URL + API key, or BookOrbit/Grimmory URL + username/password for library integration (optional) |
The save bar stays visible as you scroll. Preferences save automatically and show Saved when complete; connection details and fields marked Requires Save All need Save All. Unused direct sources start collapsed—open their heading to configure them. Downloads lists output paths first, with polling and retry options under Advanced download settings.
Only the selected indexer and library platform's credentials are shown. Switching providers preserves stored credentials and any unfinished draft for the other provider. Save All saves the active provider's draft; switch back to save a draft for another provider. Custom indexer categories appear when Search Scope is Custom. Without JavaScript,
No open issues yet, or sync has not completed.