HomeKit, HASS, and Mosquitto on TrueNAS SCALE

You aim for a reliably integrated smart home, powered by Home Assistant (HASS) and Mosquitto MQTT on TrueNAS SCALE. Central to this vision is reliable HomeKit control and discovery. This guide focuses on exactly that.

We’ll deploy HASS and Mosquitto with Docker Compose, configure HomeKit in bridge mode from the start, and directly address the persistent mDNS multicast routing issue. This problem often hinders HomeKit discovery on Docker bridge networks within TrueNAS SCALE. We’ll solve it with a precise Avahi-daemon fix, ensuring your Apple devices find your HomeKit bridge.

Setting Up Your Smart Home Core - HASS & Mosquitto with Docker Compose

Docker Compose defines and runs multi-container Docker applications. Here’s the foundation for your Home Assistant and Mosquitto stack.

Create a docker-compose.yaml file in a dedicated directory on your TrueNAS SCALE system (e.g., /mnt/poolname/apps/docker-smarthome):

version: "3.8"
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    volumes:
      # Use absolute paths under your base directory (e.g., /mnt/poolname/apps/docker/homeassistant)
      - /path/to/your/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 8123:8123 # Main Home Assistant web interface
      - 51827:51827 # HomeKit Accessory port (if you use HA as an accessory)
      - 21063:21063 # REQUIRED: HomeKit Bridge port
    environment:
      - TZ=America/Los_Angeles # Replace with your local timezone
  mosquitto:
    image: eclipse-mosquitto:2.0
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - 1883:1883 # MQTT standard port
      - 9001:9001 # MQTT websockets port (if needed)
    volumes:
      # Use absolute paths under your base directory (e.g., /mnt/poolname/apps/docker/mosquitto)
      - /path/to/your/mosquitto/config:/mosquitto/config
      - /path/to/your/mosquitto/data:/mosquitto/data
      - /path/to/your/mosquitto/log:/mosquitto/log

Key Points:

• Anonymized Paths: Remember to replace /path/to/your/... with actual absolute paths on your TrueNAS system. This ensures your configuration and data persist even if containers are recreated.
• Port Mappings: You map 8123:8123 for Home Assistant’s web UI. Crucially, you map 51827:51827 and 21063:21063 for HomeKit. The 21063 port specifically supports Home Assistant’s native HomeKit Bridge mode.
• Timezone: Set your correct TZ environment variable for accurate timekeeping within Home Assistant.

To get these running, navigate to your docker-compose.yaml directory in the TrueNAS SCALE shell and run:

docker compose up -d

Integrating HomeKit: Configuration and the mDNS Challenge

Home Assistant includes a robust native HomeKit integration. This allows HASS to expose all your connected smart devices as a single HomeKit Bridge, making them controllable from your Apple Home app.

Home Assistant configuration.yaml for HomeKit

Inside your Home Assistant configuration directory (/path/to/your/homeassistant/config), edit your configuration.yaml to include the HomeKit bridge settings:

# configuration.yaml entry for HomeKit
homekit:
  - name: HASS Bridge
    port: 21063 # Must match the port mapped in docker-compose.yaml
    advertise_ip: "192.168.1.50" # IMPORTANT: Replace with your TrueNAS Host LAN IP

Critical Detail: The advertise_ip is vital. By default, Home Assistant (running inside Docker) attempts to advertise its internal Docker bridge IP address. Your Apple devices on your main LAN cannot reach that. You must set this to the actual IP address of your TrueNAS SCALE host on your local network (e.g., 192.168.1.50).

The mDNS Impasse: Why HomeKit Fails to Discover

You’ve configured HASS, port-mapped the services, and specified the correct advertise_ip. Yet, when you try to add the HomeKit Bridge in your Apple Home app, it’s either “stuck connecting” or not discovered.

This is the classic mDNS multicast routing issue. Docker containers often run in an isolated bridge network. Multicast DNS (mDNS), also known as Bonjour or Zeroconf, uses multicast packets for service discovery. These packets do not route across network boundaries by default, especially between your Docker bridge network and your TrueNAS host’s main LAN. TrueNAS SCALE’s default Avahi configuration often adds to this isolation.

Your Apple devices on your Wi-Fi network send mDNS queries, but they never reach the Home Assistant container. Even if they did, Home Assistant’s mDNS advertisements would not make it back to your Apple devices.

TrueNAS SCALE - Avahi-daemon Fix for mDNS

TrueNAS SCALE uses avahi-daemon as its mDNS responder. To fix this communication breakdown, you must configure Avahi to act as an mDNS reflector, forwarding these critical multicast packets between your host network and the Docker bridge.

This requires directly editing the avahi-daemon.conf file on your TrueNAS SCALE host.

1. Access TrueNAS SCALE Shell: Log into your TrueNAS SCALE web interface and open the Shell.

2. Edit Avahi Configuration: Use a text editor like nano or vi to edit the file:

   sudo nano /etc/avahi/avahi-daemon.conf

3. Replace Content: Replace the entire content of the avahi-daemon.conf file with the following corrected configuration:

##
## avahi-daemon.conf
##
## Refer to avahi-daemon.conf(5) for more information about this file.
##

[server]
use-ipv4=yes
use-ipv6=yes
ratelimit-interval-usec=1000000
ratelimit-burst=1000
# ACTION: Removed Docker-related interfaces from deny list (e.g., docker0, br-*)
deny-interfaces=wg, lo, tun, tap, ix, tailscale
# ACTION: Removed 'allow-interfaces' line to listen on all interfaces
# This ensures Avahi listens on all active interfaces, including Docker bridges.

# ACTION: Must be 'no' to allow Home Assistant's mDNS stack to broadcast its service
disallow-other-stacks=no


[wide-area]
enable-wide-area=yes


[publish]
publish-hinfo=no
publish-workstation=no


[reflector]
enable-reflector=yes

Understanding the Fix:

• deny-interfaces: Explicitly remove common Docker interface patterns (like docker0 or br-*) from the deny list. This allows Avahi to listen to mDNS traffic on Docker’s bridge networks.
• Removed allow-interfaces: By not specifying allow-interfaces, Avahi defaults to listening on all available network interfaces, ensuring it catches traffic from both your physical LAN and Docker’s virtual networks.
• disallow-other-stacks=no: This is critical. Home Assistant runs its own mDNS advertising stack. Setting this to no prevents Avahi from blocking HA’s advertisements, allowing them to pass through.
• [reflector] section: This newly added section enables mDNS reflection. When enable-reflector=yes, Avahi acts as a repeater, forwarding mDNS packets it receives on one interface to all other interfaces. This bridges the gap between your host LAN and the Docker bridge network.

Restart, Verify, Pair

You’re almost there! With the Avahi configuration updated, you just need to restart services and verify.

1. Restart Avahi-daemon: In your TrueNAS SCALE Shell, restart the Avahi service:

   sudo systemctl restart avahi-daemon.service

2. Restart Home Assistant: Restart your Home Assistant container to ensure it picks up any network changes and re-advertises its services:

   docker compose restart homeassistant

   (Or restart the entire stack if preferred: docker compose restart)
3. Verify Discovery: On your Apple device, download an mDNS browser app (e.g., “Discovery - DNS-SD Browser” from the App Store). Look for services advertised by _hap._tcp.. You should now see your Home Assistant bridge advertising the correct IP address of your TrueNAS host.
4. Pair with Apple Home:
   • Important: If you previously attempted to pair and it failed, delete any existing, failed “bridge” entries from your Apple Home app.
   • Open your Apple Home app and add a new accessory.
   • Home Assistant provides a QR code and an 8-digit HomeKit code in its notifications (or under Settings > Integrations > HomeKit). Scan the QR code or enter the code manually.

Conclusion: Your Smart Home, Unlocked.

You’ve successfully deployed Home Assistant and Mosquitto on TrueNAS SCALE. This setup fixes the mDNS multicast routing issue, enabling HomeKit integration in bridge mode. Your smart home is now integrated and controlled locally from your TrueNAS server.

From here, explore Home Assistant’s vast integrations, dive deeper into MQTT automations, or consider adding other Dockerized smart home services. Your fully functional, self-hosted smart home hub awaits.