proxmox-infra/docs/home-assistant-traefik.md

Home Assistant + Traefik Configuration

Last Updated: 2025-11-16

Overview

Home Assistant is configured to work behind Traefik as a reverse proxy, accessible via https://hass.kavcorp.com.

Configuration Details

Home Assistant

• VMID: 100
• Node: pm1
• Type: QEMU VM (Home Assistant OS)
• Internal IP: 10.4.2.62
• Internal Port: 8123
• External URL: https://hass.kavcorp.com

Traefik Configuration

Location: /etc/traefik/conf.d/home-automation.yaml (inside Traefik LXC 104)

http:
  routers:
    homeassistant:
      rule: "Host(`hass.kavcorp.com`)"
      entryPoints:
        - websecure
      service: homeassistant
      tls:
        certResolver: letsencrypt
      # Home Assistant has its own auth

  services:
    homeassistant:
      loadBalancer:
        servers:
          - url: "http://10.4.2.62:8123"

Home Assistant Configuration

File: /config/configuration.yaml (inside Home Assistant VM)

Add or merge the following section:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.4.2.10  # Traefik IP
    - 172.30.0.0/16  # Home Assistant internal network (for add-ons)

Configuration Explanation:

• use_x_forwarded_for: true: Enables Home Assistant to read the real client IP from the X-Forwarded-For header that Traefik adds. This is important for:

  • Accurate logging of client IPs
  • IP-based authentication and blocking
  • Geolocation features

• trusted_proxies: Whitelist of proxy IPs that Home Assistant will trust

  • 10.4.2.10 - Traefik reverse proxy
  • 172.30.0.0/16 - Home Assistant's internal Docker network (needed for add-ons to communicate)

Setup Steps

Method 1: Web UI (Recommended)

1. Install File Editor Add-on (if not already installed):

   • Go to Settings → Add-ons → Add-on Store
   • Search for "File editor"
   • Click Install

2. Edit Configuration:

   • Open the File editor add-on
   • Navigate to /config/configuration.yaml
   • Add the http: section shown above
   • If an http: section already exists, merge the settings
   • Save the file

3. Check Configuration:

   • Go to Developer Tools → YAML
   • Click Check Configuration
   • Fix any errors if shown

4. Restart Home Assistant:

   • Go to Settings → System → Restart
   • Wait for Home Assistant to come back online

Method 2: Terminal & SSH Add-on

If you have the Terminal & SSH add-on installed:

# Edit the configuration
nano /config/configuration.yaml

# Add the http section shown above
# Save with Ctrl+X, Y, Enter

# Check configuration
ha core check

# Restart Home Assistant
ha core restart

Method 3: SSH to VM (Advanced)

If you have SSH access to the Home Assistant VM:

# SSH to pm1 first, then to the VM
ssh pm1
ssh root@10.4.2.62

# Edit configuration
vi /config/configuration.yaml

# Restart Home Assistant
ha core restart

Verification

After configuration and restart:

1. Test Internal Access:

   curl -I http://10.4.2.62:8123
   

   Should return HTTP/1.1 200 OK or 405 Method Not Allowed

2. Test Traefik Proxy:

   curl -I https://hass.kavcorp.com
   

   Should return HTTP/2 200 with valid SSL certificate

3. Check Logs:

   • In Home Assistant: Settings → System → Logs
   • Look for any errors related to HTTP or trusted proxies
   • Client IPs should now show actual client IPs, not Traefik's IP

4. Verify Headers:

   • Open browser developer tools (F12)
   • Go to Network tab
   • Access https://hass.kavcorp.com
   • Check response headers for X-Forwarded-For, X-Forwarded-Proto, etc.

Troubleshooting

400 Bad Request / Untrusted Proxy

Symptom: Home Assistant returns 400 errors when accessing via Traefik

Solution: Verify the trusted_proxies configuration includes Traefik's IP (10.4.2.10)

http:
  trusted_proxies:
    - 10.4.2.10

Wrong Client IP in Logs

Symptom: All requests show Traefik's IP (10.4.2.10) instead of real client IP

Solution: Enable use_x_forwarded_for:

http:
  use_x_forwarded_for: true

Configuration Check Fails

Symptom: YAML validation fails with syntax errors

Solution:

• Ensure proper indentation (2 spaces per level, no tabs)
• Check for special characters that need quoting
• Use ha core check to see detailed error messages

Cannot Access via Domain

Symptom: https://hass.kavcorp.com doesn't work but direct IP does

Solution:

1. Check Traefik logs:

   ssh pm2 "pct exec 104 -- tail -f /var/log/traefik/traefik.log"
   

2. Verify DNS resolves correctly:

   nslookup hass.kavcorp.com
   

3. Check Traefik config was loaded:

   ssh pm2 "pct exec 104 -- cat /etc/traefik/conf.d/home-automation.yaml"
   

SSL Certificate Issues

Symptom: Browser shows SSL certificate errors

Solution:

1. Check if Let's Encrypt certificate was generated:

   ssh pm2 "pct exec 104 -- cat /etc/traefik/ssl/acme.json | grep hass"
   

2. Allow time for DNS propagation (up to 1 hour with Namecheap)
3. Check Traefik logs for ACME errors

Security Considerations

Authentication

• Home Assistant has its own authentication system
• No Authelia middleware is applied to this route
• Users must log in to Home Assistant directly
• Consider enabling Multi-Factor Authentication in Home Assistant:
  • Settings → People → Your User → Enable MFA

Trusted Networks

If you want to bypass authentication for local network access, add to configuration.yaml:

homeassistant:
  auth_providers:
    - type: trusted_networks
      trusted_networks:
        - 10.4.2.0/24  # Local network
      allow_bypass_login: true
    - type: homeassistant

Warning: Only use this if your local network is secure!

IP Banning

Home Assistant can automatically ban IPs after failed login attempts. Ensure use_x_forwarded_for is enabled so it bans the actual attacker's IP, not Traefik's IP.

Related Services

Frigate Integration

If Frigate is integrated with Home Assistant:

• Frigate is accessible via https://frigate.kavcorp.com (see separate Frigate documentation)
• Home Assistant can embed Frigate camera streams
• Both services trust Traefik as reverse proxy

Add-ons and Internal Communication

Home Assistant add-ons communicate via the internal Docker network (172.30.0.0/16). This network must be in trusted_proxies for add-ons to work correctly when accessing the Home Assistant API.

Updating Configuration

When making changes to Home Assistant configuration:

1. Always check configuration before restarting:

   ha core check
   

2. Back up configuration before major changes:

   • Settings → System → Backups → Create Backup

3. Test changes in a development environment if possible

4. Monitor logs after restarting for errors

DNS Configuration

Ensure your DNS provider (Namecheap) has the correct A record:

hass.kavcorp.com → Your public IP (99.74.188.161)

Or use a CNAME if you have a wildcard:

*.kavcorp.com → Your public IP

Traefik handles the Let's Encrypt DNS-01 challenge automatically.

Additional Resources

• Home Assistant Reverse Proxy Documentation
• Traefik Documentation
• TRaSH Guides - Traefik Setup

Change Log

2025-11-16:

• Initial configuration created
• Added Home Assistant to Traefik
• Configured trusted proxies
• Set up hass.kavcorp.com domain