Skip to content

Configuration

chodeus edited this page Oct 22, 2026 · 23 revisions

🏠 Home › Configuration

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.

On this page

Top-level blocks

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.

general

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.

auth

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.

tmdb

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).

fanart

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).

instances

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:7878 works on a shared Docker network).

schedule

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.

schedule_blocks

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.

notifications

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

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.

Secret handling

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.

If CHUB won't start

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.

Appendix: full example + legacy migration

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.


Next: Modules · Related: First Run, Webhooks

Clone this wiki locally