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"