Skip to content

Inventory

Description / nameInput element
Name of the role
Instance suffix

The inventory system offers a centralized approach to customizing roles, allowing manipulation of variables without directly editing the roles themselves. This ensures persistent configurations while avoiding conflicts during git merge operations.

Overriding Variables

Enter your new values in:

/srv/git/saltbox/inventories/host_vars/localhost.yml

Quick Shell Access

sb edit inventory

Changes take effect after deploying the affected role(s) using the install command.

Finding Available Variables

Variables that can be used for customization within the Inventory are listed under Role Defaults at the end of role documentations.

Find a role by using search or browsing the indexes:

Data Types

Inventory syntax follows YAML specifications. You will encounter five data types in the defaults:

Data Type Token Syntax Template Saltbox Example
boolean true/false 
bool_key: true
 
use_cloudplow: false
integer 
int_key: 123
 
emby_role_config_cache_size: 2048
string "" 
str_key: "value"
 
global_themepark_theme: "overseerr"

list
[]		 
list_key:
  - item0
  - "item1"
 
gluetun_docker_networks_alias_custom:
  - "plex"
  - "plex2"

dictionary
{}		 
dict_key:
  STR_KEY: "value"
  BOOL_KEY: "false"
 
kometasw_docker_envs_custom:
  KOMETA_RUN_COLLECTIONS: "Star Wars"
  KOMETA_DELETE_LABELS: "true"

Override Levels

When a role supports multiple instances, you can apply a configuration across all instances or to a specified instance. This is achieved by shaping the variable name as follows:

Role-level (default)

sonarr_role_setting_enabled: false # (1)!
  1. Variable name unchanged (default when no instances are defined)

Applies to all instances of the role

Instance-level

sonarr4k_setting_enabled: true # (1)!
    • _role segment removed
    • instance name can be the role name (sonarr) or prefixed with it (sonarr4k)

Applies to the specified instance

When both forms of the variable are used in the Inventory, the instance-level value takes precedence.

Demo

Let's explore two example use cases for customizing roles using variables in the Saltbox Inventory.

Replacing a Default Value

A common use for overrides will be specifying the version of the Docker image to be used. Let's see how that's done by navigating to Sonarr: Role Defaults and in the Docker tab, scrolling down to:

sonarr_role_docker_image_tag 
# Type: string
sonarr_role_docker_image_tag: "release"

# Type: string
sonarr2_docker_image_tag: "release"

Given this default value, Saltbox will use ghcr.io/hotio/sonarr:release as the Sonarr Docker image.

Opting to switch to "nightly" versions across all Sonarr instances, we can add the following line to localhost.yml:

sonarr_role_docker_image_tag: "nightly"

This will cause Saltbox to use the ghcr.io/hotio/sonarr:nightly Docker image, overriding the default: release. When we update Saltbox, our tag change to nightly will remain in effect.

Adding an Item to a List

A common use for lists is to specify extra Docker mappings or flags. Let's examine how to give our code-server container access to more locations on the host. In the Docker section, we find:

code_server_role_docker_volumes_default 
# Type: list
code_server_role_docker_volumes_default:
  - "{{ lookup('role_var', '_paths_location', role='code_server') }}/project:/home/coder/project"
  - "{{ lookup('role_var', '_paths_location', role='code_server') }}/.config:/home/coder/.config"
  - "{{ lookup('role_var', '_paths_location', role='code_server') }}/.local:/home/coder/.local"
  - "{{ server_appdata_path }}:/host_opt"
code_server_role_docker_volumes_custom 
# Type: list
code_server_role_docker_volumes_custom: []

Note the list syntax. Since we want the container to preserve existing volumes, the _docker_volumes_default list should not be overridden. Instead, we use the _docker_volumes_custom list.

To expose additional host locations (in this case, /srv and our home directory), we can add custom volumes to the list using the following syntax in the Inventory:

code_server_role_docker_volumes_custom:
  - "/srv:/host_srv"
  - "/home:/host_home"

The container will then be created with the new volumes included, and the target locations will be accessible to code-server at /host_srv and /host_home.