Initial commit

docs/configuration.md

@@ -0,0 +1,79 @@
+# Configuration
+
+Configuration is layered in this order:
+
+1. `backend/default-config/app.toml`
+2. `config/app.toml`
+3. `.env` variables passed into Docker Compose
+
+The backend deep-merges TOML files and then applies environment overrides for common deployment values.
+
+## Organizer Settings
+
+`[app]`
+
+- `dry_run`: plan without moving files.
+- `scan_interval_seconds`: worker polling interval.
+- `settle_seconds`: minimum file age before processing.
+- `stable_checks`: number of matching size/mtime observations required before a file is considered stable.
+- `incomplete_suffixes`: suffixes ignored while downloads are still active.
+- `media_extensions`: media files eligible for organizing.
+- `subtitle_extensions`: subtitle files visible to the scanner.
+- `extra_keywords`: filename terms ignored by the organizer, such as samples and trailers.
+- `library_scan_max_files`: maximum files indexed by the manual library scan.
+- `library_scan_timeout_seconds`: timeout for the manual library scan.
+- `cache_max_bytes`: maximum server-side cache size. Defaults to 20GB.
+
+`[library]`
+
+- `movie_folder`: destination folder template for movies.
+- `series_folder`: destination folder template for shows.
+- `movie_file`: Jellyfin-friendly movie filename template.
+- `episode_file`: Jellyfin-friendly episode filename template.
+- `collision`: `keep-both`, `skip`, or `replace`.
+- `duplicate`: reserved duplicate policy hook.
+- `permissions_mode`: final file mode after a move.
+- `directory_mode`: directory mode applied to created destination folders.
+
+## Drives
+
+Each `[[drives]]` entry has:
+
+- `id`: stable machine name.
+- `name`: dashboard display name.
+- `path`: mounted drive path inside the container.
+- `min_free_gb`: minimum free space required before the drive is eligible.
+
+Drive selection first checks whether the title already has a home under `Movies` or `Shows`. If not, it selects the eligible drive with the most free space.
+
+## Themes
+
+Bundled presets live in `web/src/themes.css`. The current presets are:
+
+`slate`, `midnight`, `graphite`, `nord`, `dracula`, `solar`, `forest`, `marine`, `ember`, `paper`.
+
+Runtime custom CSS is loaded from `/config/custom-theme.css` when `[theme].allow_custom_css` is enabled. Override any token:
+
+```css
+:root {
+  --accent: #5cc8ff;
+  --radius: 4px;
+}
+```
+
+## Release Providers
+
+`[[release_providers]]` supports pluggable free sources:
+
+- `type = "rss"` for RSS/Atom-style feeds.
+- `type = "json"` for simple public JSON endpoints.
+
+Provider code is isolated in `backend/sortarr/releases.py` so new adapters can be added without touching the UI.
+
+## TMDb Metadata
+
+Set `TMDB_API_KEY` or `TMDB_BEARER_TOKEN` in `.env` to enrich manual library scans with TMDb posters, overviews, release dates, and TV season episode data. Without credentials, Sortarr still groups local media and shows placeholder covers.
+
+## Server Cache
+
+Sortarr stores reusable TMDb and ffprobe results under `/data/cache`. The default cache cap is 20GB via `[app].cache_max_bytes`; older cache files are pruned when new cache entries are written.