ComicOPDS/docs/configuration.md

🔧 Configuration

Environment Variables

Note: Environment variable values should be specified without quotes. For example, use SERVER_BASE=http://example.com not SERVER_BASE="http://example.com". The application will automatically strip surrounding quotes if present.

Variable	Default	Required	Description
CONTENT_BASE_DIR	/library	Required	Path inside the container where your comics are stored (mounted volume).
SERVER_BASE	(none)	Required	Public base URL (e.g. http://10.0.0.1:8382 or https://comics.example.com). Used in generated OPDS links.
URL_PREFIX	""	Optional	Path prefix when serving behind a reverse proxy (e.g. /comics). Leave empty if served at root or subdomain.
PAGE_SIZE	50	Optional	Number of entries per page in OPDS feeds. Increase/decrease depending on client performance.
DISABLE_AUTH	false	Optional	If true, disables authentication completely (public access).
OPDS_BASIC_USER	admin	Optional	Username for HTTP Basic Auth. Ignored if DISABLE_AUTH=true.
OPDS_BASIC_PASS	change-me	Optional	Password for HTTP Basic Auth. Ignored if DISABLE_AUTH=true.
ENABLE_WATCH	false	Optional	Watch filesystem for changes and update index incrementally. When enabled, new/modified/deleted comic files are automatically indexed without requiring a full rescan. Useful for large libraries. (true/false).
AUTO_INDEX_ON_START	false	Optional	If true, reindexes library on every container start. Recommended false for large libraries.
PRECACHE_THUMBS	false	Optional	If true, enables thumbnail generation when reindexing or via dashboard.
PRECACHE_ON_START	false	Optional	If true, automatically triggers full thumbnail pre-cache at container start. Recommended false for large libraries.
THUMB_WORKERS	3	Optional	Number of parallel workers for thumbnail generation. Tune for your CPU/IO capacity.
PAGE_CACHE_TTL_DAYS	14	Optional	Delete page caches that have been idle for more than this many days.
PAGE_CACHE_MAX_BYTES	10737418240	Optional	Maximum total size of page cache (10 GiB default).
PAGE_CACHE_AUTOCLEAN	true	Optional	Enable automatic background cleanup of page caches.
PAGE_CACHE_CLEAN_INTERVAL_MIN	360	Optional	Run page cache cleanup every N minutes (360 = 6 hours).

📚 Recommended Settings for Large Libraries (30k–100k+ comics)

For very large collections, some defaults should be adjusted to avoid long startup times and high resource usage:

Indexing Settings

• AUTO_INDEX_ON_START=false → prevents reindexing every time the container starts
• Use the Reindex button on the dashboard when needed instead

Thumbnail Settings

• PRECACHE_ON_START=false → don't pre-cache on every boot
• Run pre-cache manually via the dashboard button after a big import
• THUMB_WORKERS=4–6 → if you have enough CPU/IO, increase worker count for faster thumbnail generation

Performance Settings

• Keep PAGE_SIZE=50 unless your client struggles with large feeds
• Some OPDS readers work better with smaller pages (e.g. 25)

Security Settings

• For private servers behind a VPN, you can disable auth: DISABLE_AUTH=true
• Otherwise, keep Basic Auth enabled (OPDS_BASIC_USER / OPDS_BASIC_PASS)

These settings ensure the container starts faster, avoids unnecessary reprocessing, and lets you control when heavy tasks (indexing, thumbnailing) happen.

💡 Common Configuration Scenarios

Here are some typical use cases and their recommended settings:

Scenario 1: Generate Thumbnails at Startup (Without Reindexing)

Use case: You want to pre-cache thumbnails when the container starts, but don't need to reindex the library.

AUTO_INDEX_ON_START: "false"    # Don't reindex on startup
PRECACHE_ON_START: "true"       # Run thumbnail pre-cache at startup
PRECACHE_THUMBS: "false"        # Not relevant (no reindex happening)

This is useful when you've already indexed your library and just want to ensure thumbnails are ready.

Scenario 2: Reindex + Generate Thumbnails During Scan

Use case: You want to reindex the library and generate thumbnails as part of the scan process.

AUTO_INDEX_ON_START: "true"     # Reindex library on startup
PRECACHE_THUMBS: "true"         # Generate thumbnails during reindex
PRECACHE_ON_START: "false"      # Don't run separate thumbnail job

This is the most common setup for initial library setup or when you want everything fresh on each restart.

Scenario 3: Reindex First, Then Generate Thumbnails Separately

Use case: You want to reindex quickly without thumbnails, then run a separate thumbnail generation job.

AUTO_INDEX_ON_START: "true"     # Reindex library on startup
PRECACHE_THUMBS: "false"        # Skip thumbnails during reindex (faster)
PRECACHE_ON_START: "true"       # Run separate thumbnail job after

This is useful for very large libraries where you want the index ready quickly, and can let thumbnails generate in the background afterward.

Scenario 4: Manual Control (Recommended for Large Libraries)

Use case: You have a large library and want to control indexing and thumbnails manually via the dashboard.

AUTO_INDEX_ON_START: "false"    # Don't reindex on startup
PRECACHE_ON_START: "false"      # Don't pre-cache on startup
PRECACHE_THUMBS: "true"         # Generate thumbs when manual reindex is triggered
ENABLE_WATCH: "true"            # Auto-update index on file changes

This gives you the fastest startup time and lets you trigger heavy operations only when needed via the dashboard buttons.

SSD Optimization

For optimal performance, certain /data subdirectories benefit significantly from being stored on SSD:

Recommended for SSD

• /data/thumbs - Thumbnail cache (frequently accessed during browsing)
• /data/pages - Page cache for streaming (frequently accessed during reading)
• /data/library.db - SQLite database (all queries access this)

Can Stay on HDD

• /data/smartlist.json - Smart list configuration (small, rarely accessed)

Docker Volume Mapping Example

To split storage between SSD and HDD:

volumes:
  - /path/to/hdd/comicopds:/data                    # Main config on HDD
  - /path/to/ssd/comicopds/thumbs:/data/thumbs      # Thumbnails on SSD
  - /path/to/ssd/comicopds/pages:/data/pages        # Page cache on SSD
  - /path/to/ssd/comicopds/library.db:/data/library.db  # Database on SSD
  - /path/to/your/comics:/library:ro                # Comic library (read-only)

This setup keeps configuration files on regular storage while placing performance-critical caches and the database on faster SSD storage.