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)

```yaml
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:

```yaml
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:

```bash
# 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:

```bash
# 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**:
   ```bash
   curl -I http://10.4.2.62:8123
   ```
   Should return `HTTP/1.1 200 OK` or `405 Method Not Allowed`

2. **Test Traefik Proxy**:
   ```bash
   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`)

```yaml
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`:

```yaml
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:
   ```bash
   ssh pm2 "pct exec 104 -- tail -f /var/log/traefik/traefik.log"
   ```
2. Verify DNS resolves correctly:
   ```bash
   nslookup hass.kavcorp.com
   ```
3. Check Traefik config was loaded:
   ```bash
   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:
   ```bash
   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`:

```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:
   ```bash
   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](https://www.home-assistant.io/integrations/http/#reverse-proxies)
- [Traefik Documentation](https://doc.traefik.io/traefik/)
- [TRaSH Guides - Traefik Setup](https://trash-guides.info/Hardlinks/Examples/)

## Change Log

**2025-11-16**:
- Initial configuration created
- Added Home Assistant to Traefik
- Configured trusted proxies
- Set up `hass.kavcorp.com` domain