Skip to content

Role Refactor

The role-refactor branch merge includes the following updates:

  • Refactors application role variables as follows (breaking):

    • Override scope is now clearly differentiated using the following naming conventions:

      • Variables that previously applied to all instances of a role (e.g. sonarr_docker_image) now only apply to the instance with the exact name (e.g. sonarr)

      • Role-scoped overrides must now include the _role_ infix (e.g. sonarr_role_docker_image) to persist as such

    • Some _default + _custom variable pairs assigned an empty value by default were replaced with a single unsuffixed variable

  • Sandbox: settings.yml removed (breaking)

    • Settings no longer apply and must be migrated to their Inventory equivalent to persist

  • Removes roles:

    jaeger

    readarr

    rutorrent

    sub_zero

    webtools

    alternatrr

    aria2_ng

    booksonic

    comicstreamer

    docspell

    goplaxt

    maybe_finance

    rdtclient

    solr

    teamspeak

    watchtower

  • Replaces Python tools with Go rewrites: DNS manager, Docker controller

  • Tandoor Recipes: updated to use a dedicated database container (breaking):

Full changes:

Inventory Migration Guide

The following sections must be followed sequentially.

Single-instance overrides

When a role only has a single instance, either variable name pattern will achieve the same outcome. However, to align with the new convention, it is recommended to switch to the _role_ infix.

Example 
plex_dns_proxy: false

Becomes:

plex_role_dns_proxy: false

Multi-instance overrides

Multi-instance role variables must be changed to the appropriate override scope for existing configuration to persist.

Example

Specificity takes precedence

When choosing which variable to use, remember the precedence order: Instance > Role > Global

bazarr_instances: ["bazarr", "bazarr4k"]
bazarr_docker_volumes_custom: ["/opt/subcleaner:/subcleaner"] # (1)!
bazarr_themepark_theme: "nord" # (2)!
bazarr4k_themepark_theme: "maroon"

  1. Reminder: variables in this pattern were considered role-scoped prior to Role Refactor, since the prefix matches the role name.

  2. Reminder: variables in this pattern were considered role-scoped prior to Role Refactor, since the prefix matches the role name.

Becomes:

bazarr_instances: ["bazarr", "bazarr4k"]
bazarr_role_docker_volumes_custom: ["/opt/subcleaner:/subcleaner"] # (1)!
bazarr_role_themepark_theme: "nord" # or bazarr_themepark_theme: "nord" (2)
bazarr4k_themepark_theme: "maroon" # (3)!

  1. Typically, you want external processing tools to be available to all instances, so keep role-scoped.

  2. This can go both ways depending on your goal. Previously, this override was role-scoped, but with only two instances defined and the 4k instance individually overridden, the same outcome would be achieved.

    • bazarr_role_themepark_theme: "nord": additional instances added later would inherit the nord theme unless individually overridden
    • bazarr_themepark_theme: "nord": additional instances would inherit the global_themepark_theme value if enabled, or would not have theming applied.

  3. No change needed here, as variables in this pattern were already considered instance-scoped and remain so.

default / custom overrides

This section assumes you have already completed the override scope migration steps above

Variables affected by this change are typically moved to the Docker+ Role Defaults category.

  1. Check whether your override is affected by looking up the variable name in the app's documentation.

  2. If you find the corresponding variable unsuffixed, match it by removing _default/_custom from the variable name in your inventory.

  3. If you find the corresponding variable pair still exists and your override has _default, change it to _custom.

Example 
plex_docker_network_mode_default: "container:gluetun" # (1)!

firefox_role_docker_commands_custom:
  - "/usr/lib/firefox/firefox"
  - "--headless"

wireguard_role_docker_ports_default:
  - "1234:1234"
  1. Not to be confused with the similarly named list variable plex_docker_networks_default, which is still available as such (assuming an instance named plex).

Becomes:

plex_docker_network_mode: "container:gluetun"

firefox_role_docker_commands:
  - "/usr/lib/firefox/firefox"
  - "--headless"

wireguard_role_docker_ports_custom:
  - "1234:1234"

Sandbox App Settings Migration Guide

For convenience, Sandbox roles that previously read settings from /opt/sandbox/settings.yml were updated to expose those settings as scalar Inventory variables instead. If you encounter a role missing this update, please report it on Discord or open an issue in the Sandbox repository.

As always, check how the settings you use are represented in the role by looking up the variables in the app's documentation under Role Defaults and transfer the values accordingly.

Example
sandbox/settings.yml
your_spotify:
  public_key: "3e3ce6e568f6e9a8894c835b34f1701a"
  secret_key: "0593b2fec4867575d741e93a6cff3580"

Becomes:

Inventory
your_spotify_role_public_key: "3e3ce6e568f6e9a8894c835b34f1701a"
your_spotify_role_secret_key: "0593b2fec4867575d741e93a6cff3580"