Container Settings Reference
Global Container Settings
Section titled “Global Container Settings”These settings apply to all containers and are configured in inventory/group_vars/all/container_settings.yml
Container State
Section titled “Container State”hmsdocker_compose_container_state: presentControls whether containers should exist. Valid values: present, absent. Setting to absent will remove all containers.
Restart Policy
Section titled “Restart Policy”hmsdocker_container_restart_policy: unless-stoppedControls how containers behave when the Docker daemon or server restarts. Valid values:
unless-stopped(default) — Restarts automatically unless manually stoppedalways— Always restarts regardless of exit statuson-failure— Only restarts if the container exits with a non-zero exit code
Auto-Update Schedule
Section titled “Auto-Update Schedule”hmsdocker_container_auto_update_schedule: "0 0 9 * * *"The cron schedule (in UTC) for Watchtower to check for container image updates. The default checks daily at 9:00 AM UTC.
Remove Orphans
Section titled “Remove Orphans”hmsdocker_container_remove_orphans: yesWhen enabled, containers that are disabled in the container map will be automatically stopped and removed on the next playbook run.
Timezone
Section titled “Timezone”hmsdocker_container_timezone: America/New_YorkThe timezone passed to containers via the TZ environment variable. Use a valid TZ database name.
User and Group IDs
Section titled “User and Group IDs”hmsdocker_container_uid: 1234hmsdocker_container_gid: 1234The UID and GID used for running processes inside containers. These should match the user that owns your media files to avoid permission issues.
Global Port Exposure
Section titled “Global Port Exposure”hmsdocker_container_expose_ports: noWhen set to yes, all container ports will be exposed on the host. If neither Traefik nor Caddy is enabled in the container map, this is automatically overridden to yes.
For per-container port exposure, use the expose_ports setting in the Container Map.
Read-Only Media Mounts
Section titled “Read-Only Media Mounts”hmsdocker_readonly_media_containers: []A list of containers that get the media share (hmsdocker_mount_path) mounted read-only, for example:
hmsdocker_readonly_media_containers: ["plex", "jellyfin"]Each listed container still sees the media share at /data, but the mount is made with :ro. The container can read and play everything, but it cannot create, change, or delete anything on the share. This limits the damage a compromised or misbehaving media server can do. It cannot delete your library or encrypt it for ransom.
Supported containers: plex, emby, jellyfin, kavita, calibre, ersatztv, tunarr, audiobookshelf.
checkrr and librariarr always mount the media share read-only, whether or not they are listed. Listing them is accepted without a warning.
Any other container is not supported, including the ones that need to write to the media share (the Sonarr/Radarr family, the download clients, tdarr, and so on). If you list an unsupported container, or misspell a name, the playbook shows a preflight warning and that container’s mount stays writable.
Docker Socket Proxy
Section titled “Docker Socket Proxy”hmsdocker_socket_proxy_log_level: infohmsdocker_socket_proxy_overrides: {}Settings for the Docker Socket Proxy, which is enabled with socket-proxy in the Container Map.
hmsdocker_socket_proxy_log_level is the log level of the proxies, one of debug, info, warn or error (the proxies do not start with any other value, so the playbook checks it). Blocked requests are logged at warn, debug also logs every allowed request.
hmsdocker_socket_proxy_overrides changes the built-in access of individual containers, or switches a container back to the unfiltered Docker socket:
hmsdocker_socket_proxy_overrides: uptimekuma: mode: directSee Changing the defaults for all options.
Advanced Settings
Section titled “Advanced Settings”These settings are configured in inventory/group_vars/all/hmsd_advanced.yml
Project Name
Section titled “Project Name”hmsdocker_project_name: hms-dockerControls the base folder name used for the project. This affects:
- Data path:
/opt/<hmsdocker_project_name>/ - Docker Compose project name
- Docker network names (e.g.,
<hmsdocker_project_name>_proxy_net)
Data Path
Section titled “Data Path”hmsdocker_data_path: "/opt/{{ hmsdocker_project_name }}"Where all container data, configs, compose files, and secrets are stored. See the File/Folder Layout docs for the full directory structure.
Apps Path
Section titled “Apps Path”hmsdocker_apps_path: "{{ hmsdocker_data_path }}/apps"The directory where each container’s per-app data and configuration is stored (one subdirectory per container, e.g. apps/sonarr/config). Defaults to a subdirectory of hmsdocker_data_path and rarely needs to be changed.
Docker Network Subnet
Section titled “Docker Network Subnet”hmsdocker_docker_network_base_subnet: "172.27.0.0/16"The IP range used for all Docker networks. Individual /24 subnets are provisioned from this block for each Docker network. Change this if it overlaps with your internal network range.
Host Network Settings
Section titled “Host Network Settings”hmsdocker_subnet_mask: "24"Your local network subnet mask (e.g., for a 192.168.1.0/24 network, use 24). Used to generate the Traefik/Caddy IP allowlist rules and configure how some containers (Plex, Transmission) treat local network traffic.
Secrets File Permissions
Section titled “Secrets File Permissions”hmsdocker_secrets_env_user: roothmsdocker_secrets_env_group: roothmsdocker_secrets_env_mode: "0600"Controls the ownership and permissions of the .env file containing API keys and secrets. See the Secrets files section in the File/Folder Layout docs for more details on adjusting these.