README.md

# Home Assistant Infrastructure Documentation

> **Last updated:** 2026-July  
> **HA Version:** 2026.3.1 (update available: 2026.6.4)  
> **HA Host:** 10.10.0.123  

---

## Infrastructure Overview

```
┌─────────────────────┐       ┌──────────────────────────┐       ┌──────────────────────┐
│   Home Assistant    │──────▶│       InfluxDB 2.7       │──────▶│       Grafana        │
│   10.10.0.123       │       │    SRvDocker1 (10.10.0.41)│       │   10.10.0.41:3001     │
│   HA 2026.3.1       │       │    port 8086              │       │   v13.1.0             │
└─────────────────────┘       └──────────────────────────┘       └──────────────────────┘
```

- **Home Assistant** pushes time-series metrics to InfluxDB v2.7
- **InfluxDB** stores metrics in the `home_assistant` bucket (13-month retention)
- **Grafana** reads from InfluxDB and renders dashboards
- Both InfluxDB and Grafana run as Docker containers on **SRvDocker1 (10.10.0.41)**

---

## 1. Cleanup Summary

The Home Assistant host disk was at **83% usage** and is now at **46%** after cleanup.

| Action | Space Freed |
|--------|-------------|
| Old HA backups (versions pre-2026) | ~28 GB |
| Orphaned temporary directories | ~7.2 GB |
| **Total** | **~35.2 GB** |

- Backups older than 3 months were identified and removed.
- Orphaned temp directories from previous addons/upgrades were cleaned.
- HA recorder database was compacted via auto-repair.

---

## 2. InfluxDB 2.7 Migration

### Background

- The old InfluxDB **addon** (installed inside HA) had been idle since December 2025.
- It was removed entirely to free resources on the HA host.
- A standalone InfluxDB 2.7.12 instance was deployed on SRvDocker1.

### Deployment Details

| Field | Value |
|-------|-------|
| **Version** | InfluxDB 2.7.12 |
| **Host** | SRvDocker1 (10.10.0.41) |
| **Port** | 8086 |
| **Docker Compose** | `/home/adminx/influxdb/docker-compose.yml` |
| **Bucket** | `home_assistant` |
| **Organization** | `swordrock` |
| **Retention** | 13 months (9456 hours) |
| **API Version** | v2 |
| **SSL** | Off (internal network) |
| **Admin Token** | Stored in locky Vaultwarden |

### Docker Compose

```yaml
# /home/adminx/influxdb/docker-compose.yml
services:
  influxdb:
    image: influxdb:2.7.12
    container_name: influxdb
    restart: unless-stopped
    ports:
      - "8086:8086"
    volumes:
      - /data/influxdb:/var/lib/influxdb2
      - /etc/influxdb2:/etc/influxdb2
    environment:
      - INFLUXDB_REPORTING_DISABLED=true
```

### Home Assistant Integration

- **Method:** UI-based setup (Settings → Devices & Services → InfluxDB)
- **Why UI and not YAML?** The `influxdb:` YAML configuration did not work on HA 2026.3.1. The UI-based integration was the only method that successfully connected and started pushing data.
- **YAML cleanup:** The `influxdb:` block was removed from `configuration.yaml` to avoid conflicts.

---

## 3. Recorder Tuning

To reduce SQLite DB writes and I/O pressure on the HA host, recorder settings were added to `configuration.yaml`.

### Configuration

```yaml
recorder:
  purge_keep_days: 7
  commit_interval: 30
```

| Setting | Value | Purpose |
|---------|-------|---------|
| `purge_keep_days` | 7 | Keep only 7 days of history in the SQLite DB |
| `commit_interval` | 30 | Batch commits every 30 seconds (reduces write frequency) |

The full configuration snippet is available in [`configuration-snippets.yaml`](configuration-snippets.yaml).

### Rationale

- Historical data is now stored in InfluxDB (13-month retention), so the HA SQLite DB only needs a short window.
- Lower commit frequency reduces disk I/O spikes.
- This keeps the HA SQLite DB small and fast while InfluxDB handles long-term storage.

---

## 4. Grafana Dashboards

### Deployment

| Field | Value |
|-------|-------|
| **Version** | Grafana 13.1.0 |
| **Host** | SRvDocker1 (10.10.0.41) |
| **Port** | 3001 |
| **Login** | `admin` |
| **Password** | Stored in locky Vaultwarden ("Grafana Admin" item) |
| **Data Source** | InfluxDB (Flux queries against `home_assistant` bucket) |

### Dashboards

#### 🏠 Home Energy
- **Solar production** (Watts, daily/monthly totals)
- **Grid consumption** (import/export, net metering)
- **Voltage** (L1, L2, L3 phases)
- **Frequency** (grid frequency monitoring)

#### 🌡️ Climate
- Indoor/outdoor **temperature** (all sensors)
- **Humidity** (indoor rooms, outdoor)
- **Weather** (forecast vs actual, pressure, wind)

#### 📷 Security Cameras
- Camera **status** (online/offline)
- Motion **event counts**
- Stream health and uptime

---

## 5. Known Issues

| Issue | Status | Notes |
|-------|--------|-------|
| **HA 2026.3.1 InfluxDB YAML config** | ⚠️ Workaround applied | YAML `influxdb:` block didn't work. UI-based integration is the only working method. |
| **HA update pending** | ⚠️ Available | HA 2026.6.4 is available. Upgrade may change InfluxDB integration behavior — test after upgrade. |
| **No network bandwidth data in HA** | ℹ️ By design | UniFi traffic/bandwidth data flows to Zabbix, not HA. No plan to change. |
| **No Zabbix → InfluxDB streaming** | ❌ Not configured | Zabbix metrics are not yet streamed to InfluxDB. Future enhancement: could pipe Zabbix alerts/metrics into InfluxDB for unified Grafana dashboards. |

---

## 6. Maintenance Notes

### Checking HA Disk
```bash
ssh ha-host df -h /
```

### InfluxDB Container Health
```bash
ssh srvoc0 "ssh 10.10.0.41 docker ps | grep influxdb"
```

### Grafana Container Health
```bash
ssh srvoc0 "ssh 10.10.0.41 docker ps | grep grafana"
```

### InfluxDB CLI
```bash
docker exec -it influxdb influx query 'from(bucket: "home_assistant") |> range(start: -1h) |> limit(n: 5)'
```

### Backup Reminders
- HA backups auto-prune at 7 days — verify retention is working.
- InfluxDB data lives on SRvDocker1 at `/data/influxdb` — ensure this is included in backup policy.
- Grafana dashboard JSONs should be exported periodically.

---

## Related

- [ZWave-JS-UI Repository](https://cody.swordrock.com/SwordRock/ZWave-JS-UI) — Z-Wave network management
- [Zabbix Monitoring](https://cody.swordrock.com/SwordRock/Zabbix) — Network monitoring, UniFi data
- locky Vaultwarden — All credentials (InfluxDB admin token, Grafana admin password)