Skip to content

Container Settings Reference

These settings apply to all containers and are configured in inventory/group_vars/all/container_settings.yml

hmsdocker_compose_container_state: present

Controls whether containers should exist. Valid values: present, absent. Setting to absent will remove all containers.

hmsdocker_container_restart_policy: unless-stopped

Controls how containers behave when the Docker daemon or server restarts. Valid values:

  • unless-stopped (default) — Restarts automatically unless manually stopped
  • always — Always restarts regardless of exit status
  • on-failure — Only restarts if the container exits with a non-zero exit code
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.

hmsdocker_container_remove_orphans: yes

When enabled, containers that are disabled in the container map will be automatically stopped and removed on the next playbook run.

hmsdocker_container_timezone: America/New_York

The timezone passed to containers via the TZ environment variable. Use a valid TZ database name.

hmsdocker_container_uid: 1234
hmsdocker_container_gid: 1234

The UID and GID used for running processes inside containers. These should match the user that owns your media files to avoid permission issues.

hmsdocker_container_expose_ports: no

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

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.

hmsdocker_socket_proxy_log_level: info
hmsdocker_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: direct

See Changing the defaults for all options.


These settings are configured in inventory/group_vars/all/hmsd_advanced.yml

hmsdocker_project_name: hms-docker

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

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.

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.

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.

hmsdocker_secrets_env_user: root
hmsdocker_secrets_env_group: root
hmsdocker_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.