DNS

Tip

It is recommended to use an internal DNS server (such as a Pi-hole or AdGuard Home) to resolve requests that point to an internal private IP address

The domain used is defined in the variable hms_docker_domain in inventory/group_vars/all/main.yml

UniFi DNS Role

There is an Ansible role available to enable that will manage the required DNS records if you are using a UniFi Network controller.

The role should only modify records that are used in this playbook and will create CNAME records that point to a single A record. This UniFi DNS role was created by Claude Code, so use at your own risk.

To enable, create the A record that points to your host manually in the Unifi console and then in your inventory/group_vars/all/unifi.yml file configure the following:

inventory/group_vars/all/unifi.yml

---
# Enable or disable the Unifi DNS role
unifi_dns_enabled: false

# The Unifi controller base URL (do NOT include a trailing slash)
# Example: "https://192.168.1.1"
unifi_dns_controller_url: ""

# The Unifi API key for authentication
# Generated in the Integrations section of your UniFi application
unifi_dns_api_key: ""

# The Unifi site name to manage DNS records for
# This matches the "internalReference" field from the sites API
unifi_dns_site_name: "default"

# The target A record domain name that all CNAME records will point to
# Example: "server.home.local"
unifi_dns_cname_target: ""

# Whether to include external Traefik hosts in DNS record management
unifi_dns_include_external_hosts: true

# Whether to include 4K instance subdomains (sonarr-4k, radarr-4k)
unifi_dns_include_4k_instances: true

Note

If any DNS records were created for this project prior to the UniFi DNS API becoming available, you will likely need to delete the records first. I observed that any records created prior to the API becoming available had the same ID, deleting them resolved the issue.

Accessing the Containers

Internally

There are several approaches for setting up internal DNS records. Choose whichever best fits your environment:

1. Wildcard A record (simplest) — Create a *.<domain> record on your local DNS server pointing to the private IP address of the server. This covers all subdomains automatically.

2. Individual A records — Create a separate A record for each container listed in the Container Map.

3. Single A record + CNAME records (recommended) — Create one A record (e.g., server.<domain>) and then CNAME records for each container pointing to it. This way, if the server IP changes, you only need to update one record.

To verify DNS is working, run:

nslookup <container>.<domain>
# Or query a specific DNS server:
nslookup <container>.<domain> <DNS server IP>

Once DNS resolves correctly, access containers at <name>.<domain> where <name> is the proxy_host_rule value from the container map and <domain> is the value of hms_docker_domain.

You can customize the subdomain for each application by changing its proxy_host_rule value in the container map.

Externally

For external access, if you enabled Cloudflare DDNS, a request.<domain> public A record will be created automatically that points to your network’s public IP.

• This default A record can be changed in the cloudflare_ddns_subdomain variable located in inventory/group_vars/all/cloudflare.yml.

Unless port 80 and/or 443 are port forwarded on the router to your host, accessing this public address from outside your main network will not work.

To grant public access to containers, you will need to:

1. Preferred Use a Cloudflare Tunnel

2. OR Create a public DNS record for it that is either:

   • A record that points to the public IP

   • CNAME record that points to the <cloudflare_ddns_subdomain>.<domain> (eg. seerr.example.com)

3. Set the expose_to_public value to yes for the specific container in the Container Map