Skip to content

environment-variables.md

Latest commit

 

History

History
2165 lines (1338 loc) · 63.1 KB

environment-variables.md

File metadata and controls

2165 lines (1338 loc) · 63.1 KB

Environment Variables

This document lists all configuration options that can be set via environment variables.

Auto-generated - Do not edit manually. Run python scripts/generate_env_docs.py to regenerate.

Table of Contents

Bootstrap Configuration

These environment variables are used at startup before the settings system loads. They typically configure paths, server settings, and authentication startup behavior.

Variable Description Type Default
CONFIG_DIR Directory for storing configuration files and plugin settings. string (path) /config
LOG_ROOT Root directory for log files. string (path) /var/log/
TMP_DIR Staging directory for downloads before moving to destination. string (path) /tmp/shelfmark
ENABLE_LOGGING Enable file logging under LOG_ROOT/shelfmark/ (including shelfmark.log and startup logs). boolean true
FLASK_HOST Host address for the Flask web server. string 0.0.0.0
FLASK_PORT Port number for the Flask web server. number 8084
SESSION_COOKIE_SECURE Enable secure cookies (requires HTTPS). boolean false
CWA_DB_PATH Path to the Calibre-Web database for authentication integration. string (path) /auth/app.db
HIDE_LOCAL_AUTH Hide the username/password login form when OIDC is active. boolean false
DISABLE_LOCAL_AUTH Disable username/password login and remove the local-admin prerequisite for OIDC. Implies HIDE_LOCAL_AUTH; with AUTH_METHOD=builtin, everyone is locked out until auth env vars are changed. boolean false
OIDC_AUTO_REDIRECT Automatically redirect to the OIDC provider instead of showing the login page. boolean false
DOCKERMODE Indicates the application is running inside a Docker container. boolean false
ONBOARDING Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage). boolean true
Detailed descriptions

CONFIG_DIR

Directory for storing configuration files and plugin settings.

  • Type: string (path)
  • Default: /config

LOG_ROOT

Root directory for log files.

  • Type: string (path)
  • Default: /var/log/

TMP_DIR

Staging directory for downloads before moving to destination.

  • Type: string (path)
  • Default: /tmp/shelfmark

ENABLE_LOGGING

Enable file logging under LOG_ROOT/shelfmark/ (including shelfmark.log and startup logs).

  • Type: boolean
  • Default: true

FLASK_HOST

Host address for the Flask web server.

  • Type: string
  • Default: 0.0.0.0

FLASK_PORT

Port number for the Flask web server.

  • Type: number
  • Default: 8084

SESSION_COOKIE_SECURE

Enable secure cookies (requires HTTPS).

  • Type: boolean
  • Default: false

CWA_DB_PATH

Path to the Calibre-Web database for authentication integration.

  • Type: string (path)
  • Default: /auth/app.db

HIDE_LOCAL_AUTH

Hide the username/password login form when OIDC is active.

  • Type: boolean
  • Default: false

DISABLE_LOCAL_AUTH

Disable username/password login and remove the local-admin prerequisite for OIDC. Implies HIDE_LOCAL_AUTH; with AUTH_METHOD=builtin, everyone is locked out until auth env vars are changed.

  • Type: boolean
  • Default: false

OIDC_AUTO_REDIRECT

Automatically redirect to the OIDC provider instead of showing the login page.

  • Type: boolean
  • Default: false

DOCKERMODE

Indicates the application is running inside a Docker container.

  • Type: boolean
  • Default: false

ONBOARDING

Show the onboarding wizard on first run. Set to false to skip (useful for ephemeral storage).

  • Type: boolean
  • Default: true

General

Variable Description Type Default
SEARCH_PAGE_TITLE Title shown above the main search box on the homepage. string Shelfmark
CALIBRE_WEB_URL Adds a navigation button to your book library (Calibre-Web Automated, Grimmory, etc). string none
AUDIOBOOK_LIBRARY_URL Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text. string none
SUPPORTED_FORMATS Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found. string (comma-separated) epub,mobi,azw3,fb2,djvu,cbz,cbr
SUPPORTED_AUDIOBOOK_FORMATS Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found. string (comma-separated) m4b,mp3
BOOK_LANGUAGE Default language filter for searches. string (comma-separated) en
Detailed descriptions

SEARCH_PAGE_TITLE

Search Page Title

Title shown above the main search box on the homepage.

  • Type: string
  • Default: Shelfmark

CALIBRE_WEB_URL

Library URL

Adds a navigation button to your book library (Calibre-Web Automated, Grimmory, etc).

  • Type: string
  • Default: none

AUDIOBOOK_LIBRARY_URL

Audiobook Library URL

Adds a separate navigation button for your audiobook library (Audiobookshelf, Plex, etc). When both URLs are set, icons are shown instead of text.

  • Type: string
  • Default: none

SUPPORTED_FORMATS

Supported Book Formats

Book formats to include in search results. ZIP/RAR archives are extracted automatically and book files are used if found.

  • Type: string (comma-separated)
  • Default: epub,mobi,azw3,fb2,djvu,cbz,cbr

SUPPORTED_AUDIOBOOK_FORMATS

Supported Audiobook Formats

Audiobook formats to include in search results. ZIP/RAR archives are extracted automatically and audiobook files are used if found.

  • Type: string (comma-separated)
  • Default: m4b,mp3

BOOK_LANGUAGE

Default Book Languages

Default language filter for searches.

  • Type: string (comma-separated)
  • Default: en

Search Mode

Variable Description Type Default
SEARCH_MODE How you want to search for and download books. string (choice) universal
AA_DEFAULT_SORT Default sort order for search results. string (choice) relevance
SHOW_RELEASE_SOURCE_LINKS Show clickable release-source links in release and details modals. Metadata provider links stay enabled. boolean true
SHOW_COMBINED_SELECTOR Show the option to search for and download both a book and audiobook together. boolean true
METADATA_PROVIDER Choose which metadata provider to use for book searches. string (choice) openlibrary
METADATA_PROVIDER_AUDIOBOOK Metadata provider for audiobook searches. Uses the book provider if not set. string (choice) empty string
METADATA_PROVIDER_COMBINED Metadata provider for combined mode searches. Uses the book provider if not set. string (choice) empty string
DEFAULT_RELEASE_SOURCE The release source tab to open by default in the release modal for books. Leave unset to use the first available source. string (choice) empty string
DEFAULT_RELEASE_SOURCE_AUDIOBOOK The release source tab to open by default in the release modal for audiobooks. Uses the book release source if not set. string (choice) empty string
Detailed descriptions

SEARCH_MODE

Search Mode

How you want to search for and download books.

  • Type: string (choice)
  • Default: universal
  • Options: direct (Direct), universal (Universal)

AA_DEFAULT_SORT

Default Sort Order

Default sort order for search results.

  • Type: string (choice)
  • Default: relevance
  • Options: relevance (Most relevant), newest (Newest (publication year)), oldest (Oldest (publication year)), largest (Largest (filesize)), smallest (Smallest (filesize)), newest_added (Newest (open sourced)), oldest_added (Oldest (open sourced))

SHOW_RELEASE_SOURCE_LINKS

Show Release Source Links

Show clickable release-source links in release and details modals. Metadata provider links stay enabled.

  • Type: boolean
  • Default: true

SHOW_COMBINED_SELECTOR

Show Combined Download Selector

Show the option to search for and download both a book and audiobook together.

  • Type: boolean
  • Default: true

METADATA_PROVIDER

Book Metadata Provider

Choose which metadata provider to use for book searches.

  • Type: string (choice)
  • Default: openlibrary
  • Options: "" (No providers enabled)

METADATA_PROVIDER_AUDIOBOOK

Audiobook Metadata Provider

Metadata provider for audiobook searches. Uses the book provider if not set.

  • Type: string (choice)
  • Default: empty string
  • Options: "" (Use book provider), "" (No providers enabled)

METADATA_PROVIDER_COMBINED

Combined Mode Metadata Provider

Metadata provider for combined mode searches. Uses the book provider if not set.

  • Type: string (choice)
  • Default: empty string
  • Options: "" (Use book provider), "" (No providers enabled)

DEFAULT_RELEASE_SOURCE

Default Book Release Source

The release source tab to open by default in the release modal for books. Leave unset to use the first available source.

  • Type: string (choice)
  • Default: empty string
  • Options: "" (Use first available source)

DEFAULT_RELEASE_SOURCE_AUDIOBOOK

Default Audiobook Release Source

The release source tab to open by default in the release modal for audiobooks. Uses the book release source if not set.

  • Type: string (choice)
  • Default: empty string
  • Options: "" (Use book release source)

Downloads

Variable Description Type Default
BOOKS_OUTPUT_MODE Choose where completed book files are sent. string (choice) folder
INGEST_DIR Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}). string /books
FILE_ORGANIZATION Choose how downloaded book files are named and organized. string (choice) rename
TEMPLATE_RENAME Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or ''); use Organize for folders. Applies to single-file downloads. string {Author} - {Title} ({Year})
TEMPLATE_ORGANIZE Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. string {Author}/{Title} ({Year})
HARDLINK_TORRENTS Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. boolean false
BOOKLORE_HOST Base URL of your Grimmory instance string none
BOOKLORE_USERNAME Grimmory account username string none
BOOKLORE_PASSWORD Grimmory account password string (secret) none
BOOKLORE_DESTINATION Choose whether uploads go directly to a specific library path or to Bookdrop for review. string (choice) library
BOOKLORE_LIBRARY_ID Grimmory library to upload into. string (choice) none
BOOKLORE_PATH_ID Grimmory library path for uploads. string (choice) none
EMAIL_RECIPIENT Optional fallback email address when no per-user email recipient override is configured. string none
EMAIL_ATTACHMENT_SIZE_LIMIT_MB Maximum total attachment size per email. Email encoding adds overhead; keep this below your provider's limit. number 25
EMAIL_SMTP_HOST SMTP server hostname or IP (e.g., smtp.gmail.com). string none
EMAIL_SMTP_PORT SMTP server port (587 is typical for STARTTLS, 465 for SSL). number 587
EMAIL_SMTP_SECURITY Transport security mode for SMTP. string (choice) starttls
EMAIL_SMTP_USERNAME SMTP username (leave empty for no authentication). string none
EMAIL_SMTP_PASSWORD SMTP password (required if Username is set). string (secret) none
EMAIL_FROM From address used for the email. You can include a display name (e.g., Shelfmark mail@example.com). Leave blank to default to the SMTP username (when it is an email address). string none
EMAIL_SUBJECT_TEMPLATE Email subject. Variables: {Author}, {Title}, {PrimaryTitle}, {Year}, {Series}, {SeriesPosition}, {Subtitle}, {Format}. string {Title}
EMAIL_SMTP_TIMEOUT_SECONDS How long to wait for SMTP operations before failing. number 60
EMAIL_ALLOW_UNVERIFIED_TLS Disable TLS certificate verification (not recommended). boolean false
DESTINATION_AUDIOBOOK Directory where downloaded audiobook files are saved. Leave empty to use the Books destination. string none
FILE_ORGANIZATION_AUDIOBOOK Choose how downloaded audiobook files are named and organized. string (choice) rename
TEMPLATE_AUDIOBOOK_RENAME Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or ''); use Organize for folders. Applies to single-file downloads. string {Author} - {Title}
TEMPLATE_AUDIOBOOK_ORGANIZE Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. string {Author}/{Title}/{Title}
HARDLINK_TORRENTS_AUDIOBOOK Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder. boolean true
AUTO_OPEN_DOWNLOADS_SIDEBAR Automatically open the downloads sidebar when a new download is queued. boolean false
DOWNLOAD_TO_BROWSER_CONTENT_TYPES Automatically download completed files to your browser for the selected content types. string (comma-separated) empty list
MAX_CONCURRENT_DOWNLOADS Maximum number of simultaneous downloads. number 3
STATUS_TIMEOUT How long to keep completed/failed downloads in the queue display. number 3600
Detailed descriptions

BOOKS_OUTPUT_MODE

Output Mode

Choose where completed book files are sent.

  • Type: string (choice)
  • Default: folder
  • Options: folder (Folder), email (Email (SMTP)), booklore (Grimmory (API))

INGEST_DIR

Destination

Directory where downloaded files are saved. Use {User} for per-user folders (e.g. /books/{User}).

  • Type: string
  • Default: /books
  • Required: Yes

FILE_ORGANIZATION

File Organization

Choose how downloaded book files are named and organized.

  • Type: string (choice)
  • Default: rename
  • Options: none (None), rename (Rename Only), organize (Rename and Organize)

TEMPLATE_RENAME

Naming Template

Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or ''); use Organize for folders. Applies to single-file downloads.

  • Type: string
  • Default: {Author} - {Title} ({Year})

TEMPLATE_ORGANIZE

Path Template

Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension). Universal adds: {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

  • Type: string
  • Default: {Author}/{Title} ({Year})

HARDLINK_TORRENTS

Hardlink Book Torrents

Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder.

  • Type: boolean
  • Default: false

BOOKLORE_HOST

Grimmory URL

Base URL of your Grimmory instance

  • Type: string
  • Default: none
  • Required: Yes

BOOKLORE_USERNAME

Username

Grimmory account username

  • Type: string
  • Default: none
  • Required: Yes

BOOKLORE_PASSWORD

Password

Grimmory account password

  • Type: string (secret)
  • Default: none
  • Required: Yes

BOOKLORE_DESTINATION

Upload Destination

Choose whether uploads go directly to a specific library path or to Bookdrop for review.

  • Type: string (choice)
  • Default: library
  • Options: library (Specific Library), bookdrop (Bookdrop)

BOOKLORE_LIBRARY_ID

Library

Grimmory library to upload into.

  • Type: string (choice)
  • Default: none
  • Required: Yes

BOOKLORE_PATH_ID

Path

Grimmory library path for uploads.

  • Type: string (choice)
  • Default: none
  • Required: Yes

EMAIL_RECIPIENT

Default Email Recipient

Optional fallback email address when no per-user email recipient override is configured.

  • Type: string
  • Default: none

EMAIL_ATTACHMENT_SIZE_LIMIT_MB

Attachment Size Limit (MB)

Maximum total attachment size per email. Email encoding adds overhead; keep this below your provider's limit.

  • Type: number
  • Default: 25
  • Constraints: min: 1, max: 600

EMAIL_SMTP_HOST

SMTP Host

SMTP server hostname or IP (e.g., smtp.gmail.com).

  • Type: string
  • Default: none
  • Required: Yes

EMAIL_SMTP_PORT

SMTP Port

SMTP server port (587 is typical for STARTTLS, 465 for SSL).

  • Type: number
  • Default: 587
  • Constraints: min: 1, max: 65535

EMAIL_SMTP_SECURITY

SMTP Security

Transport security mode for SMTP.

  • Type: string (choice)
  • Default: starttls
  • Options: none (None), starttls (STARTTLS), ssl (SSL/TLS)

EMAIL_SMTP_USERNAME

Username

SMTP username (leave empty for no authentication).

  • Type: string
  • Default: none

EMAIL_SMTP_PASSWORD

Password

SMTP password (required if Username is set).

  • Type: string (secret)
  • Default: none

EMAIL_FROM

From Address

From address used for the email. You can include a display name (e.g., Shelfmark mail@example.com). Leave blank to default to the SMTP username (when it is an email address).

  • Type: string
  • Default: none

EMAIL_SUBJECT_TEMPLATE

Subject Template

Email subject. Variables: {Author}, {Title}, {PrimaryTitle}, {Year}, {Series}, {SeriesPosition}, {Subtitle}, {Format}.

  • Type: string
  • Default: {Title}

EMAIL_SMTP_TIMEOUT_SECONDS

SMTP Timeout (seconds)

How long to wait for SMTP operations before failing.

  • Type: number
  • Default: 60
  • Constraints: min: 1, max: 600

EMAIL_ALLOW_UNVERIFIED_TLS

Allow Unverified TLS

Disable TLS certificate verification (not recommended).

  • Type: boolean
  • Default: false

DESTINATION_AUDIOBOOK

Destination

Directory where downloaded audiobook files are saved. Leave empty to use the Books destination.

  • Type: string
  • Default: none

FILE_ORGANIZATION_AUDIOBOOK

File Organization

Choose how downloaded audiobook files are named and organized.

  • Type: string (choice)
  • Default: rename
  • Options: none (None), rename (Rename Only), organize (Rename and Organize)

TEMPLATE_AUDIOBOOK_RENAME

Naming Template

Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty. Rename templates are filename-only (no '/' or ''); use Organize for folders. Applies to single-file downloads.

  • Type: string
  • Default: {Author} - {Title}

TEMPLATE_AUDIOBOOK_ORGANIZE

Path Template

Use / to create folders. Variables: {Author}, {Title}, {Year}, {User}, {OriginalName} (source filename without extension), {Series}, {SeriesPosition}, {Subtitle}, {PrimaryTitle}, {PartNumber}. Use arbitrary prefix/suffix: {Vol. SeriesPosition - } outputs 'Vol. 2 - ' when set, nothing when empty.

  • Type: string
  • Default: {Author}/{Title}/{Title}

HARDLINK_TORRENTS_AUDIOBOOK

Hardlink Audiobook Torrents

Create hardlinks instead of copying. Preserves seeding but archives won't be extracted. Don't use if destination is a library ingest folder.

  • Type: boolean
  • Default: true

AUTO_OPEN_DOWNLOADS_SIDEBAR

Auto-Open Downloads Sidebar

Automatically open the downloads sidebar when a new download is queued.

  • Type: boolean
  • Default: false

DOWNLOAD_TO_BROWSER_CONTENT_TYPES

Download to Browser

Automatically download completed files to your browser for the selected content types.

  • Type: string (comma-separated)
  • Default: empty list

MAX_CONCURRENT_DOWNLOADS

Max Concurrent Downloads

Maximum number of simultaneous downloads.

  • Type: number
  • Default: 3
  • Requires restart: Yes
  • Constraints: min: 1, max: 10

STATUS_TIMEOUT

Status Timeout (seconds)

How long to keep completed/failed downloads in the queue display.

  • Type: number
  • Default: 3600
  • Constraints: min: 60, max: 86400

Security

Variable Description Type Default
AUTH_METHOD Select the authentication method for accessing Shelfmark. Restart container after changing Calibre-Web passwords. string (choice) none
PROXY_AUTH_USER_HEADER The HTTP header your proxy uses to pass the authenticated username. string X-Auth-User
PROXY_AUTH_LOGOUT_URL The URL to redirect users to for logging out. Leave empty to disable logout functionality. string empty string
PROXY_AUTH_ADMIN_GROUP_HEADER Optional: header your proxy uses to pass user groups/roles. string X-Auth-Groups
PROXY_AUTH_ADMIN_GROUP_NAME Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection. string empty string
OIDC_DISCOVERY_URL OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration. string none
OIDC_CLIENT_ID OAuth2 client ID from your identity provider. string none
OIDC_CLIENT_SECRET OAuth2 client secret from your identity provider. string (secret) none
OIDC_SCOPES OAuth2 scopes to request from the identity provider. Managed automatically: includes essential scopes and the group claim when using admin group authorization. string (comma-separated) openid,email,profile
OIDC_GROUP_CLAIM The name of the claim in the ID token that contains user groups. string groups
OIDC_ADMIN_GROUP Users in this group will be given admin access (if enabled below). Leave empty to use database roles only. string empty string
OIDC_USE_ADMIN_GROUP When enabled, users in the Admin Group are granted admin access. When disabled, admin access is determined solely by database roles. boolean true
OIDC_AUTO_PROVISION Automatically create a user account on first OIDC login. When disabled, users must be pre-created by an admin. boolean true
OIDC_BUTTON_LABEL Custom label for the OIDC sign-in button on the login page. string empty string
Detailed descriptions

AUTH_METHOD

Authentication Method

Select the authentication method for accessing Shelfmark. Restart container after changing Calibre-Web passwords.

  • Type: string (choice)
  • Default: none
  • Options: none (No Authentication), builtin (Local), proxy (Proxy Authentication), oidc (OIDC (OpenID Connect)), cwa (Calibre-Web Database)

PROXY_AUTH_USER_HEADER

Proxy Auth User Header

The HTTP header your proxy uses to pass the authenticated username.

  • Type: string
  • Default: X-Auth-User

PROXY_AUTH_LOGOUT_URL

Proxy Auth Logout URL

The URL to redirect users to for logging out. Leave empty to disable logout functionality.

  • Type: string
  • Default: empty string

PROXY_AUTH_ADMIN_GROUP_HEADER

Proxy Auth Admin Group Header

Optional: header your proxy uses to pass user groups/roles.

  • Type: string
  • Default: X-Auth-Groups

PROXY_AUTH_ADMIN_GROUP_NAME

Proxy Auth Admin Group

Optional: users in this group are treated as admins. Leave blank to skip group-based admin detection.

  • Type: string
  • Default: empty string

OIDC_DISCOVERY_URL

Discovery URL

OpenID Connect discovery endpoint URL. Usually ends with /.well-known/openid-configuration.

  • Type: string
  • Default: none
  • Required: Yes

OIDC_CLIENT_ID

Client ID

OAuth2 client ID from your identity provider.

  • Type: string
  • Default: none
  • Required: Yes

OIDC_CLIENT_SECRET

Client Secret

OAuth2 client secret from your identity provider.

  • Type: string (secret)
  • Default: none
  • Required: Yes

OIDC_SCOPES

Scopes

OAuth2 scopes to request from the identity provider. Managed automatically: includes essential scopes and the group claim when using admin group authorization.

  • Type: string (comma-separated)
  • Default: openid,email,profile

OIDC_GROUP_CLAIM

Group Claim Name

The name of the claim in the ID token that contains user groups.

  • Type: string
  • Default: groups

OIDC_ADMIN_GROUP

Admin Group Name

Users in this group will be given admin access (if enabled below). Leave empty to use database roles only.

  • Type: string
  • Default: empty string

OIDC_USE_ADMIN_GROUP

Use Admin Group for Authorization

When enabled, users in the Admin Group are granted admin access. When disabled, admin access is determined solely by database roles.

  • Type: boolean
  • Default: true

OIDC_AUTO_PROVISION

Auto-Provision Users

Automatically create a user account on first OIDC login. When disabled, users must be pre-created by an admin.

  • Type: boolean
  • Default: true

OIDC_BUTTON_LABEL

Login Button Label

Custom label for the OIDC sign-in button on the login page.

  • Type: string
  • Default: empty string

Network

Variable Description Type Default
CERTIFICATE_VALIDATION Controls SSL/TLS certificate verification for outbound connections. Disable for self-signed certificates on internal services (e.g. OIDC providers, Prowlarr). string (choice) enabled
CUSTOM_DNS DNS provider for domain resolution. 'Auto' rotates through providers on failure. string (choice) auto
CUSTOM_DNS_MANUAL Comma-separated list of DNS server IP addresses (e.g., 8.8.8.8, 1.1.1.1). string none
USE_DOH Use encrypted DNS queries for improved reliability and privacy. boolean true
USING_TOR Route all traffic through Tor for enhanced privacy. Requires root startup. boolean false
PROXY_MODE Choose proxy type. SOCKS5 handles all traffic through a single proxy. string (choice) none
HTTP_PROXY HTTP proxy URL (e.g., http://proxy:8080) string none
HTTPS_PROXY HTTPS proxy URL (leave empty to use HTTP proxy for HTTPS) string none
SOCKS5_PROXY SOCKS5 proxy URL. Supports auth: socks5://user:pass@host:port string none
NO_PROXY Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.,.local) string none
Detailed descriptions

CERTIFICATE_VALIDATION

Certificate Validation

Controls SSL/TLS certificate verification for outbound connections. Disable for self-signed certificates on internal services (e.g. OIDC providers, Prowlarr).

  • Type: string (choice)
  • Default: enabled
  • Options: enabled (Enabled (Recommended)), disabled_local (Disabled for Local Addresses), disabled (Disabled)

CUSTOM_DNS

DNS Provider

DNS provider for domain resolution. 'Auto' rotates through providers on failure.

  • Type: string (choice)
  • Default: auto
  • Options: auto (Auto (Recommended)), system (System), google (Google), cloudflare (Cloudflare), quad9 (Quad9), opendns (OpenDNS), manual (Manual)

CUSTOM_DNS_MANUAL

Manual DNS Servers

Comma-separated list of DNS server IP addresses (e.g., 8.8.8.8, 1.1.1.1).

  • Type: string
  • Default: none

USE_DOH

Use DNS over HTTPS

Use encrypted DNS queries for improved reliability and privacy.

  • Type: boolean
  • Default: true

USING_TOR

Tor Routing

Route all traffic through Tor for enhanced privacy. Requires root startup.

  • Type: boolean
  • Default: false

PROXY_MODE

Proxy Mode

Choose proxy type. SOCKS5 handles all traffic through a single proxy.

  • Type: string (choice)
  • Default: none
  • Options: none (None (Direct Connection)), http (HTTP/HTTPS Proxy), socks5 (SOCKS5 Proxy)

HTTP_PROXY

HTTP Proxy

HTTP proxy URL (e.g., http://proxy:8080)

  • Type: string
  • Default: none

HTTPS_PROXY

HTTPS Proxy

HTTPS proxy URL (leave empty to use HTTP proxy for HTTPS)

  • Type: string
  • Default: none

SOCKS5_PROXY

SOCKS5 Proxy

SOCKS5 proxy URL. Supports auth: socks5://user:pass@host:port

  • Type: string
  • Default: none

NO_PROXY

No Proxy

Comma-separated hosts to bypass proxy (e.g., localhost,127.0.0.1,10.,.local)

  • Type: string
  • Default: none

Advanced

Variable Description Type Default
URL_BASE Optional URL path prefix. Use a path like /shelfmark (no hostname). Leave blank for root. string none
DEBUG Enable verbose logging to console and file. Not recommended for normal use. boolean false
MAIN_LOOP_SLEEP_TIME How often the download queue is checked for new items. number 5
DOWNLOAD_PROGRESS_UPDATE_INTERVAL How often download progress is broadcast to the UI. number 1
CUSTOM_SCRIPT Path to a script to run after each successful download. Must be executable. string none
CUSTOM_SCRIPT_PATH_MODE Pass the path to the custom script as an absolute path or relative to the destination folder. string (choice) absolute
CUSTOM_SCRIPT_JSON_PAYLOAD Send a JSON payload to the script via stdin. Useful for multi-file imports (audiobooks) or richer metadata without relying on path parsing. boolean false
COVERS_CACHE_ENABLED Cache book covers on the server for faster loading. boolean true
COVERS_CACHE_TTL How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork). number 0
COVERS_CACHE_MAX_SIZE_MB Maximum disk space for cached covers. Oldest images are removed when limit is reached. number 500
METADATA_CACHE_ENABLED When disabled, all metadata searches hit the provider API directly. boolean true
METADATA_CACHE_SEARCH_TTL How long to cache search results. Default: 300 (5 minutes). Max: 604800 (7 days). number 300
METADATA_CACHE_BOOK_TTL How long to cache individual book details. Default: 600 (10 minutes). Max: 604800 (7 days). number 600
Detailed descriptions

URL_BASE

Base Path

Optional URL path prefix. Use a path like /shelfmark (no hostname). Leave blank for root.

  • Type: string
  • Default: none
  • Requires restart: Yes

DEBUG

Debug Mode

Enable verbose logging to console and file. Not recommended for normal use.

  • Type: boolean
  • Default: false
  • Requires restart: Yes

MAIN_LOOP_SLEEP_TIME

Queue Check Interval (seconds)

How often the download queue is checked for new items.

  • Type: number
  • Default: 5
  • Requires restart: Yes
  • Constraints: min: 1, max: 60

DOWNLOAD_PROGRESS_UPDATE_INTERVAL

Progress Update Interval (seconds)

How often download progress is broadcast to the UI.

  • Type: number
  • Default: 1
  • Requires restart: Yes
  • Constraints: min: 1, max: 10

CUSTOM_SCRIPT

Custom Script Path

Path to a script to run after each successful download. Must be executable.

  • Type: string
  • Default: none

CUSTOM_SCRIPT_PATH_MODE

Custom Script Path Mode

Pass the path to the custom script as an absolute path or relative to the destination folder.

  • Type: string (choice)
  • Default: absolute
  • Options: absolute (Absolute), relative (Relative)

CUSTOM_SCRIPT_JSON_PAYLOAD

Custom Script JSON Payload

Send a JSON payload to the script via stdin. Useful for multi-file imports (audiobooks) or richer metadata without relying on path parsing.

  • Type: boolean
  • Default: false

COVERS_CACHE_ENABLED

Enable Cover Cache

Cache book covers on the server for faster loading.

  • Type: boolean
  • Default: true

COVERS_CACHE_TTL

Cache TTL (days)

How long to keep cached covers. Set to 0 to keep forever (recommended for static artwork).

  • Type: number
  • Default: 0
  • Constraints: min: 0, max: 365

COVERS_CACHE_MAX_SIZE_MB

Max Cache Size (MB)

Maximum disk space for cached covers. Oldest images are removed when limit is reached.

  • Type: number
  • Default: 500
  • Constraints: min: 50, max: 5000

METADATA_CACHE_ENABLED

Enable Metadata Caching

When disabled, all metadata searches hit the provider API directly.

  • Type: boolean
  • Default: true

METADATA_CACHE_SEARCH_TTL

Search Results Cache (seconds)

How long to cache search results. Default: 300 (5 minutes). Max: 604800 (7 days).

  • Type: number
  • Default: 300
  • Constraints: min: 60, max: 604800

METADATA_CACHE_BOOK_TTL

Book Details Cache (seconds)

How long to cache individual book details. Default: 600 (10 minutes). Max: 604800 (7 days).

  • Type: number
  • Default: 600
  • Constraints: min: 60, max: 604800

Prowlarr

Variable Description Type Default
PROWLARR_ENABLED Enable searching for books via Prowlarr indexers boolean false
PROWLARR_URL Base URL of your Prowlarr instance string none
PROWLARR_API_KEY Found in Prowlarr: Settings > General > API Key string (secret) none
PROWLARR_INDEXERS Select which indexers to search. 📚 = has book categories. Leave empty to search all. string (comma-separated) empty list
PROWLARR_AUTO_EXPAND Automatically retry search without category filtering if no results are found boolean false
PROWLARR_USE_SEED_PREFERENCES Apply per-indexer seed time and ratio preferences from Prowlarr when sending torrents to the download client boolean false
Detailed descriptions

PROWLARR_ENABLED

Enable Prowlarr source

Enable searching for books via Prowlarr indexers

  • Type: boolean
  • Default: false

PROWLARR_URL

Prowlarr URL

Base URL of your Prowlarr instance

  • Type: string
  • Default: none
  • Required: Yes

PROWLARR_API_KEY

API Key

Found in Prowlarr: Settings > General > API Key

  • Type: string (secret)
  • Default: none
  • Required: Yes

PROWLARR_INDEXERS

Indexers to Search

Select which indexers to search. 📚 = has book categories. Leave empty to search all.

  • Type: string (comma-separated)
  • Default: empty list

PROWLARR_AUTO_EXPAND

Auto-expand search on no results

Automatically retry search without category filtering if no results are found

  • Type: boolean
  • Default: false

PROWLARR_USE_SEED_PREFERENCES

Use Prowlarr seed preferences

Apply per-indexer seed time and ratio preferences from Prowlarr when sending torrents to the download client

  • Type: boolean
  • Default: false

Newznab

Variable Description Type Default
NEWZNAB_ENABLED Enable searching for books via a Newznab-compatible indexer boolean false
NEWZNAB_URL Base URL of your Newznab indexer or aggregator string none
NEWZNAB_API_KEY Your Newznab API key (leave blank if not required) string (secret) none
NEWZNAB_AUTO_EXPAND Automatically retry search without category filtering if no results are found boolean false
Detailed descriptions

NEWZNAB_ENABLED

Enable Newznab source

Enable searching for books via a Newznab-compatible indexer

  • Type: boolean
  • Default: false

NEWZNAB_URL

Newznab URL

Base URL of your Newznab indexer or aggregator

  • Type: string
  • Default: none
  • Required: Yes

NEWZNAB_API_KEY

API Key

Your Newznab API key (leave blank if not required)

  • Type: string (secret)
  • Default: none

NEWZNAB_AUTO_EXPAND

Auto-expand search on no results

Automatically retry search without category filtering if no results are found

  • Type: boolean
  • Default: false

AudiobookBay

Variable Description Type Default
ABB_ENABLED Enable AudiobookBay as a release source for audiobooks. boolean false
ABB_HOSTNAME AudiobookBay domain (e.g., audiobookbay.lu, audiobookbay.is). Required to enable searches. string empty string
ABB_PAGE_LIMIT Maximum number of search result pages to fetch (1-10). number 1
ABB_EXACT_PHRASE Wrap generated queries in quotes for stricter matching. If no results are found, Shelfmark retries without quotes. boolean false
ABB_RATE_LIMIT_DELAY Delay between requests in seconds to avoid rate limiting (0-10). number 1.0
Detailed descriptions

ABB_ENABLED

Enable AudiobookBay

Enable AudiobookBay as a release source for audiobooks.

  • Type: boolean
  • Default: false

ABB_HOSTNAME

Hostname

AudiobookBay domain (e.g., audiobookbay.lu, audiobookbay.is). Required to enable searches.

  • Type: string
  • Default: empty string
  • Required: Yes

ABB_PAGE_LIMIT

Max Pages to Search

Maximum number of search result pages to fetch (1-10).

  • Type: number
  • Default: 1
  • Constraints: min: 1, max: 10

ABB_EXACT_PHRASE

Prefer Exact-Phrase Search

Wrap generated queries in quotes for stricter matching. If no results are found, Shelfmark retries without quotes.

  • Type: boolean
  • Default: false

ABB_RATE_LIMIT_DELAY

Rate Limit Delay (seconds)

Delay between requests in seconds to avoid rate limiting (0-10).

  • Type: number
  • Default: 1.0
  • Constraints: min: 0.0, max: 10.0

IRC

Variable Description Type Default
IRC_SERVER IRC server hostname string none
IRC_PORT IRC server port (usually 6697 for TLS, 6667 for plain) number 6697
IRC_USE_TLS Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS. boolean true
IRC_CHANNEL Channel name without the # prefix string none
IRC_NICK Your IRC nickname (required). Must be unique on the IRC network. string none
IRC_SEARCH_BOT The search bot to query for results string none
IRC_CACHE_TTL How long to keep cached search results before they expire. string (choice) 2592000
Detailed descriptions

IRC_SERVER

Server

IRC server hostname

  • Type: string
  • Default: none
  • Required: Yes

IRC_PORT

Port

IRC server port (usually 6697 for TLS, 6667 for plain)

  • Type: number
  • Default: 6697

IRC_USE_TLS

Use TLS

Enable TLS/SSL encryption for the IRC connection. Disable for servers that don't support TLS.

  • Type: boolean
  • Default: true

IRC_CHANNEL

Channel

Channel name without the # prefix

  • Type: string
  • Default: none
  • Required: Yes

IRC_NICK

Nickname

Your IRC nickname (required). Must be unique on the IRC network.

  • Type: string
  • Default: none
  • Required: Yes

IRC_SEARCH_BOT

Search bot

The search bot to query for results

  • Type: string
  • Default: none

IRC_CACHE_TTL

Cache Duration

How long to keep cached search results before they expire.

  • Type: string (choice)
  • Default: 2592000
  • Options: 2592000 (30 days), 0 (Forever (until manually cleared))

Download Clients

Variable Description Type Default
PROWLARR_TORRENT_CLIENT Choose which torrent client to use string (choice) empty string
QBITTORRENT_URL Web UI URL of your qBittorrent instance string none
QBITTORRENT_USERNAME qBittorrent Web UI username string none
QBITTORRENT_PASSWORD qBittorrent Web UI password string (secret) none
QBITTORRENT_CATEGORY Category to assign to book downloads in qBittorrent string books
QBITTORRENT_CATEGORY_AUDIOBOOK Category for audiobook downloads. Leave empty to use the book category. string empty string
QBITTORRENT_DOWNLOAD_DIR Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified) string none
QBITTORRENT_TAG Tag(s) to assign to qBittorrent downloads. Leave empty for no tags. string (comma-separated) empty list
TRANSMISSION_URL URL of your Transmission instance (use https:// for TLS) string none
TRANSMISSION_USERNAME Transmission RPC username (if authentication enabled) string none
TRANSMISSION_PASSWORD Transmission RPC password string (secret) none
TRANSMISSION_CATEGORY Label to assign to book downloads in Transmission string books
TRANSMISSION_CATEGORY_AUDIOBOOK Label for audiobook downloads. Leave empty to use the book label. string empty string
TRANSMISSION_DOWNLOAD_DIR Server-side directory where torrents are downloaded (optional, uses Transmission default if not specified) string none
DELUGE_HOST Hostname/IP or full URL of your Deluge Web UI (deluge-web) string localhost
DELUGE_PORT Deluge Web UI port (default: 8112) string 8112
DELUGE_PASSWORD Deluge Web UI password (default: deluge) string (secret) none
DELUGE_CATEGORY Label to assign to book downloads in Deluge string books
DELUGE_CATEGORY_AUDIOBOOK Label for audiobook downloads. Leave empty to use the book label. string empty string
DELUGE_DOWNLOAD_DIR Server-side directory where torrents are downloaded (optional, uses Deluge default if not specified) string none
RTORRENT_URL XML-RPC URL of your rTorrent instance string none
RTORRENT_USERNAME HTTP Basic auth username (if authentication enabled) string none
RTORRENT_PASSWORD HTTP Basic auth password string (secret) none
RTORRENT_LABEL Label to assign to book downloads in rTorrent string cwabd
RTORRENT_DOWNLOAD_DIR Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified) string none
PROWLARR_TORRENT_ACTION Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding string (choice) keep
PROWLARR_USENET_CLIENT Choose which usenet client to use string (choice) empty string
NZBGET_URL URL of your NZBGet instance string none
NZBGET_USERNAME NZBGet control username string nzbget
NZBGET_PASSWORD NZBGet control password string (secret) none
NZBGET_CATEGORY Category to assign to book downloads in NZBGet string Books
NZBGET_CATEGORY_AUDIOBOOK Category for audiobook downloads. Leave empty to use the book category. string empty string
SABNZBD_URL URL of your SABnzbd instance string none
SABNZBD_API_KEY Found in SABnzbd: Config > General > API Key string (secret) none
SABNZBD_CATEGORY Category to assign to book downloads in SABnzbd string books
SABNZBD_CATEGORY_AUDIOBOOK Category for audiobook downloads. Leave empty to use the book category. string empty string
PROWLARR_USENET_ACTION Move deletes the job from your usenet client after import; Copy keeps it in the client string (choice) move
Detailed descriptions

PROWLARR_TORRENT_CLIENT

Torrent Client

Choose which torrent client to use

  • Type: string (choice)
  • Default: empty string
  • Options: "" (None), qbittorrent (qBittorrent), transmission (Transmission), deluge (Deluge), rtorrent (rTorrent)

QBITTORRENT_URL

qBittorrent URL

Web UI URL of your qBittorrent instance

  • Type: string
  • Default: none

QBITTORRENT_USERNAME

Username

qBittorrent Web UI username

  • Type: string
  • Default: none

QBITTORRENT_PASSWORD

Password

qBittorrent Web UI password

  • Type: string (secret)
  • Default: none

QBITTORRENT_CATEGORY

Book Category

Category to assign to book downloads in qBittorrent

  • Type: string
  • Default: books

QBITTORRENT_CATEGORY_AUDIOBOOK

Audiobook Category

Category for audiobook downloads. Leave empty to use the book category.

  • Type: string
  • Default: empty string

QBITTORRENT_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses qBittorrent default if not specified)

  • Type: string
  • Default: none

QBITTORRENT_TAG

Tags

Tag(s) to assign to qBittorrent downloads. Leave empty for no tags.

  • Type: string (comma-separated)
  • Default: empty list

TRANSMISSION_URL

Transmission URL

URL of your Transmission instance (use https:// for TLS)

  • Type: string
  • Default: none

TRANSMISSION_USERNAME

Username

Transmission RPC username (if authentication enabled)

  • Type: string
  • Default: none

TRANSMISSION_PASSWORD

Password

Transmission RPC password

  • Type: string (secret)
  • Default: none

TRANSMISSION_CATEGORY

Book Label

Label to assign to book downloads in Transmission

  • Type: string
  • Default: books

TRANSMISSION_CATEGORY_AUDIOBOOK

Audiobook Label

Label for audiobook downloads. Leave empty to use the book label.

  • Type: string
  • Default: empty string

TRANSMISSION_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses Transmission default if not specified)

  • Type: string
  • Default: none

DELUGE_HOST

Deluge Web UI Host/URL

Hostname/IP or full URL of your Deluge Web UI (deluge-web)

  • Type: string
  • Default: localhost

DELUGE_PORT

Deluge Web UI Port

Deluge Web UI port (default: 8112)

  • Type: string
  • Default: 8112

DELUGE_PASSWORD

Password

Deluge Web UI password (default: deluge)

  • Type: string (secret)
  • Default: none

DELUGE_CATEGORY

Book Label

Label to assign to book downloads in Deluge

  • Type: string
  • Default: books

DELUGE_CATEGORY_AUDIOBOOK

Audiobook Label

Label for audiobook downloads. Leave empty to use the book label.

  • Type: string
  • Default: empty string

DELUGE_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses Deluge default if not specified)

  • Type: string
  • Default: none

RTORRENT_URL

rTorrent URL

XML-RPC URL of your rTorrent instance

  • Type: string
  • Default: none

RTORRENT_USERNAME

Username

HTTP Basic auth username (if authentication enabled)

  • Type: string
  • Default: none

RTORRENT_PASSWORD

Password

HTTP Basic auth password

  • Type: string (secret)
  • Default: none

RTORRENT_LABEL

Book Label

Label to assign to book downloads in rTorrent

  • Type: string
  • Default: cwabd

RTORRENT_DOWNLOAD_DIR

Download Directory

Server-side directory where torrents are downloaded (optional, uses rTorrent default if not specified)

  • Type: string
  • Default: none

PROWLARR_TORRENT_ACTION

Torrent Completion Action

Remove deletes the torrent from your client immediately after import (stops seeding, files are kept); Keep leaves it in the client to continue seeding

  • Type: string (choice)
  • Default: keep
  • Options: keep (Keep), remove (Remove)

PROWLARR_USENET_CLIENT

Usenet Client

Choose which usenet client to use

  • Type: string (choice)
  • Default: empty string
  • Options: "" (None), nzbget (NZBGet), sabnzbd (SABnzbd)

NZBGET_URL

NZBGet URL

URL of your NZBGet instance

  • Type: string
  • Default: none

NZBGET_USERNAME

Username

NZBGet control username

  • Type: string
  • Default: nzbget

NZBGET_PASSWORD

Password

NZBGet control password

  • Type: string (secret)
  • Default: none

NZBGET_CATEGORY

Book Category

Category to assign to book downloads in NZBGet

  • Type: string
  • Default: Books

NZBGET_CATEGORY_AUDIOBOOK

Audiobook Category

Category for audiobook downloads. Leave empty to use the book category.

  • Type: string
  • Default: empty string

SABNZBD_URL

SABnzbd URL

URL of your SABnzbd instance

  • Type: string
  • Default: none

SABNZBD_API_KEY

API Key

Found in SABnzbd: Config > General > API Key

  • Type: string (secret)
  • Default: none

SABNZBD_CATEGORY

Book Category

Category to assign to book downloads in SABnzbd

  • Type: string
  • Default: books

SABNZBD_CATEGORY_AUDIOBOOK

Audiobook Category

Category for audiobook downloads. Leave empty to use the book category.

  • Type: string
  • Default: empty string

PROWLARR_USENET_ACTION

NZB Completion Action

Move deletes the job from your usenet client after import; Copy keeps it in the client

  • Type: string (choice)
  • Default: move
  • Options: move (Move), copy (Copy)

Metadata Providers

Metadata Providers: Hardcover

Variable Description Type Default
HARDCOVER_ENABLED Enable Hardcover as a metadata provider for book searches boolean false
HARDCOVER_API_KEY Get your API key from hardcover.app/account/api string (secret) none
HARDCOVER_DEFAULT_SORT Default sort order for Hardcover search results. string (choice) relevance
HARDCOVER_EXCLUDE_COMPILATIONS Filter out compilations, anthologies, and omnibus editions from search results boolean false
HARDCOVER_EXCLUDE_UNRELEASED Filter out books with a release year in the future boolean false
HARDCOVER_AUTO_REMOVE_ON_DOWNLOAD Automatically remove a book from the active Hardcover list when you download it boolean true
Detailed descriptions

HARDCOVER_ENABLED

Enable Hardcover

Enable Hardcover as a metadata provider for book searches

  • Type: boolean
  • Default: false

HARDCOVER_API_KEY

API Key

Get your API key from hardcover.app/account/api

  • Type: string (secret)
  • Default: none
  • Required: Yes

HARDCOVER_DEFAULT_SORT

Default Sort Order

Default sort order for Hardcover search results.

  • Type: string (choice)
  • Default: relevance
  • Options: relevance (Most relevant), popularity (Most popular), rating (Highest rated), newest (Newest), oldest (Oldest)

HARDCOVER_EXCLUDE_COMPILATIONS

Exclude Compilations

Filter out compilations, anthologies, and omnibus editions from search results

  • Type: boolean
  • Default: false

HARDCOVER_EXCLUDE_UNRELEASED

Exclude Unreleased Books

Filter out books with a release year in the future

  • Type: boolean
  • Default: false

HARDCOVER_AUTO_REMOVE_ON_DOWNLOAD

Auto-Remove from List on Download

Automatically remove a book from the active Hardcover list when you download it

  • Type: boolean
  • Default: true

Metadata Providers: Open Library

Variable Description Type Default
OPENLIBRARY_ENABLED Enable Open Library as a metadata provider for book searches boolean false
OPENLIBRARY_DEFAULT_SORT Default sort order for Open Library search results. string (choice) relevance
Detailed descriptions

OPENLIBRARY_ENABLED

Enable Open Library

Enable Open Library as a metadata provider for book searches

  • Type: boolean
  • Default: false

OPENLIBRARY_DEFAULT_SORT

Default Sort Order

Default sort order for Open Library search results.

  • Type: string (choice)
  • Default: relevance
  • Options: relevance (Most relevant), newest (Newest), oldest (Oldest)

Metadata Providers: Google Books

Variable Description Type Default
GOOGLEBOOKS_ENABLED Enable Google Books as a metadata provider for book searches boolean false
GOOGLEBOOKS_API_KEY Get your API key from Google Cloud Console (APIs & Services > Credentials) string (secret) none
GOOGLEBOOKS_DEFAULT_SORT Default sort order for Google Books search results. string (choice) relevance
Detailed descriptions

GOOGLEBOOKS_ENABLED

Enable Google Books

Enable Google Books as a metadata provider for book searches

  • Type: boolean
  • Default: false

GOOGLEBOOKS_API_KEY

API Key

Get your API key from Google Cloud Console (APIs & Services > Credentials)

  • Type: string (secret)
  • Default: none
  • Required: Yes

GOOGLEBOOKS_DEFAULT_SORT

Default Sort Order

Default sort order for Google Books search results.

  • Type: string (choice)
  • Default: relevance
  • Options: relevance (Most relevant), newest (Newest)

Direct Download

Direct Download: Download Sources

Variable Description Type Default
DIRECT_DOWNLOAD_ENABLED Show Direct Download in release-source lists and allow Direct mode searches. Add your own mirror URLs in the Mirrors tab before using it. boolean false
AA_DONATOR_KEY Enables fast download access on AA. Get this from your donator account page. string (secret) none
FAST_SOURCES_DISPLAY Always tried first, no waiting or bypass required. JSON array see UI for defaults
SOURCE_PRIORITY Fallback sources, may have waiting. Requires bypasser. Drag to reorder. JSON array see UI for defaults
MAX_RETRY Maximum retry attempts for failed downloads. number 10
DEFAULT_SLEEP Wait time between download retry attempts. number 5
AA_CONTENT_TYPE_ROUTING Override destination based on content type metadata. boolean false
AA_CONTENT_TYPE_DIR_FICTION Fiction Books string none
AA_CONTENT_TYPE_DIR_NON_FICTION Non-Fiction Books string none
AA_CONTENT_TYPE_DIR_UNKNOWN Unknown Books string none
AA_CONTENT_TYPE_DIR_MAGAZINE Magazines string none
AA_CONTENT_TYPE_DIR_COMIC Comic Books string none
AA_CONTENT_TYPE_DIR_STANDARDS Standards Documents string none
AA_CONTENT_TYPE_DIR_MUSICAL_SCORE Musical Scores string none
AA_CONTENT_TYPE_DIR_OTHER Other string none
Detailed descriptions

DIRECT_DOWNLOAD_ENABLED

Enable Direct Download Source

Show Direct Download in release-source lists and allow Direct mode searches. Add your own mirror URLs in the Mirrors tab before using it.

  • Type: boolean
  • Default: false

AA_DONATOR_KEY

Account Donator Key

Enables fast download access on AA. Get this from your donator account page.

  • Type: string (secret)
  • Default: none

FAST_SOURCES_DISPLAY

Fast downloads

Always tried first, no waiting or bypass required.

  • Type: JSON array
  • Default: see UI for defaults

SOURCE_PRIORITY

Slow downloads

Fallback sources, may have waiting. Requires bypasser. Drag to reorder.

  • Type: JSON array
  • Default: see UI for defaults

MAX_RETRY

Max Retries

Maximum retry attempts for failed downloads.

  • Type: number
  • Default: 10
  • Constraints: min: 1, max: 50

DEFAULT_SLEEP

Retry Delay (seconds)

Wait time between download retry attempts.

  • Type: number
  • Default: 5
  • Constraints: min: 1, max: 60

AA_CONTENT_TYPE_ROUTING

Enable Content-Type Routing

Override destination based on content type metadata.

  • Type: boolean
  • Default: false

AA_CONTENT_TYPE_DIR_FICTION

Fiction Books

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_NON_FICTION

Non-Fiction Books

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_UNKNOWN

Unknown Books

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_MAGAZINE

Magazines

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_COMIC

Comic Books

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_STANDARDS

Standards Documents

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_MUSICAL_SCORE

Musical Scores

  • Type: string
  • Default: none

AA_CONTENT_TYPE_DIR_OTHER

Other

  • Type: string
  • Default: none

Direct Download: Cloudflare Bypass

Variable Description Type Default
USE_CF_BYPASS Attempt to bypass Cloudflare protection on download sites. boolean true
USING_EXTERNAL_BYPASSER Use FlareSolverr or similar external service instead of built-in bypasser. Caution: May have limitations with custom DNS, Tor and proxies. You may experience slower downloads and and poorer reliability compared to the internal bypasser. boolean false
EXT_BYPASSER_URL URL of the external bypasser service (e.g., FlareSolverr). string http://flaresolverr:8191
EXT_BYPASSER_PATH API path for the external bypasser. string /v1
EXT_BYPASSER_TIMEOUT Timeout for external bypasser requests in milliseconds. number 60000
Detailed descriptions

USE_CF_BYPASS

Enable Cloudflare Bypass

Attempt to bypass Cloudflare protection on download sites.

  • Type: boolean
  • Default: true
  • Requires restart: Yes

USING_EXTERNAL_BYPASSER

Use External Bypasser

Use FlareSolverr or similar external service instead of built-in bypasser. Caution: May have limitations with custom DNS, Tor and proxies. You may experience slower downloads and and poorer reliability compared to the internal bypasser.

  • Type: boolean
  • Default: false
  • Requires restart: Yes

EXT_BYPASSER_URL

External Bypasser URL

URL of the external bypasser service (e.g., FlareSolverr).

  • Type: string
  • Default: http://flaresolverr:8191
  • Requires restart: Yes

EXT_BYPASSER_PATH

External Bypasser Path

API path for the external bypasser.

  • Type: string
  • Default: /v1
  • Requires restart: Yes

EXT_BYPASSER_TIMEOUT

External Bypasser Timeout (ms)

Timeout for external bypasser requests in milliseconds.

  • Type: number
  • Default: 60000
  • Requires restart: Yes
  • Constraints: min: 10000, max: 300000

Direct Download: Mirrors

Variable Description Type Default
AA_BASE_URL Select Auto to try mirrors from your list on startup and fail over on errors. Choosing a specific mirror pins Shelfmark to that URL. string (choice) auto
AA_MIRROR_URLS List the Anna's Archive mirror URLs you want Shelfmark to use. Type a URL and press Enter to add it. Order matters when Auto is selected. string (comma-separated) empty list
LIBGEN_MIRROR_URLS Mirrors are tried in the order you add them until one works. string (comma-separated) empty list
ZLIB_MIRROR_URLS Only the first mirror in the list is used. string (comma-separated) empty list
WELIB_MIRROR_URLS Only the first mirror in the list is used. string (comma-separated) empty list
Detailed descriptions

AA_BASE_URL

Primary Mirror

Select Auto to try mirrors from your list on startup and fail over on errors. Choosing a specific mirror pins Shelfmark to that URL.

  • Type: string (choice)
  • Default: auto
  • Options: auto (Auto (Recommended))

AA_MIRROR_URLS

Mirrors

List the Anna's Archive mirror URLs you want Shelfmark to use. Type a URL and press Enter to add it. Order matters when Auto is selected.

  • Type: string (comma-separated)
  • Default: empty list

LIBGEN_MIRROR_URLS

LibGen

Mirrors are tried in the order you add them until one works.

  • Type: string (comma-separated)
  • Default: empty list

ZLIB_MIRROR_URLS

Z-Library

Only the first mirror in the list is used.

  • Type: string (comma-separated)
  • Default: empty list

WELIB_MIRROR_URLS

Welib

Only the first mirror in the list is used.

  • Type: string (comma-separated)
  • Default: empty list