Repository navigation
Configuration
🏠 Home › Configuration
CHUB reads one YAML file, config.yml in ${CONFIG_DIR} (/config/config.yml in Docker). This page covers the top-level blocks; module fields are on Modules.
The Settings pages write it for you and validate every save. If you edit it by hand, keep it at 0600 (it holds API keys): CHUB validates the whole file on startup and refuses to start on a bad field, naming it in the log.
- Top-level blocks
- general
- auth
- tmdb
- fanart
- instances
- schedule
- notifications
- user_interface
- Secret handling
- If CHUB won't start
- Appendix: full example + legacy migration
Anything you omit falls back to safe defaults.
| Block | What it holds |
|---|---|
general |
Global toggles: logging, backups, disabled modules, webhook tuning, Plex cache TTL, dashboard layout, first-run gate. |
auth |
The login (managed by the UI). |
tmdb |
TMDB API key for ID resolution (better poster matching + request links). |
fanart |
fanart.tv key for the fanart logo/background source. |
instances |
Radarr / Sonarr / Lidarr / Plex connections → see First Run. |
schedule |
When each module runs. |
schedule_blocks |
Extra schedules per module, each with its own settings overrides. |
notifications |
Discord / Notifiarr destinations. |
user_interface |
Server-wide default theme. |
| one block per module |
poster_renamerr, border_replacerr, nohl, … → see Modules. |
Global toggles. Most are on Settings → General; the page column says where the rest live.
| Field | Default | Page | Purpose |
|---|---|---|---|
log_level |
info |
General, System |
debug | info | warning | error | critical. |
max_logs |
9 |
General | Rotated log files kept (1–100). |
log_retention_days |
0 |
System | Delete rotated logs older than this many days (0–365; 0 = keep by count only). |
auto_backup |
false |
System | Write a config + database backup once a day. |
auto_backup_keep |
12 |
System | Automatic backups kept (1–100). |
backup_dir |
"" |
System | Where backups go; empty = ${CONFIG_DIR}/backups (the same volume as the data — prefer another). |
disabled_modules |
[] |
Modules | Modules switched off: skipped by the scheduler and blocked from manual and webhook runs. |
update_notifications |
false |
— | Deprecated; no longer wired at runtime. |
webhook_initial_delay |
30 |
General | Seconds to wait after an inbound webhook before acting (0–3600). |
webhook_retry_delay |
30 |
General | Seconds between Plex-availability retries (1–3600). |
webhook_max_retries |
10 |
General | Max retries (0–100). |
webhook_secret |
"" |
General | Shared secret for inbound webhooks — see Webhooks. |
trusted_proxies |
["private"] |
General | Proxies whose X-Forwarded-For CHUB trusts when matching a webhook to its instance. IPs or CIDRs; private = any LAN / loopback / Docker address; empty = never. |
public_url |
"" |
General | CHUB's address as the *arrs reach it, written into each *arr by webhook auto-setup. Empty = a URL found in an existing CHUB webhook in your *arrs, else the browser address. |
plex_cache_ttl_seconds |
300 |
— | Reuse the Plex snapshot for this long across runs (0–86400; 0 = always refresh). |
dashboard_modules |
[] |
General | Which module rows show, in order; empty = all. |
dashboard_refresh_seconds |
30 |
General | Dashboard poll/countdown interval when live updates aren't connected (0–3600; 0 = off). |
dashboard_upcoming_limit |
5 |
General | Upcoming runs listed in the Up next panel (1–50). |
duplicate_exclude_groups |
[] |
General |
Quality Instance Groups: lists of instances that hold the same media on purpose (for example radarr and radarr4k). Items shared within a group are not flagged as duplicates. |
setup_completed |
false |
— | First-run wizard gate; set true once the wizard finishes (backfilled true for existing installs). |
The webhook_* fields are covered in full on Webhooks.
Managed by the UI. The login is optional: with no username / password_hash, CHUB asks for none. Choose in the setup wizard or later in Settings → General → Access (turning it off needs the current password).
| Field | Default | Purpose |
|---|---|---|
username |
"" |
Login name. |
password_hash |
"" |
Bcrypt hash (set by the UI). |
jwt_secret |
"" |
Random secret signing session tokens. Cleared when the login is turned off, which ends every session. |
token_expiry_hours |
24 |
Session lifetime. |
Gotcha: with no login, anyone who can reach CHUB can change its settings, including your instance API keys. Only turn it off when CHUB isn't reachable from outside your network.
Lost the password? See Troubleshooting → Reset the admin password.
With an apikey, CHUB looks up missing TMDB ids (from TVDB/IMDb ids) for better poster matching, Plex matching, and request links. On Settings → General → TMDB.
| Field | Default | Purpose |
|---|---|---|
apikey |
"" |
TMDB API key. |
cache_expiration |
60 |
Days to cache resolved IDs (1–3650). |
The logo and background source for asset_renamerr. Needs a free personal key from fanart.tv/get-an-api-key; without one, asset runs use local files only. On Settings → General → fanart.tv.
| Field | Default | Purpose |
|---|---|---|
client_key |
"" |
Personal fanart.tv API key. |
cache_expiration |
2 |
Days to cache resolved logo/background URLs (1–3650). |
Your Radarr, Sonarr, Lidarr, and Plex connections. The key under each service (radarr_main, sonarr_4k, …) is the name you reference elsewhere in config.yml.
instances:
radarr:
radarr_main:
url: http://radarr:7878
api: <api_key>
enabled: true
webhook_force_reupload: false # bypass dedup, re-push to Plex on webhook
plex:
plex_main:
url: http://plex:32400
api: <x_plex_token> # X-Plex-Token, not a login
enabled_libraries: [Movies, TV Shows] # Plex libraries CHUB may use
sync_schedule: "cron(0 4 * * *)" # background media-cache sync; "" = off
| Field | Default | Purpose |
|---|---|---|
url |
"" |
Service base URL CHUB can reach. |
api |
"" |
API key — for Plex, the X-Plex-Token. |
enabled |
true |
Whether CHUB uses this instance. |
webhook_force_reupload |
false |
On radarr/sonarr/lidarr only: webhook uploads bypass the unchanged-file dedup and re-push to Plex. |
enabled_libraries |
unset | Plex only: the libraries CHUB syncs, counts and shows. Unset = every library the server has at the first sync, then saved as that list, so a library added to Plex later stays hidden until you tick it. [] = none. plex_maintenance and poster_cleanarr ignore this and work on the whole server. |
sync_schedule |
cron(0 4 * * *) |
How often CHUB refreshes its media cache from every instance — a safety net behind webhooks. The Instances page offers Off, Every 6 hours, Daily and Weekly. |
Connecting and testing instances: First Run. Each card on Settings → Instances has Test, Sync, Edit, Delete and an enable switch; a Plex card expands to its libraries.
Gotcha: CHUB refuses cloud-metadata and unroutable addresses. Use an IP or hostname the container can resolve (
http://radarr:7878works on a shared Docker network).
One schedule string per module; a module not listed only runs by hand or by webhook. Settings → Schedule writes this for you.
schedule:
poster_renamerr: "cron(0 */4 * * *)" # every 4 hours
jduparr: "daily(03:00|15:00)" # 03:00 and 15:00
upgradinatorr: "hourly(15)" # at :15 every hour
nohl: "weekly(sun@04:00)" # Sundays at 04:00
plex_maintenance: "monthly(1@05:00)" # the 1st at 05:00
Times are 24-hour HH:MM in the container's time zone (TZ).
| Form | Example | Runs |
|---|---|---|
hourly(MM) |
hourly(30) |
Every hour at minute MM. |
daily(HH:MM|HH:MM…) |
daily(09:00|21:00) |
At each listed time. |
weekly(day@HH:MM|…) |
weekly(mon@09:00|fri@18:00) or weekly(mon,fri@09:00)
|
On those weekdays (mon…sun). |
monthly(D@HH:MM|…) |
monthly(1@09:00|15@09:00) or monthly(1,15@09:00)
|
On those days of the month. |
cron(expr) |
cron(0 9 * * 1-5) |
Standard five-field cron. |
Holiday windows in border_replacerr use range(MM/DD-MM/DD) instead. A save with a schedule that could never run is refused, naming the field. A system health probe runs every 6 hours on its own.
Extra schedules for a module, each applying its overrides to that run only — for example poster_cleanarr reporting daily and removing weekly. Set them up on Settings → Schedule.
schedule_blocks:
poster_cleanarr:
- label: Weekly clean
enabled: true
schedule: "weekly(sun@03:00)"
overrides:
mode: remove
Upgradinatorr profiles can also carry their own schedule — see Modules → upgradinatorr.
A list of destinations: one Discord webhook or Notifiarr Passthrough each, with the modules it covers and the events it sends. Settings → Notifications writes this for you.
notifications:
destinations:
- id: d1
method: discord # discord | notifiarr
name: Run summaries
enabled: true
events: { success: true, failure: false }
modules: [poster_renamerr, upgradinatorr]
config:
webhook: https://discord.com/api/webhooks/...
bot_name: CHUB
color: "#5865F2"
- id: n2
method: notifiarr
name: Errors
events: { success: false, failure: true }
modules: [__ALL__] # every module
config:
webhook: https://notifiarr.com/api/v1/notification/passthrough/<API_KEY>
channel_id: 1234567890
| Field | Purpose |
|---|---|
method |
discord or notifiarr. |
name |
Display name on the Notifications page. |
enabled |
Pause a destination without deleting it. |
events.success |
Send each covered module's run summary (On success on the page). |
events.failure |
Send error alerts — any ERROR-level log line from a covered module (On failure). |
modules |
Module keys this destination covers; __ALL__ = every module. |
config.webhook |
Discord channel webhook URL, or Notifiarr Passthrough URL. |
config.bot_name |
Discord only: overrides the webhook's default username. |
config.color |
Hex embed color. Error notifications are always red. |
config.channel_id |
Notifiarr only: Discord channel ID for Notifiarr to post to. |
Test on a destination sends a real notification. Summaries list at most 50 items, plus a total.
An older config with a discord: / notifiarr: block per module (and a main: error channel) is converted on load; a webhook shared by several modules becomes one destination.
user_interface:
theme: dark # auto | dark | light (auto follows the system setting)
The server-wide default (Settings → General → Appearance). Each browser remembers its own choice.
Config sent to the UI has these fields replaced with ********, matched by exact key name:
api, api_key, apikey, client_key, access_token, refresh_token, client_secret, token, password_hash, jwt_secret, webhook_secret, and outbound notification webhook URLs.
So webhook_force_reupload and webhook_*_delay are not hidden. A field saved back as ******** keeps its stored value, so editing other fields never wipes a secret. The eye button on a secret field shows the saved value; password_hash and jwt_secret are never shown.
docker compose logs chub names the field that failed. Fix it, or remove the section (it falls back to defaults), and restart. More in Troubleshooting.
Full example config.yml
Every top-level block, with a minimal setup for each module. Module fields: Modules.
general:
log_level: info
max_logs: 9
webhook_initial_delay: 30
webhook_retry_delay: 30
webhook_max_retries: 10
webhook_secret: ""
plex_cache_ttl_seconds: 300
duplicate_exclude_groups: []
tmdb:
apikey: ""
cache_expiration: 60
fanart:
client_key: ""
cache_expiration: 2
instances:
radarr:
radarr_main:
url: http://radarr:7878
api: <radarr-api-key>
enabled: true
sonarr:
sonarr_main:
url: http://sonarr:8989
api: <sonarr-api-key>
enabled: true
lidarr:
lidarr_main:
url: http://lidarr:8686
api: <lidarr-api-key>
enabled: true
plex:
plex_main:
url: http://plex:32400
api: <x-plex-token>
enabled: true
enabled_libraries: [Movies, TV Shows]
sync_schedule: "cron(0 4 * * *)"
schedule:
poster_renamerr: "cron(0 */4 * * *)" # every 4 hours
jduparr: "daily(03:00|15:00)" # twice a day
upgradinatorr: "daily(03:15)" # daily at 03:15
notifications:
destinations:
- id: d1
method: discord
name: Errors
events: { success: false, failure: true }
modules: [__ALL__]
config:
webhook: https://discord.com/api/webhooks/...
- id: n2
method: notifiarr
name: Health checks
events: { success: true, failure: false }
modules: [health_checkarr]
config:
webhook: https://notifiarr.com/api/v1/notification/passthrough/<API_KEY>
channel_id: 1234567890
user_interface:
theme: dark # auto | dark | light
# --- Modules (minimal subset; see the Modules page for every field) ---
poster_renamerr:
dry_run: false
apply_method: kometa # kometa | plex
action_type: hardlink # copy | move | hardlink | symlink
asset_folders: true # must match your Kometa setting
source_dirs: [/posters/custom] # Sync GDrive drives are added automatically
destination_dir: /kometa # Kometa's asset_directory
instances: [radarr_main, sonarr_main]
plex_scope:
- instance: plex_main
library_names: ["Movies", "TV Shows"]
add_posters: true # only used when apply_method: plex
border_replacerr:
dry_run: false
border_width: 26 # 0–200; color-mode only
border_colors: ["#ff7300"]
holidays:
- name: 🎃 Halloween
schedule: "range(10/01-10/31)"
colors: ["#FF6600", "#000000"]
poster_cleanarr:
mode: report # bloat: report | move | remove | restore | clear | nothing
plex_path: /plex # Plex Media Server data folder (contains Metadata/)
instances: [plex_main] # Plex only
orphan_instances: [radarr_main, sonarr_main]
orphan_assets_enabled: false
orphan_assets_mode: report # report | move | remove
asset_dirs: [/kometa]
stale_duplicates_enabled: false
stale_duplicates_mode: report # report | move | remove
jduparr:
hash_database: /config/jduparr.db
source_dirs: [/media/movies, /media/tv]
nohl:
dry_run: true # resolve deletes files through the ARR — start dry
searches: 10
source_dirs:
- { path: /media/movies, mode: resolve } # scan | resolve
- { path: /media/tv, mode: resolve }
instances: [radarr_main, sonarr_main]
upgradinatorr:
instances_list:
- instance: radarr_main
count: 10
tag_name: checked
search_mode: upgrade
renameinatorr:
rename_folders: true
count: 100 # integer, or "" = all items
tag_name: renamed
instances: [radarr_main, sonarr_main]
health_checkarr:
dry_run: true # deletes ARR items — start dry
instances: [radarr_main, sonarr_main]
nestarr:
library_mappings:
- arr_instance: radarr_main
plex_instances:
- { instance: plex_main, library_names: [Movies] }
path_mapping:
- arr_path: /media/movies
local_path: /data/movies
sync_gdrive:
gdrive_sa_location: /config/gdrive-sa.json
gdrive_list:
- id: "<google-drive-folder-id>"
location: /posters/gdrive-pull
Auto-migration from DAPS / older config formats
A config.yml from DAPS or an older CHUB is converted on load. CHUB first saves the original as config.yml.legacy-<timestamp>.yml, then writes the converted file and logs each rule that fired. A current file is left alone. Only the config's shape changes — no database or match state carries over (see FAQ).
What gets migrated
| Kind | Example |
|---|---|
| Section moves |
main.log_level → general.log_level; main.theme → user_interface.theme; main.update_notifications → general; empty main: dropped |
| Section removals | Top-level discord: (notification destinations cover it) |
| Field renames |
unmatched_assets.ignore_root_folders → ignore_folders; renameinatorr.ignore_tag → ignore_tags; poster_cleanarr.source_dirs → asset_dirs; labelarr plex_instance → instance
|
| Field removals |
poster_renamerr.incremental_border_replacerr, unmatched_assets.source_dirs, poster_cleanarr.ignore_media (warnings logged) |
| Shape changes | Plex entries in poster_renamerr / asset_renamerr / unmatched_assets instances → plex_scope; poster_cleanarr.instances split into Plex (instances) and ARR (orphan_instances) |
| Type conversions |
poster_cleanarr.dry_run: bool → mode: str; border_replacerr.holidays: dict → list
|
| Notifications | Per-module discord: / notifiarr: blocks → notifications.destinations
|
Check paths afterwards — the converter can't know your mounts: sync_gdrive.gdrive_sa_location + gdrive_list[].location, poster_renamerr.source_dirs[] + destination_dir, border_replacerr.source_dirs[] + destination_dir, poster_cleanarr.asset_dirs[] + plex_path, plex_maintenance.plex_path, nohl.source_dirs[].path, jduparr.hash_database + source_dirs[].
Restore the original: stop CHUB, copy config.yml.legacy-<timestamp>.yml over config.yml, restart.