百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
S

shelfarr

> 编程语言
开源

自主托管的电子书和有声读物管理系统

268 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

自主托管的电子书和有声读物管理系统

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

Features

  • Book Discovery — Search millions of titles via Hardcover, Google Books and Open Library
  • Smart Acquisition — Search Prowlarr, Jackett or Newznab/NZBHydra2 indexers; download via qBittorrent, Decypharr, Deluge, Transmission, SABnzbd or NZBGet
  • Direct Downloads — Ebooks and audiobooks from Anna's Archive, ebooks from Z-Library, and public-domain audiobooks from LibriVox — no torrent client needed
  • Auto-Selection & Format Preferences — Pick the best release automatically, scored by your preferred formats, bitrate and language
  • Auto-Processing — Rename and organize files with path/filename templates, then deliver to Audiobookshelf, BookOrbit or Grimmory watched folders
  • Library Sync — Automatic Audiobookshelf, BookOrbit or Grimmory scans after downloads complete
  • Manual Uploads — Upload your own files to fulfill a request, or add them directly to the library. For a failed standalone upload, administrators can open Admin → Uploads → Upload Details to select a local book of the same format or create one with corrected title/author, then retry. That choice is preserved across retries and bypasses automatic metadata matching. Uploads attached to requests or Audible imports cannot be reassigned here; uploads with reserved library files must use Retry to reconcile their existing destination first.
  • Multi-User — Role-based access with user requests and admin controls
  • Authentication — TOTP-based 2FA with backup codes, plus OIDC/SSO (Authentik, Authelia, Keycloak, etc.)
  • Notifications — In-app, Discord, Telegram and webhook notifications for request events
  • Download Routing — Route specific indexers to specific clients, with priority ordering
  • REST API — Scoped, per-user API tokens under /api/v1
  • Custom Acquisition Providers — Trusted HTTP providers can contribute search results and resolve selected items into direct, torrent or usenet artifacts
  • Third-Party Store Offers (Beta) — Surface legitimate DRM-free editions from supported sellers without handling checkout or payment data
  • Audible Backup (Beta) — Sync purchased Audible titles, explicitly queue a one-time backup of eligible existing purchases, optionally back up future purchases automatically, and import them through the separately packaged Libation companion

Books 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.

Beta integrations

The following integrations are opt-in and disabled by default:

  • Third-party stores add a separate purchase-options section to a request. Shelfarr checks the seller's catalog, shows DRM-free formats, localized availability and an external purchase link, but never handles payment or treats an offer as a downloadable result. The first provider is eBooks.com. See Third-party stores (Beta).
  • Audible Backup, powered by Libation connects Shelfarr to an optional companion service running the unmodified, pinned Libation CLI. Its Settings-style page separates Overview, Connection, Automation, and diagnostic Catalog concerns. After the first sync, Shelfarr asks whether to queue a conservative one-time backup of eligible existing purchases; the durable background batch and individual-title work are managed from the main Library while Libation processes one title at a time. Scheduled sync is optional, with a 24-hour default and an hourly option. Automatic backup for future purchases remains a separate opt-in. It is not an Audible store or general metadata provider. See Audible Backup (Beta).

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.

Quick Start

Docker (Recommended)

…

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.

Environment Variables

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:

yaml
environment:
  - HTTP_PORT=8080
ports:
  - "5056:8080"  # Map to the custom port

Example running at a sub-path (e.g., behind a reverse proxy at /shelfarr):

yaml
environment:
  - RAILS_RELATIVE_URL_ROOT=/shelfarr

Settings Environment Overrides

OIDC 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:

yaml
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.

Configuration

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,

Issues· 32 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言