Traefik & Home Assistant

This article will guide you through the process of accessing your Home Assistant instance through the Traefik reverse proxy. An important note: if you want to enable automatic device discovery on your network, you will need to use the network_mode: host configuration.

Initial Setup

You can find the official Home Assistant Docker installation guide here: https://www.home-assistant.io/installation/alternative

Here is the basic Docker Compose configuration:

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /PATH_TO_YOUR_CONFIG:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

Network Mode Considerations

Initially, I tried to use Docker's bridge mode for better container isolation. However, I (and many others) encountered issues with ESPHome and automatic device discovery. The root cause was related to mDNS resolution.

After the initial setup, Home Assistant will be available at: http://<host>:8123

Setting Up External Access

To access Home Assistant from outside your network, you will need to follow the Traefik configuration.

Start with Step 1 of the Traefik setup guide.

Traefik Configuration

First, let's set up the Traefik configuration. Here is the Docker Compose configuration for Traefik:

version: "3.7"

services:
  traefik:
    image: "traefik:v2.11.0"
    container_name: "traefik"
    restart: always
    networks:
      - default
    ports:
      - "80:80"
      - "443:443"
    command:
      - "--api.dashboard=true"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.websecure.http.tls=true"
      - "--entrypoints.websecure.http.tls.certResolver=myresolver"
      - "--entrypoints.websecure.http.tls.domains[0].main=mydomain.com"
      - "--entrypoints.websecure.http.tls.domains[0].sans=*.mydomain.com"
      - "--providers.file.filename=/etc/traefik/dynamic.yml"
    volumes:
      - "./dynamic.yml:/etc/traefik/dynamic.yml"

networks:
  default:

Dynamic Configuration

Create a dynamic.yml file with the following configuration:

http:
  services:
    service-ha:
      loadBalancer:
        passHostHeader: true
        servers:
          - url: "<http://192.168.X.XXX:8123/>"

  routers:
    ha:
      entryPoints:
        - websecure
      rule: "Host(`homeassistant.mydomain.com`)"
      service: service-ha
      tls:
        certResolver: myresolver

192.168.X.XXX: IP of docker host.

Troubleshooting: X-Forwarded-For Headers

After setting up the configuration, you might encounter the following errors in your Home Assistant logs:

homeassistant  | 2024-12-22 20:39:20.779 ERROR (MainThread) [homeassistant.components.http.forwarded] Received X-Forwarded-For header from an untrusted proxy 192.168.176.2
homeassistant  | 2024-12-22 20:39:20.782 ERROR (MainThread) [homeassistant.components.http.forwarded] Received X-Forwarded-For header from an untrusted proxy 192.168.176.2

This error occurs because Home Assistant doesn't trust the Traefik proxy by default. To fix this:

1. Once you confirm Traefik's IP address (in this case, 192.168.176.2), add it to your Home Assistant configuration file:

Verify Traefik's IP address:

docker exec -it {traefik-container-id} sh
ifconfig

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.176.2# Traefik's IP address
  ip_ban_enabled: true
  login_attempts_threshold: 3

Monitor the logs to check the configuration:

docker compose logs -f

After adding the trusted proxy configuration, the errors should be resolved, and your Home Assistant instance will be securely accessible through Traefik.

Conclusion

Setting up Home Assistant behind a Traefik reverse proxy provides a secure and elegant way to access your smart home platform from the internet.

Key takeaways from this setup:

• Using network_mode: host ensures proper device discovery
• Properly configuring trusted proxies is crucial for security
• The setup enables secure remote access while maintaining local network functionality

With this configuration in place, you can safely access your Home Assistant instance from anywhere while maintaining proper security practices. Remember to regularly update both Traefik and Home Assistant to ensure you have the latest security features and improvements.

Useful links about Docker & mDNS:

https://conway.scot/mdns-docker/

https://medium.com/@andrejtaneski/using-mdns-from-a-docker-container-b516a408a66b

https://blog.hardill.me.uk/2020/09/27/dns-to-mdns/