Server Config

There are a number of configuration options that you can set to customize Stump's behavior. You will be setting these options in the Stump.toml file, located within your configured config directory, but you can also set them as environment variables.

If you're using Stump with Docker, you'll want to specify environment variables in either the docker run or docker-compose.yml file to override the default configuration. See the Docker guide for more information.

Below are the available configuration options, loosely grouped by category. If you encounter any values which are not documented, please open an issue or submit a pull request to add them to the documentation.

Core

STUMP_PORT

The port for the Stump server.

STUMP_CONFIG_DIR

The directory where Stump will look for its configuration file.

STUMP_CLIENT_DIR

The directory the contains the web bundle for the web UI

STUMP_DB_PATH

Overrides the path where Stump stores its database file. By default this path is same as parent directory of STUMP_CONFIG_DIR. If set the database would be put at STUMP_DB_PATH/stump.db.

STUMP_ALLOWED_ORIGINS

A comma-delineated list of allowed origins for the Stump API. If you're trying to access the API from a different domain, you'll need to add it to this list. By default, origins corresponding to the Tauri desktop application are allowed, and the host machine's IP address with the configured port is allowed for both HTTP and HTTPS.

Stored as a valid array in the configuration file.

Be sure to replace {machine_ip} and {configured_port} with the appropriate values for your environment.

STUMP_TRUST_PROXY_HEADERS

Whether or not to trust proxy headers like X-Forwarded-For and X-Real-IP for determining the client's IP address. This should only be set to true if Stump is running behind a reverse proxy that is properly configured to set these headers, since it increases the risk of IP spoofing.

Logging

STUMP_VERBOSITY

The verbosity level for Stump logs. Verbosity levels are integers that correspond to a list of log levels that will be visible, and are inclusive of all the levels below them.

For example, if you set the verbosity level to 1, you will see INFO, WARN, and ERROR messages. If you set the verbosity level to 2, you will see DEBUG, INFO, WARN, and ERROR messages, and so on. The default verbosity level is 1.

You may turn off logging entirely by setting the verbosity level to 0. However, this is not recommended, as it will make it difficult to debug issues with Stump if they arise. I generally recommend setting the verbosity to 1, as it allows you to see info-level messages, warnings, and errors.

The available verbosity levels are:

STUMP_PRETTY_LOGS

Controls whether logs are formatted in a human-friendly, pretty-printed style.

Authentication & Sessions

HASH_COST

Controls the computational cost used when hashing user passwords.

SESSION_TTL

The time-to-live for session cookies. This is the amount of time that a session cookie will be valid for in seconds. The default value is 259200, or 3 days. You can set this to a different value if you want sessions to expire sooner or later, depending on your needs.

SESSION_EXPIRY_CLEANUP_INTERVAL

The time (in seconds) between each session expiry cleanup check. The check will remove any expired sessions from the database.

OpenID Connect (OIDC)

port = 10801
# other non-OIDC config...

[oidc] # start of OIDC config
enabled = true
issuer_url = "https://example.com"
# other OIDC config...

STUMP_OIDC_ENABLED

Whether or not to enable OpenID Connect (OIDC) authentication. When enabled, users can sign in using an external identity provider. See the OIDC guide for more information.

STUMP_OIDC_ISSUER_URL

The base URL of your OIDC provider. This should be the URL where the provider's .well-known/openid-configuration endpoint can be found.

Required when STUMP_OIDC_ENABLED is true.

Example: https://pocketid.stump.mycloud

STUMP_OIDC_CLIENT_ID

The client ID provided by your OIDC provider for the Stump application

Required when STUMP_OIDC_ENABLED is true.

STUMP_OIDC_CLIENT_SECRET

The client secret provided by your OIDC provider for the Stump application

Required when STUMP_OIDC_ENABLED is true.

STUMP_OIDC_SCOPES

A comma-separated list of additional scopes to request from the OIDC provider

STUMP_OIDC_ALLOW_REGISTRATION

Whether or not to allow automatic user registration via OIDC on first login. When enabled, users who sign in with OIDC for the first time will have an account automatically created for them.

STUMP_OIDC_DISABLE_LOCAL_AUTH

Whether or not to disable local username/password authentication when OIDC is enabled. When set to true, the username/password login form will be hidden and only OIDC authentication will be available.

Note: Some features, such as OPDS feeds, still require username/password authentication even when this is enabled.

STUMP_OIDC_EXTRA_AUDIENCES

A comma-separated list of additional trusted audiences for ID token verification. This is required when using providers like Zitadel that inject extra values (e.g. the project ID) into the JWT aud claim. See the OIDC guide for more information.

Example: 360960386461073457,another-audience

Integrations

ENABLE_KOBO_SYNC

Whether or not to enable the Kobo sync integration. To learn more about this integration, visit the Kobo guide.

ENABLE_KOREADER_SYNC

Whether or not to enable the KoReader sync integration. This is a special integration that allows KoReader to sync with Stump. To learn more about this integration, visit the KoReader guide.

ENABLE_OPDS_PROGRESSION

Whether or not OPDS page access should automatically track reading progression. When disabled, accessing pages via OPDS won't update reading progress, which prevents inaccurate tracking when clients preload or cache multiple pages at once. This is particularly useful for OPDS clients that load more than one page at a time.

PDF Rendering

PDFIUM_PATH

The path to the PDFium binary. This is only required if you want PDF support and you're running Stump outside of Docker, since the PDFium binary is included in the Docker image. You'll want to find and download the PDFium binary for your platform from here, and then set this environment variable to the path of the binary.

STUMP_PDF_CACHE_PAGES

Controls whether rendered PDF pages are cached.

STUMP_PDF_HIGH_QUALITY

Enables higher-quality PDF rendering at the cost of increased resource usage.

STUMP_PDF_MAX_DIMENSION

Controls the maximum width or height (in pixels) for rendered PDF images.

STUMP_PDF_PRERENDER_RANGE

Controls how many pages before and after the current page should be pre-rendered.

STUMP_PDF_RENDER_DPI

Sets the DPI (dots per inch) used when rendering PDF pages. High values increases image clarity at the cost of memory usage and render time.

STUMP_PDF_RENDER_FORMAT

Specifies the images format used when rendering PDF pages.

File Uploads

STUMP_ENABLE_UPLOAD

STUMP_MAX_FILE_UPLOAD_SIZE

The maximum allowed size, in bytes, of files uploaded via the upload interface. This configuration variable will have no effect unless ENABLE_UPLOAD is true.

STUMP_MAX_IMAGE_UPLOAD_SIZE

The maximum size, in bytes, for images uploaded as thumbnails for users, libraries, series, or media.

Performance

STUMP_MAX_SCANNER_CONCURRENCY

The maximum number of files which may be processed concurrently by the scanner. This is useful for limiting the number of files that are processed at once, which can help prevent the server from becoming overwhelmed on systems with limited resources.

Note: The OS thread scheduler should prevent overload, however, you may want to set this value lower if you're running Stump on a system with limited resources.

STUMP_MAX_THUMBNAIL_CONCURRENCY

The maximum number of images which may be generated concurrently by the thumbnailer. This is useful for limiting the number of thumbnails that are generated at once, which can help prevent the server from becoming overwhelmed on systems with limited resources.

Note: Thumbnail generation is a CPU-intensive process, so you may want to set this value lower if you're running Stump on a system with limited resources.

STUMP_BOOK_COMPLETION_DEDUP_TIMEOUT_SECS

The number of seconds after which a book can be re-completed.

Developer / Advanced

STUMP_ENABLE_PLAYGROUND

Whether or not to enable the GraphQL playground. The playground is an interactive in-browser IDE for exploring the Stump GraphQL API. It is always enabled in development builds.

API_VERSION

The version of the Stump API to use. This should really be left alone and not manually set.

STUMP_PROFILE

The profile to use when running Stump. This should really be left alone and not manually set.