Skip to content
HMS-Docker

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”
hms_docker_compose_container_state: present

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

Restart Policy

Section titled “Restart Policy”
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

Auto-Update Schedule

Section titled “Auto-Update Schedule”
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”
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.

Timezone

Section titled “Timezone”
container_timezone: America/New_York

The 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”
container_uid: 1234
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.

Global Port Exposure

Section titled “Global Port Exposure”
container_expose_ports: no

When set to yes, all container ports will be exposed on the host. If Traefik is disabled in the container map, this is automatically overridden to yes.

For per-container port exposure, use the expose_ports setting in the Container Map.

Advanced Settings

Section titled “Advanced Settings”

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

Project Name

Section titled “Project Name”
project_name: hms-docker

Controls the base folder name used for the project. This affects:

  • Data path: /opt/<project_name>/
  • Docker Compose project name
  • Docker network names (e.g., <project_name>_proxy_net)

Data Path

Section titled “Data Path”
hms_docker_data_path: "/opt/{{ project_name }}"

Where all container data, configs, compose files, and secrets are stored. See the File/Folder Layout docs for the full directory structure.

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”
hms_docker_subnet_mask: "24"

Your local network subnet mask (e.g., for a 192.168.1.0/24 network, use 24). Used to generate Traefik IP allowlist rules and configure how some containers (Plex, Transmission) treat local network traffic.

Secrets File Permissions

Section titled “Secrets File Permissions”
secrets_env_user: root
secrets_env_group: root
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.