Skip to content

Configuration reference

This page lists every setting you can change. Most people only need the storage paths, and the Docker image already sets those for you.

How to set values

Settings are hierarchical keys such as MangaPixer:Storage:DataRoot. Set them as environment variables, replacing each : with a double underscore __:

# docker compose override
services:
  mangapixer:
    environment:
      MangaPixer__Backups__RetentionCount: "14"
      MangaPixer__Media__MaxConcurrentJobs: "1"

The server also reads appsettings.json next to the server binary. In the container image that file is baked in and the filesystem is read-only, so use environment variables there.

Invalid or out-of-range values (for example a negative number) are ignored and the default is used. The PageVariants settings are the exception: an invalid value there is an error, not ignored (see Media processing).

Every setting on this page is read once at start-up. Restart the container after you change one. The sections below are grouped by the part of the server that uses them.

Container user

These are read by the container's start-up script, not by the server.

Variable Default Meaning
PUID 1000 User ID the server runs as. The script gives this user ownership of /data, /cache, /scratch and /config (whichever exist) on every start.
PGID 1000 Group ID the server runs as.

Set them to the owner of your host folders so the files on the host belong to you. See Install on Unraid.

Memory allocator

1.49.0. The container image sets one more environment variable. It is read by the C library (glibc) that the server and its helper processes use to hand out memory, not by MangaPixer itself, so it is not a MangaPixer__ key and it is not changed on the Performance card.

Variable Default Meaning
MALLOC_ARENA_MAX 2 in the image How many separate memory pools (arenas) glibc may use for the server and for each helper process. glibc normally opens up to eight per processor and keeps the memory freed in each of them, so after heavy work (a big scan, a long reading session) the container held far more memory than the programs were using. With 2, in our test (two people reading for 12 minutes) the container ended at about 0.8 GB instead of about 1.4 GB, and page times were unchanged.

To use glibc's own default again, set the variable to an empty value (MALLOC_ARENA_MAX= in the template, or MALLOC_ARENA_MAX: "" under environment: in the compose file); any other number replaces the 2. Restart the container after you change it. The helper processes inherit it from the server.

Network

Key (environment variable) Default Meaning
ASPNETCORE_URLS http://+:8080 (set in the image) Address and port the server listens on inside the container.
MangaPixer:Network:KnownProxies (MangaPixer__Network__KnownProxies) not set Extra reverse-proxy IP addresses to trust, comma-separated (for example 203.0.113.7).
MangaPixer:Network:KnownNetworks (MangaPixer__Network__KnownNetworks) not set Extra reverse-proxy networks to trust, as comma-separated CIDR ranges (for example 203.0.113.0/24).
MangaPixer:Network:AllowSearchIndexing (MangaPixer__Network__AllowSearchIndexing) false Whether search engines may index this server. While it is false, /robots.txt asks every crawler to stay away and every response carries an X-Robots-Tag: noindex, nofollow header, so your sign-in page does not show up in search results even when the server is reachable from the internet. Set true only if you really want it listed.

The server always trusts proxies on loopback and the private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16); the two keys above add to that list, they do not replace it. Only set them if your reverse proxy connects from some other address. See Reverse proxy and HTTPS.

Leave ASPNETCORE_URLS alone in Docker. The image's health check calls http://localhost:8080/health. To use a different port, change the host side of the port mapping instead (see Install with Docker). The server speaks plain HTTP only. For HTTPS, see Reverse proxy and HTTPS.

Storage

Key (environment variable) Default Meaning
MangaPixer:Storage:DataRoot (MangaPixer__Storage__DataRoot) /data in the image; otherwise a data folder next to the server binary Database (mangapixer.db), sign-in keys (keys/), logs (logs/), backups (backups/) and thumbnails (thumbnails/). Keep this safe.
MangaPixer:Storage:CacheRoot (MangaPixer__Storage__CacheRoot) /cache in the image; otherwise cache next to the binary Cached page images. Disposable: emptied on every start (each run writes into its own run-… folder and deletes the earlier ones in the background).
MangaPixer:Storage:ScratchRoot (MangaPixer__Storage__ScratchRoot) /scratch in the image; otherwise scratch next to the binary Temporary work folders for opening archives and for the YACReader import. Disposable.
MangaPixer:Storage:MediaRoot (MangaPixer__Storage__MediaRoot) /media The only folder tree the admin Browse… picker can show when you register a library. It does not restrict what you can type into Root Path by hand.
MangaPixer:Storage:CacheBudgetBytes (MangaPixer__Storage__CacheBudgetBytes) 1073741824 (1 GiB) Maximum size of the page cache, in bytes. The least recently used pages are evicted after a write pushes the cache over budget, and a full pass also runs once a day. The cache starts empty on every start, so the budget covers everything in the folder. Admins can also set it on the Performance card (below); a value set here wins and the card shows it as set by the server configuration.
MangaPixer:Storage:ScratchBudgetBytes (MangaPixer__Storage__ScratchBudgetBytes) 1073741824 (1 GiB) Size limit for temporary work folders, in bytes. Pages are written here briefly while they are extracted, and the YACReader import unpacks its upload here.

Budgets are plain byte counts: 268435456 is 256 MiB, 4294967296 is 4 GiB. Relative paths are resolved against the server's working directory. You cannot register a library whose folder is inside a storage root or contains one.

The Unraid Compose file sets the three roots to /config/data, /config/cache and /config/scratch.

Media processing

Key (environment variable) Default Meaning
MangaPixer:Media:MaxConcurrentJobs (MangaPixer__Media__MaxConcurrentJobs) a quarter of the processors, at least 2 and at most 4 How many helper processes prepare pages, thumbnails and covers and analyze archives at once. Pages someone is reading are always served first. Use 1 on a low-memory NAS. Admins can also set it (1-8) on the Performance card (below); a value set here wins. Before version 1.42.0 the default was always 2.
MangaPixer:Media:BackgroundWhileReading (MangaPixer__Media__BackgroundWhileReading) slow What background work (analyzing new archives, cover thumbnails, cover look-ups) may do while someone reads: pause (none until 30 seconds after the last page someone opened), slow (one helper process) or normal (every helper process but one). Also on the Performance card; a value set here wins.
MangaPixer:Media:WorkerIdleTimeoutSeconds (MangaPixer__Media__WorkerIdleTimeoutSeconds) 180 How many seconds a helper process that opens archives may sit unused before the server shuts it down. Each one holds roughly 100-200 MB of memory, so a quiet server gives that back. The next page or scan starts a fresh one, which adds about a fifth of a second to that first request. 0 keeps helpers running until the server stops, as before version 1.22.0.
MangaPixer:Media:MinWarmWorkers (MangaPixer__Media__MinWarmWorkers) 0 How many helper processes stay running however long the server is idle. 0 lets a quiet server run with none. Set 1 if you prefer the first page after a quiet spell to open without the start-up delay and can spare the memory. It never goes above MaxConcurrentJobs.
MangaPixer:Warmup:Enabled (MangaPixer__Warmup__Enabled) true After a start or an update, once the server answers, it opens the library first pages, the home rows and one page on the already-running helper process in the background, so the first visitors do not wait for that preparation. It only reads, sends nothing anywhere and pauses whenever someone uses the server. false switches it off.
MangaPixer:Media:ThumbnailBackfill:BatchSize (MangaPixer__Media__ThumbnailBackfill__BatchSize) 200 How many items the background thumbnail pass loads at a time.
MangaPixer:Media:ThumbnailBackfill:BackoffMs (MangaPixer__Media__ThumbnailBackfill__BackoffMs) 200 How long, in milliseconds, the thumbnail pass waits between checks while the server is busy with readers or analysis.
MangaPixer:Media:PageVariants:MaxDimensions (MangaPixer__Media__PageVariants__MaxDimensions) 1080,1440,2160 Page sizes the reader may ask for, as longest edge in pixels, written smallest first and separated by commas. A request is rounded up to the next size on this list, so a few sizes cover every screen. Pages are never enlarged: a page already smaller than the requested size is sent as it is. At most six sizes; each extra size is another cached copy of every page you read.
MangaPixer:Media:PageVariants:WebpQuality (MangaPixer__Media__PageVariants__WebpQuality) 82 Image quality (1-100) for those resized pages. Higher looks better and costs more space and bandwidth.
MangaPixer:Media:PageVariants:DefaultFilter (MangaPixer__Media__PageVariants__DefaultFilter) balanced How pages are resized when the reader does not choose: sharp, balanced or soft. sharp keeps line art crispest but can make screentone dots shimmer on a high-resolution screen; soft smooths them away at the cost of some crispness; balanced sits in between. Readers can override this per request, so this only sets the starting point. An unrecognized value is not ignored: the server starts, but page requests fail with an error until you correct it.
Media:WorkerExecutablePath (Media__WorkerExecutablePath) Set in the image; otherwise found automatically Location of the helper process that opens archives. Leave it as it is. Note there is no MangaPixer prefix on this key.

Scanning

Key (environment variable) Default Meaning
MangaPixer:Scanning:Scheduler:Enabled (MangaPixer__Scanning__Scheduler__Enabled) true Turns automatic library scans on or off for the whole server. When off, libraries are only scanned when an admin starts a scan, and each library's Auto-scan setting is kept for when you turn it back on.
MangaPixer:Scanning:Scheduler:StartupDelaySeconds (MangaPixer__Scanning__Scheduler__StartupDelaySeconds) 180 Seconds after start-up before the first check for due libraries, so a restart does not start scans straight away.
MangaPixer:Scanning:Scheduler:TickSeconds (MangaPixer__Scanning__Scheduler__TickSeconds) 60 Seconds between checks for due libraries.

How often each library is scanned is set per library in MangaPixer Administration > Scheduled jobs (Auto-scan: Off, Hourly, Every 6 hours, Daily or Weekly; daily by default). A value that cannot be read is ignored and the default is used. See Automatic scans.

Backups

Key (environment variable) Default Meaning
MangaPixer:Backups:Enabled (MangaPixer__Backups__Enabled) true Turns the scheduled database backups on or off. Back up now keeps working either way.
MangaPixer:Backups:IntervalHours (MangaPixer__Backups__IntervalHours) 24 Hours between scheduled backups. Decimals are allowed (0.5 = 30 minutes). The first backup runs 2 minutes after the server starts.
MangaPixer:Backups:Hour (MangaPixer__Backups__Hour) not set (any time) 1.32.0. Hour of the day (0-23, server time) for backups whose interval is whole days (24, 48, ... hours): they then run at that hour every 1, 2, ... days. Ignored for shorter intervals. When set, the hour cannot be changed in Scheduled jobs.
MangaPixer:Backups:RetentionCount (MangaPixer__Backups__RetentionCount) 7 How many rotating snapshots (rotating-*.db.gz and older rotating-*.db) to keep. Older ones are deleted. Pre-migration and pre-restore snapshots are kept separately (the newest 3 of each).
MangaPixer:Backups:Location (MangaPixer__Backups__Location) not set (<DataRoot>/backups) Absolute folder for the rotating backups, for example /backups next to a bind mount. It must pass the same checks as a folder chosen in the web app. If it fails them, backups stop (they never fall back to the data folder) and /health/ready reports Degraded.
MangaPixer:Backups:AllowLocationChange (MangaPixer__Backups__AllowLocationChange) true false locks the backup location in the web app, even when no Location is set.
MangaPixer:Backups:Compress (MangaPixer__Backups__Compress) true 1.49.0. New rotating backups are gzip-compressed (.db.gz). false writes plain .db files as before. Backups of either kind are listed, kept and restorable together. 1.50.0: the same switch is Compress new backups in the Backup settings card; set here, it is shown there as Managed by server configuration.
MangaPixer:Backups:MaxRestoreUploadBytes (MangaPixer__Backups__MaxRestoreUploadBytes) 536870912 (512 MiB) Largest backup you can restore, counted in the database's own size: for a compressed .db.gz the limit applies to the unpacked bytes (at most 1 GiB, the server's limit for the whole upload request).

The schedule, retention, compression and location can also be changed in the Backup settings card in the web app. Each setting is resolved on its own: a value in this configuration wins (the web app shows it as Managed by server configuration), then the value saved in the web app, then the default. A value that cannot be read (for example IntervalHours: daily) is ignored with a warning in the log. Pre-migration and pre-restore snapshots always stay in <DataRoot>/backups. See Backup and restore.

Sign-in protection

Key (environment variable) Default Meaning
MangaPixer:Security:RateLimit:MaxAttemptsPerIp (MangaPixer__Security__RateLimit__MaxAttemptsPerIp) 10 Failed sign-ins allowed from one IP address per window.
MangaPixer:Security:RateLimit:MaxAttemptsPerUser (MangaPixer__Security__RateLimit__MaxAttemptsPerUser) 5 Failed sign-ins allowed for one username per window.
MangaPixer:Security:RateLimit:Window (MangaPixer__Security__RateLimit__Window) 00:05:00 Length of the counting window, as hh:mm:ss.
MangaPixer:Security:RateLimit:Disabled (MangaPixer__Security__RateLimit__Disabled) false Turns the limiter off. Only for testing.
MangaPixer:Security:ApiTokens:RequestsPerMinute (MangaPixer__Security__ApiTokens__RequestsPerMinute) 600 Requests a minute one API token may make to the export; above it the answer is 429 with Retry-After. 0 = no ceiling.
MangaPixer:Security:ApiTokens:FailedAttemptsPerIp (MangaPixer__Security__ApiTokens__FailedAttemptsPerIp) 20 Requests with a wrong token from one address within 5 minutes before that address's token requests are refused for the rest of the 5 minutes.
MangaPixer:Security:ApiTokens:ScanCooldownMinutes (MangaPixer__Security__ApiTokens__ScanCooldownMinutes) 5 1.36.0. Minutes between two scans of the same library requested by API tokens; a request inside that time gets 429 with Retry-After. Scans started in Administration or by the schedule do not count. 0 = no wait. See API tokens.

The counters are held in memory and reset when the server restarts. Separately, an account locks for 15 minutes after 5 wrong passwords; that is not configurable. Behind a reverse proxy the limit counts each client's real address, as long as the proxy is trusted and sends X-Forwarded-For (see Reverse proxy and HTTPS).

Logging

The log level is not set in configuration. It is controlled at runtime by an admin and goes back to Information every time the server restarts. The Logging:LogLevel entries in appsettings.json do not change the server's log output.

  • In the web UI: the Debug Logging card in MangaPixer Administration. Global level accepts Verbose, Debug, Information, Warning, Error or Fatal. Below it you can raise the level for a single area (Scanning, Media or Reading) without flooding the log with everything else; Inherited from Global makes an area follow the global level again. Changes apply immediately.
  • With the API (admin only): GET /api/v1/operations/logging returns the current levels and PUT /api/v1/operations/logging changes them. For a single area:
{ "categories": [ { "name": "Scanning", "level": "Debug" } ] }

Send an empty level for a category to make it follow the global level again. Calling the API needs a signed-in admin session and the CSRF header; see Backup and restore for a script that does both.

Framework noise (Microsoft.AspNetCore, Microsoft.EntityFrameworkCore) stays at Warning regardless of the level you pick.

Logs go to the container output and to files in <DataRoot>/logs (mangapixer-<date>.log, one file per day, a new file after 20 MB, 7 files kept). See Troubleshooting for what the logs contain and deliberately leave out.

Settings stored in the app

A few server-wide settings are changed by an admin in MangaPixer Administration rather than in configuration, and are saved in the database:

  • Backup settings: schedule, retention and location (configuration values above take precedence).
  • Update Checker: off by default. When an admin ticks Check for updates, the server asks the GitHub Releases API for MangaPixer's latest release at most once a day (or when you select Check now) and shows Update available or Up to date in the admin page. The request carries no instance identifier, user data, paths or telemetry; apart from web series information (below), it is the only call MangaPixer makes to the internet, and only while this setting is on.
  • Metadata Manager (its own page, /admin/metadata, opened from the account menu, Settings tab): Show series information, Fetch from the web (off by default; turning it on needs the consent tick), Automatic matching (off by default, with its own consent tick), the Daily request budget (5000 by default) and the per-library switches. See Series information. Metadata__NetworkDisabled=true (config key Metadata:NetworkDisabled) turns web lookups off regardless of the admin setting, for operators who want certainty; the Metadata Manager page then says so.
  • Trackers (new in 1.43.0, Administration > Trackers): allow MyAnimeList or MangaUpdates sync for the server, after its consent text. Trackers__NetworkDisabled=true (config key Trackers:NetworkDisabled) turns tracker sync off regardless of the admin setting. See Tracker setup.
  • Library icons and reading directions, set per library on the Libraries card, and automatic scan schedules, set per library in Scheduled jobs.
  • Performance (1.42.0): media workers, page cache size and background work while someone reads - see Performance.
  • Volume contents (1.44.0): find the chapters inside volume files - see Volume contents.
  • Scheduled jobs (1.32.0): the hours of the daily jobs (series information refresh, backups, trash, cache clean-up), each library's scan time and how often series information is refreshed. See Scheduled jobs.

Performance

1.42.0. The Performance card in MangaPixer Administration sets three things. Every change applies at once, without a restart. For each one the order is: the server configuration (the keys above) first, then the card, then the built-in default. A value set in the configuration is shown on the card as Set by the server configuration and cannot be changed there; choosing the (default) option on the card clears the stored value, so the setting follows the default again.

Setting Default Range Configuration key
Media workers - helper processes that prepare pages and covers and analyze archives at once a quarter of the processors, 2-4 1-8 MangaPixer:Media:MaxConcurrentJobs
Page cache size - prepared pages kept for quick re-reading 1 GB 256 MB - 64 GB MangaPixer:Storage:CacheBudgetBytes
Background work while someone reads Slow Pause / Slow / Normal MangaPixer:Media:BackgroundWhileReading
  • Who goes first. When every helper process is busy, a page someone is looking at goes first, then the pages the reader is loading ahead and the reader's page strip, then background work. The reader loads at most two pages ahead at a time, and only once the page on screen is there.
  • Someone reads means a page was opened in the last 30 seconds. While nobody reads, background work may use every helper process. With Slow, background work that has waited 10 seconds goes before pages loaded ahead, so it never stops completely.
  • More workers open pages faster when several people read and finish a library scan sooner, but each helper process takes some memory (about 150-250 MB while busy) and the processor time of the others on the same machine.
  • A smaller cache frees its space at once (the least recently read pages go first). The cache always starts empty after a restart.

Volume contents

1.44.0. The Volume contents card in MangaPixer Administration, next to Performance, has one switch: Find the chapters inside volume files (on by default). While it is on, MangaPixer reads volume files that no volume list maps and the chapter files next to them, in the background, to tell which chapters a volume file holds (see Volumes view). The card shows how many volume files were checked and in how many chapters were found. The work runs one request at a time on the background helper processes, so Background work while someone reads applies to it. Files are only read; nothing leaves the server.

Configuration key Default Effect
MangaPixer:VolumeScan:Enabled (MangaPixer__VolumeScan__Enabled) true false switches the scan off whatever the card says (the card then shows it as switched off by the server configuration).

Scheduled jobs lists it as Volume contents: hourly and after library scans, while it is switched on.

Fixed behavior

These are built in and have no setting:

  • Sign-in sessions last 7 days from your last activity.
  • Passwords need at least 8 characters, including a lowercase letter.
  • Expired sessions are cleaned up every hour. The cache-size pass runs daily, at the hour chosen in Scheduled jobs (05:00 server time by default).
  • Automatic scans run one library at a time and never alongside another scan.
  • Archive-processing time limits (for example 120 seconds to open an archive on a drive that is spinning up).