Skip to content

Configuration

Environment variables, config.toml, and precedence.

Everything is optional — a bare docker compose up -d works. Precedence, lowest to highest: built-in defaults ← config.toml in the config dir (may be absent) ← SUMIDOKU_* environment variables ← --config-dir (the only CLI flag, highest precedence; every other argument is a startup error). config.toml keys are the snake_case names of the variables below (net.* and auth.* sections for the grouped ones).

The one data root is the config dir: the database, cover cache, source packages (sources/), materialized page images (page-blobs/) and the default scheduled-backup destination (backups/) all live under it and are not separately configurable. sources/ in particular is pinned — drop packages there and scan, no path setting exists. config.toml is read from this directory too, so the config dir itself is CLI/environment-only: a config_dir key in the file is ignored with a warning (the file cannot relocate the directory it is read from).

Volumes (Docker)

Volume Purpose
/config the config dir: database, settings, cover cache, source packages
/downloads downloaded chapters

Windows desktop

The Windows build is a desktop app: it logs to stdout and to a daily rolling file under <config>/logs (7 files kept), and in an interactive session it shows a tray icon with Open / Open config dir / Open logs dir / Start with Windows / Exit. Start with Windows writes the HKCU\Software\Microsoft\Windows\CurrentVersion\Run\Sumidoku value as "<exe>" --config-dir "<absolute config dir>", so the logon start finds the same data root regardless of its working directory. Non-interactive sessions (a service, a scheduled task) get no icon and run headless with the same configuration channels.

Tracker OAuth

Tracker sign-ins (AniList, MyAnimeList, Bangumi, MangaBaka) use OAuth apps registered to the project, with the redirect URI hosted at https://sumidoku.github.io/oauth (the Sumidoku/oauth Pages site): the provider returns there and the relay bounces the browser to the instance callback named in the OAuth state. The client credentials are compile-time values, not runtime configuration: official release binaries bake them in (option_env!), and a build without them serves tracker browsing normally but answers the OAuth start endpoint with an error naming the missing variable. Self-builders who want sign-ins set the eight SUMIDOKU_OAUTH_<PROVIDER>_CLIENT_ID / _CLIENT_SECRET pairs in the environment when compiling (a cargo build with the variables exported is enough; cross builds forward them via Cross.toml).

Server

Variable Default Purpose
SUMIDOKU_ADDR 0.0.0.0:3000 (127.0.0.1:3000 on Windows) listen address; the Windows desktop default binds loopback only, so a desktop install without auth is not exposed to the LAN
SUMIDOKU_CONFIG_DIR /config in Docker, %LOCALAPPDATA%\Sumidoku on Windows, ./data otherwise data root (see above); config.toml is read from here
SUMIDOKU_LOG info log level (tracing filter)
SUMIDOKU_CALL_CONCURRENCY 8 max concurrent calls into a source instance
SUMIDOKU_TASK_POOL_SIZE 2 background task workers; tasks of one source still serialize regardless of pool size
SUMIDOKU_USER_AGENT a Chrome desktop UA global User-Agent for source fetches
SUMIDOKU_COVER_CACHE_MAX 2048 max cached cover files on disk; least recently served go first, covers of manga outside the library before library covers
SUMIDOKU_WEBUI_DIR ./webui/build serve the web UI from this directory instead of the embedded build
SUMIDOKU_SOURCE_IDLE_EVICT_MINUTES 30 evict source instances idle longer than this; 0 or negative disables the sweep
SUMIDOKU_RSS_THRESHOLD_MB 1024 process RSS threshold; above it the monitor evicts source instances most-idle first (in-flight calls are never touched). 0 disables the monitor
SUMIDOKU_LOCAL_DIRS [<config>/local] local manga roots scanned by the built-in Local source, semicolon-separated (empty segments ignored); the roots merge into one shelf, a relative path present in several roots lists the first root’s copy, and keys from root N ≥ 1 carry the N: prefix. Overridable at runtime by the local.dirs setting from the Settings page
SUMIDOKU_LOCAL_DIR — one-item fallback for SUMIDOKU_LOCAL_DIRS, used only when that is unset
SUMIDOKU_LOCAL_ONESHOTS_DIR — name marking a oneshots directory for the Local source (empty = off): a directory whose relative path contains it (case-insensitive substring) is never listed itself, and every archive directly inside becomes its own one-chapter manga titled by the file stem. Overridable at runtime by the local.oneshots_dir setting from the Settings page
SUMIDOKU_LOCAL_SCAN_SECS 0 (off) interval between scheduled full scans of every local instance; 0 disables only the scheduler — manual, browse-kicked, startup and settings-triggered scans still run
SUMIDOKU_LOCAL_SCAN_ON_STARTUP false enqueue a full scan of every local instance at startup
SUMIDOKU_LOCAL_SCAN_EXCLUSIONS [] semicolon-separated path substrings excluded from local scans (case-insensitive, empty entries ignored). Overridable per instance by the exclusions setting from the Settings page
SUMIDOKU_LOCAL_SCAN_FORCE_MODIFIED_TIME false global default for the per-instance forceModifiedTime switch: also folds file mtimes into the scan change detector, catching in-place archive edits (overridable from the Settings page)
SUMIDOKU_LOCAL_ANALYZE_PAGES true global default for the analyzePages switch: the post-scan analysis pass fills chapter page rows through the reader’s own load_pages (overridable from the Settings page)
SUMIDOKU_LOCAL_ANALYZE_METADATA true global default for the analyzeMetadata switch: the analysis pass fills embedded ComicInfo/OPF metadata and manga-level aggregates (overridable from the Settings page)

Local scans reconcile the persisted index against the filesystem: newly discovered manga and chapters are indexed at enumeration cost, and entries that vanished on disk are soft-deleted into the trash bin (GET/DELETE /api/v1/local/trash), never hard-deleted. Per-instance settings from the Settings page — exclusions, forceModifiedTime, analyzePages, analyzeMetadata — override the config fallbacks above (scan-affecting changes re-scan the instance automatically); the post-scan analysis pass fills embedded metadata and page rows when the analyze* switches are on. Existing local libraries are backfilled by the first scan after an upgrade: browsing an instance with no rows kicks one automatically, while an instance with previously opened/shelved rows keeps showing that persisted subset until a scan runs (manual “scan now”, scheduled, or startup).

WASM runtime

Variable Default Purpose
SUMIDOKU_WASM_MEMORY_MAX_MB 128 per-source wasm linear-memory cap; memory.grow beyond it fails
SUMIDOKU_WASM_FUEL 10000000000 instruction budget per source export call
SUMIDOKU_WASM_CALL_TIMEOUT_SECS 60 per-call wall-clock timeout; a timed-out call restarts the instance

Library updates and downloads

Variable Default Purpose
SUMIDOKU_UPDATE_INTERVAL_HOURS 0 (off) fallback scheduled library update interval when library.update_interval_hours is unset
SUMIDOKU_AUTO_DOWNLOAD_NEW_CHAPTERS false download chapters found by library updates
SUMIDOKU_AUTO_DOWNLOAD_LIMIT 5 per-manga cap for auto downloads
SUMIDOKU_DOWNLOADS_DIR /downloads in Docker, ./downloads otherwise downloads directory
SUMIDOKU_DOWNLOAD_CONCURRENCY 3 concurrent chapter downloads
SUMIDOKU_DOWNLOAD_FORMAT cbz download container format
SUMIDOKU_DOWNLOAD_MOVE_PATH — override download.move_path (setting default empty = off): move each packaged download to the rendered template path — variables {source}, {title}/{manga}, {author}, {artist}, {chapter}, {filename}; absolute targets like /mnt/library/{author}/{manga}/{filename} are the intended use

The download and library-update behavior settings are re-read from the setting table for each operation, so changes from the Settings page do not require a restart. The corresponding file/env values above are fallbacks when a setting is absent. downloads_dir remains deployment-level and has no runtime override.

Setting key Default Purpose
auto_download_new_chapters false automatically download chapters found by library updates
auto_download_limit 5 maximum automatic downloads per manga per update; 0 disables the candidates
download_format cbz cbz archive or folder image directory
download_concurrency 3 maximum sources downloading concurrently, with one chapter at a time per source
library.excluded_download_categories [] admin category ids excluded from automatic downloads only; manual downloads and reader-ahead are unaffected
downloads.auto_skip_manga_with_unread true skip automatic downloads when chapters that existed before the current refresh are unread; the new chapters themselves do not block
downloads.auto_ignore_reuploads false exclude candidates whose number is below the previous latest chapter number; update results, unread counts and notifications are unchanged
delete_after_manual_read false delete a download after directly marking its chapter read
delete_after_read false delete a download when the reader reaches the final page
allow_delete_bookmarked false allow the two read-driven deletion switches to delete bookmarked chapters
downloads.download_ahead false enqueue following unread chapters after a successful reader page load
downloads.download_ahead_count 2 maximum following unread chapters to consider for reader-ahead

Backup

These four override the backup.* settings (headless deployments); see Backup & Import for the format and scheduling model.

Variable Default Purpose
SUMIDOKU_BACKUP_ENABLED — force scheduled backups on/off, overriding backup.enabled
SUMIDOKU_BACKUP_INTERVAL_HOURS — override backup.interval_hours (setting default 24)
SUMIDOKU_BACKUP_RETENTION_COUNT — override backup.retention_count (setting default 10)
SUMIDOKU_BACKUP_DIR <config>/backups scheduled-backup destination; may live outside the config dir

Authentication

See Authentication for the model.

Variable Default Purpose
SUMIDOKU_AUTH_USERNAME admin built-in admin’s login username, written onto the user row on every boot; exposed by /api/v1/auth/status only with a valid authenticated identity
SUMIDOKU_AUTH_PASSWORD — built-in admin’s password, re-seeded on every boot; enables authentication (username + password login) for the web UI and REST API
SUMIDOKU_BASIC_PASSWORD — legacy alias of SUMIDOKU_AUTH_PASSWORD; only applies when the latter is unset

Network

Sidecar setup and the routing model are in Sidecars.

Variable Default Purpose
SUMIDOKU_NET_PROXY — global forward proxy for source fetches
SUMIDOKU_NET_TRAWL_PROXY — trawl forward-proxy URL; fallback for challenged hosts when solving is unavailable or fails
SUMIDOKU_NET_TRAWL_CA — trawl’s MITM root CA (PEM); required for HTTPS sources through trawl
SUMIDOKU_NET_RELAY_DOMAINS — comma-separated domains always fetched through trawl
SUMIDOKU_NET_DIRECT_DOMAINS — comma-separated domains pinned to direct (never escalated to trawl)
SUMIDOKU_NET_ALLOW_DIRECT_FALLBACK false allow falling back to direct when the proxy path fails
SUMIDOKU_NET_BROWSER_HEADERS true fill the browser header suite (sec-ch-ua, accept, sec-fetch-*, upgrade-insecure-requests) matching the Chrome user agent on source fetches; set false for honest semantics on API/XHR-heavy sources
SUMIDOKU_NET_BROWSER_TRAWL — trawl API URL (e.g. http://trawl:8191, requires trawl ≥ v1.9.1); browser backend for webview using trawl sessions, and the Cloudflare clearance solver: a challenged host is solved once here, then replayed direct with the solving browser’s user agent
SUMIDOKU_NET_BODY_MAX_MB 32 response body cap for source fetches; shared by the wasm net host and the server-side cover/page fetches because both buffer a source-controlled endpoint’s body in the same process — the cap counts decoded bytes; 0 disables
SUMIDOKU_NET_ZIP_BODY_MAX_MB 128 body cap for zip page archives, which pack a whole chapter into one response and legitimately exceed the page-image cap; 0 disables

config.toml example

Placed in the config dir (./data/config.toml outside Docker, /config/config.toml in the image):

addr = "0.0.0.0:3000"
log = "info"

[auth]
username = "admin"
password = "change-me"

[net]
proxy = "http://proxy:8080"
trawl_proxy = "http://trawl:8080"
browser_trawl = "http://trawl:8191"
Navigation

Type to search…

↑↓ navigate↵ selectEsc close