Initial commit: KavCorp infrastructure documentation
- CLAUDE.md: Project configuration for Claude Code - docs/: Infrastructure documentation - INFRASTRUCTURE.md: Service map, storage, network - CONFIGURATIONS.md: Service configs and credentials - CHANGELOG.md: Change history - DECISIONS.md: Architecture decisions - TASKS.md: Task tracking - scripts/: Automation scripts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
304
docs/home-assistant-traefik.md
Normal file
304
docs/home-assistant-traefik.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user