TopherMayor/hermes-ice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: homelab infrastructure wiki

Browse Source 
- Full Obsidian vault content
- Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte)
- Media stack documentation
- Traefik HA setup
- Automation scripts
- Bachelor party planning
This commit is contained in:
Hermes Agent
2026-05-24 16:08:40 -07:00
parent d132442429
commit e4d91aadf9
285 changed files with 30018 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
homelab/concepts/ai-applications.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: AI Applications Pipeline
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, ai, services]
sources: [../../homelab/architecture.md]
---
# AI Applications Pipeline
Local AI/ML stack running on ubuntu with GPU acceleration (GTX 1080 8GB), plus AI-powered applications that use LLM inference.
## Core AI Infrastructure
| Service | URL | Purpose |
|---------|-----|---------|
| Ollama | localhost:11434 | Local LLM inference (GPU via GTX 1080) |
| Qdrant | ubuntu:6333 | Vector database for OpenCode cluster memory |
| Faster Whisper Server | — | Speech-to-text (Whisper) |
## AI Applications (7 containers)
| Application | Description |
|-------------|-------------|
| AI Job Pipeline (backend + frontend) | AI task orchestration |
| AI Alert Aggregator (backend + frontend + postgres) | Alert intelligence |
| AI Media Intelligence (backend) | Media analysis |
| AI Subscriptions | Subscription management |
| Homelab Inventory (backend) | Infrastructure inventory |
## Immich ML
| Component | Description |
|-----------|-------------|
| Immich Server | Photo/video management |
| Immich ML | Machine learning on GPU |
| Immich Postgres | Dedicated PostgreSQL (pgvecto-rs extension) |
| Immich Redis | Caching |
## OpenCode Embeddings
OpenCode instances across the cluster use:
- **Ollama** — generating embeddings for vector memory
- **Qdrant** — storing shared vector memory across OpenCode cluster
## Related
- [[opencode-cluster]] — OpenCode cluster using this AI infrastructure
- [[ubuntu]] — Hosts GPU (GTX 1080) and all AI services
- [[jellyfin]] — Media server with AI features
- [[../../homelab/docs/ai-applications.md]] — AI applications documentation

60
homelab/concepts/deployment-scripts.md Normal file
View File

@@ -0,0 +1,60 @@
---
title: Deployment Scripts
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, automation, homelab, scripts]
confidence: high
---
# Deployment Scripts
Maintenance, deployment, and operational automation scripts for homelab management.
## Homelab Scripts (`scripts/homelab/`)
| Script | Purpose |
|--------|---------|
| `deploy-service.py` | Deploy services to remote hosts |
| `detect-drift.py` | Detect config drift between repo and hosts |
| `drift_detector.py` | SSH-based container state comparison |
| `generate-context.py` | Generate context for AI assistants |
| `collect-host-inventory.py` | Collect host inventory information |
| `validate_catalog.py` | Validate catalog consistency |
## Authentik Scripts (`scripts/authentik/`)
Scripts for managing Authentik identity provider: OAuth2/OIDC providers, group bindings, branding, and SSO configuration.
## Maintenance Scripts (`scripts/maintenance/`)
| Script | Purpose |
|--------|---------|
| `fix-permissions.py` | Fix file and directory permissions |
| `fix-truenas-permissions.py` | Fix TrueNAS permissions |
## Ansible Playbooks (`ansible/`)
| Playbook | Purpose |
|----------|---------|
| `sync-configs.yml` | Pull/push docker-compose configs |
| `deploy-services.yml` | Restart Docker services |
| `sync-opencode.yml` | Push OpenCode configurations |
| `ping.yml` | Test connectivity to all hosts |
## Host Inventory
| Host | IP | Repo Path | Purpose |
|------|-----|-----------|---------|
| ubuntu | 192.168.50.61 | homelab/ubuntu | Primary Docker host |
| grizzley | 192.168.50.84 | homelab/grizzley | Edge ingress |
| ice | 192.168.50.197 | homelab/ice | Control plane |
| truenas | 192.168.50.12 | homelab/truenas | Storage host |
| pve | 192.168.50.11 | homelab/proxmox | Hypervisor |
## Related
- [[hermes-opencode-cluster]] — AI agent cluster using these scripts
- [[traefik-ha]] — Traefik ingress deployment
- [[nfs-storage]] — TrueNAS storage management
- [[sso-authentik]] — Authentik SSO configuration

162
homelab/concepts/device-placement-policy.md Normal file
View File

@@ -0,0 +1,162 @@
---
title: Device Placement Policy
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [iot, smart-home, concept, vlan, security, policy]
confidence: high
sources: [network-device-census, UniFi controller configuration]
---
# Device Placement Policy
> Defines which device classes belong on which VLAN, firewall rules required for cross-VLAN access, and the rationale for each placement decision.
## VLAN Architecture
```
┌─────────────────────────────────────────────────────────┐
│ UniFi Dream Machine │
│ 192.168.50.1 (Controller) │
├──────────┬──────────┬───────────┬──────────┬─────────────┤
│ VLAN 10 │ VLAN 20 │ VLAN 30 │ VLAN 50 │ Default │
│ Family │ Guest │ IoT │ Prod │ Mgmt │
│ .10.x │ .20.x │ .30.x │ .50.x │ .1.x │
└──────────┴──────────┴───────────┴──────────┴─────────────┘
```
## Device Class → VLAN Assignment
### VLAN 10 — "Family of D." (Personal Devices)
**Policy**: Trusted personal devices with full internal access. Phones, tablets, laptops, watches. No IoT devices unless they require direct phone access without firewall rules.
| Device Class | Examples | Rationale |
|-------------|----------|-----------|
| Phones | TophPhone14 (×3) | Need access to everything |
| Tablets | iPad | Personal use |
| Laptops | MacBook | Personal use |
| Watches | Apple Watch | Companion to phone |
| Baby monitors | Eufy cameras (×3) | **Exception**: Require constant phone access; avoid firewall complexity |
| RPi (personal) | Ice (.10.178 WiFi) | Personal use connection |
### VLAN 30 — "Will of D. IoT" (Smart Home + Infrastructure)
**Policy**: All IoT devices, smart home hardware, and infrastructure hosts that need inter-device communication. This is where [[panda]] and all smart home controllers live.
| Device Class | Examples | Rationale |
|-------------|----------|-----------|
| HA controller | [[panda]] (.30.196) | Central hub — needs access to all IoT |
| Zigbee/Thread hubs | [[home-assistant-connect-zbt-2]], [[aqara-hub-m3]] (.30.59) | Must reach Zigbee devices + HA |
| Voice assistants | Echo Dots (×4) | Matter controllers, need HA access |
| Media players | Apple TV (.30.234), LG TV (.30.79) | Controlled by HA + phones |
| Smart lighting | Shelly (×2), Govee (×5), TP-Link (×4) | WiFi actuators, HA-controlled |
| Climate | Nest Thermostat (.30.179) | HA + Google ecosystem |
| Air purifiers | Levoit Vital 200S (.30.21), AMWAY (.30.161) | WiFi appliances |
| Sensors/Locks | Aqara Zigbee devices (via hubs) | Non-IP, behind Zigbee coordinators |
| Cameras | Aqara Doorbell (.30.118), Camera Hub G3 (.30.113) | Aqara ecosystem, HA-managed |
| Robot vacuum | Eufy Omni C20 (.30.50) | WiFi appliance |
| Voice PE | HA Voice PE (.30.25) | ESPHome voice assistant |
| Sleep mat | Withings Rest (.30.177) | Health device |
| Infrastructure | Grizzley (.30.84), Ubuntu (.30.61), Ice (.30.197) | Also have .50.x on Production |
| NAS | TrueNAS (.30.11) | Also .50.12 on Production |
### VLAN 50 — "Production" (Server Infrastructure)
**Policy**: Server-to-server communication only. Infrastructure hosts carry dual NICs — .50.x for production traffic, .30.x for HA/IoT management.
| Device Class | Examples | Rationale |
|-------------|----------|-----------|
| Docker hosts | Ubuntu (.50.61), Grizzley (.50.84) | Production services |
| NAS | TrueNAS (.50.12) | Storage backend |
| Control plane | Ice (.50.197) | Gateway + monitoring |
| Proxmox | PVE (.50.11) | Hypervisor |
### VLAN 20 — "Will of D. (Guest)" (Guest Access)
**Policy**: Internet-only access, no internal device communication.
| Device Class | Examples | Rationale |
|-------------|----------|-----------|
| Guest phones | Any | Internet only |
| Solar monitor | SunPower (.20.190) | Internet-only reporting? ⚠️ Verify |
### Default — No VLAN (Management)
**Policy**: Network infrastructure management. Switches, wired-only devices without VLAN tagging.
| Device Class | Examples | Rationale |
|-------------|----------|-----------|
| Managed switch | TP-Link SG108PE (.1.92) | Switch management |
| Unknown wired | HYTERevolt (.1.143), VectorPro (.1.77) | Unidentified — investigate |
## Cross-VLAN Firewall Rules
Current state and recommended rules:
### Required (Missing)
| Source | Destination | Ports | Purpose | Priority |
|--------|------------|-------|---------|----------|
| VLAN 10 | VLAN 30:8123 | TCP 8123 | Phone → HA dashboard | High |
| VLAN 10 | VLAN 30:443 | TCP 443 | Phone → Traefik ingress to HA | High |
| VLAN 10 | VLAN 30 (Eufy) | Eufy app ports | Phone → Baby cameras | Medium |
| VLAN 50 | VLAN 30 | All | Server ↔ IoT management | Medium |
| VLAN 30 | VLAN 50 | All | IoT → Storage (NFS, S3) | Medium |
### Already Working (Same VLAN)
| Source → Dest | VLAN | Why it works |
|--------------|------|-------------|
| Phone → Eufy cameras | 10 → 10 | Same VLAN, no firewall needed |
| HA → All IoT devices | 30 → 30 | Same VLAN, no firewall needed |
| Echo → Alexa cloud | 30 → Internet | Outbound allowed by default |
| Nest → Google cloud | 30 → Internet | Outbound allowed by default |
## Placement Decision Tree
```
New device arrives
├── Is it a personal phone/tablet/laptop/watch?
│ └── YES → VLAN 10
├── Is it a server or infrastructure host?
│ ├── YES → Dual: VLAN 50 (production) + VLAN 30 (management)
│ └── NO ↓
├── Is it an IoT device managed by HA?
│ ├── YES → VLAN 30
│ └── NO ↓
├── Does it need direct phone access WITHOUT HA?
│ ├── YES → VLAN 10 (with note: add to HA if possible)
│ └── NO ↓
├── Is it a guest device?
│ ├── YES → VLAN 20
│ └── NO ↓
└── Unknown → VLAN 30 (IoT) + investigate
```
## Exceptions & Rationale
| Device | Expected VLAN | Actual VLAN | Reason |
|--------|-------------|-------------|--------|
| Eufy Baby Cameras (×3) | 30 | 10 | Phone accessibility without firewall rules |
| SunPower Solar Monitor | 30 or 10 | 20 | Possibly internet-only reporting; verify |
| HYTERevolt | 10 or 50 | Default | Unknown device — needs identification |
| VectorPro | 50 | Default | Unknown device — needs identification |
## Migration Checklist
If moving Eufy cameras to VLAN 30 for better segmentation:
1. Reserve IPs on VLAN 30 for 3 Eufy cameras
2. Add UniFi firewall rule: VLAN 10 → VLAN 30, allow Eufy app ports (TCP 8006, 8080, 9000 — verify with Eufy docs)
3. Add UniFi firewall rule: VLAN 10 → VLAN 30, allow mDNS (UDP 5353) for device discovery
4. Reconnect cameras to IoT SSID
5. Test phone app access from VLAN 10
6. Update [[network-device-census]] with new IPs
## Related Pages
- [[network-device-census]] — Full device classification
- [[iot-device-inventory]] — IoT devices by room
- [[matter-multi-fabric]] — Matter ecosystem architecture
- [[smart-home-handbook]] — Operational handbook

82
homelab/concepts/docker-traefik-stack.md Normal file
View File

@@ -0,0 +1,82 @@
---
title: Docker Traefik Stack
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, networking, homelab, docker, traefik]
confidence: high
---
# Docker Traefik Stack
Container orchestration and ingress configuration across the homelab. Two Traefik instances provide high-availability routing.
## Traefik Instances
| Instance | Host | Role | Version |
|----------|------|------|---------|
| ubuntu Traefik | 192.168.50.61 | Primary router | v3.6.7 |
| grizzley Traefik | 192.168.50.84 | Edge ACME + ingress | v3.6.7 |
See [[traefik-ha]] for the full HA strategy.
## Dynamic Config Files (ubuntu)
Located in `homelab/ubuntu/traefik/config/dynamic/`:
| File | Services Routed |
|------|----------------|
| `canonical-hosts.yml` | Grizzley ingress proxy, PVE OpenCode |
| `gitea.yml` | gitea.tophermayor.com |
| `homeassistant.yml` | ha.tophermayor.com |
| `immich.yml` | immich.tophermayor.com |
| `jellyfin.yml` | jellyfin.tophermayor.com |
| `jellyseerr.yml` | jellyseerr.tophermayor.com |
| `media-stack.yml` | Sonarr, Radarr, SABnzbd, Prowlarr, qBittorrent, Lidarr, Readarr (via gluetun) |
| `middlewares.yml` | 30+ middleware definitions |
| `opencode.yml` | opencode.tophermayor.com |
| `proxmox.yml` | proxmox.local.tophermayor.com |
| `stremio.yml` | stremio.local.tophermayor.com |
| `traefik-dashboard.yml` | traefik.local.tophermayor.com |
| `truenas.yml` | truenas.local.tophermayor.com |
| `vaultwarden.yml` | vaultwarden.tophermayor.com |
| `wildcard-certs.yml` | TLS certificate file references |
## Common Middlewares
| Middleware | Purpose |
|------------|---------|
| `local-only@file` | Restrict to local network IPs |
| `authentik-auth@file` | SSO authentication |
| `security-headers@file` | Add security headers |
| `crowdsec-bouncer@file` | Rate limiting and threat protection |
## Docker Networks
| Network | Scope | Purpose |
|---------|-------|---------|
| `proxy-net` | External | Traefik-routed services |
| `app-net` | External | Internal backend communication |
| `authentik-internal` | Bridge | SSO isolation |
| `monitoring-internal` | Bridge | Metrics/logs isolation |
| `immich-internal` | Bridge | Immich DB/Redis/ML |
| `traefik-proxy` | Bridge (grizzley) | Grizzley edge Traefik |
| `media-net` | External | Media stack isolation |
## Container Labels
Standard Traefik labels:
```yaml
labels:
- "traefik.enable=true"
- "traefik.http.services.<service>.loadbalancer.server.port=8096"
- "traefik.http.routers.<router>.rule=Host(`service.tophermayor.com`)"
- "traefik.http.routers.<router>.tls.certresolver=cloudflare"
```
## Related
- [[traefik-ha]] — Traefik HA strategy across ubuntu + grizzley
- [[sso-authentik]] — Authentik SSO middleware
- [[media-stack]] — Media automation routing
- [[hermes-opencode-cluster]] — OpenCode routing via Traefik

144
homelab/concepts/forge-ai.md Normal file
View File

@@ -0,0 +1,144 @@
---
title: Forge AI
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, ai, tools, cli]
sources: [../raw/articles/forge/]
confidence: high
---
# Forge AI
Forge AI (ForgeCode) is a CLI-based AI coding harness — a competitor to Claude Code with first-class support for many AI providers. It works with cloud models, open-weight models, and local models.
**Website:** https://forgecode.dev
## Agents
Forge provides three built-in agents:
| Agent | Access | Purpose |
|-------|--------|---------|
| **muse** | read + write | Planning and analysis — reviews impact, plans changes |
| **forge** | read + write | Implementation — makes changes, fixes bugs (default) |
| **sage** | read | Research — used internally by muse/forge for codebase understanding |
Typical workflow: use `muse` to plan, switch to `forge` to implement.
Switch agents with `:agent`, `:muse`, `:forge`.
## Custom Agents
Create agents as markdown files with YAML frontmatter in `.forge/agents/` (project) or `~/forge/agents/` (global).
```yaml
---
id: my-agent
title: My Agent
description: Brief description
tools: [read, search, shell]
model: claude-sonnet-4
provider: anthropic
temperature: 0.1
---
System prompt here.
```
Tools: read, write, patch, shell, search, fetch, remove, undo, or `"*"` for all.
## Custom Commands
Repeatable workflows as slash commands in `.forge/commands/`:
```markdown
---
name: check
description: Runs lint and tests before commit
---
Run `lint` and `test`, fix any issues found.
<lint>cargo clippy --fix</lint>
<test>cargo test</test>
```
Invoke with `:check` in the Forge chat.
## MCP Integration
Connect external tools via `.mcp.json`:
```json
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}
```
Manage with `forge mcp import`, `forge mcp list`, `forge mcp remove`, `forge mcp reload`.
## Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `FORGE_TERM` | on | Terminal context capture — passes command history to the model |
| `FORGE_TERM_MAX_COMMANDS` | 5 | History buffer size |
| `FORGE_CONFIG` | `~/forge/` | Config directory (for dotfiles repos) |
| `FORGE_BIN` | `forge` | Binary path (for local builds or version switching) |
## $FORGE_TERM
On by default. The Zsh plugin tracks what commands you run, whether they succeeded, and passes that to ForgeCode on every `:` invocation. Means `forge fix it` already knows what failed — no need to narrate.
Disable per-session: `export FORGE_TERM=false`
## Forge Services
Optional backend for enhanced capabilities: context engine (semantic search), tool-call guardrails, and skill engine. Enable with `:login` → select ForgeServices.
Index project with `:sync`, check status with `:sync-status`.
## Setup
```bash
# 1. Install
curl -fsSL https://forgecode.dev/cli | sh
# 2. Zsh plugin
forge zsh setup
# 3. Login to provider
:login
# 4. Pick model
:model
# 5. First prompt
: Hi!
```
Requires: Nerd Font, Zsh.
## Skills
ForgeCode skills are markdown files (`.forge/skills/`) that provide reusable workflows. Similar to custom commands but more powerful — skills can use templating and conditional logic.
## Configuration Files
| File | Purpose |
|------|---------|
| `.forge.toml` | Main config ( ForgeConfig dir) |
| `.mcp.json` | MCP server definitions |
| `.forge/agents/` | Custom agent definitions |
| `.forge/commands/` | Custom slash commands |
| `.forge/skills/` | Reusable skill workflows |
| `AGENTS.md` | Project-wide rules for all agents |
## Related
- [[opencode-cluster]] — OpenCode cluster setup in this homelab
- [[ai-applications]] — AI application stack on ubuntu
- [[hermes-gateway]] — Hermes gateway used for model routing

62
homelab/concepts/gitops.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: GitOps
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, git, automation]
sources: [../automation/scripts.md, ../../homelab/architecture.md]
---
# GitOps
The homelab uses a GitOps pattern where the git repository IS the infrastructure.
## Core Principle
All configuration lives in `/home/bear/homelabagentroot/`. Each host pulls its configs from the repo. Agents (Hermes, OpenCode) commit changes and push to Gitea. Other hosts pull on next session.
## Repository Structure
```
homelabagentroot/
├── homelab/ # Infrastructure configs per host
│ ├── ubuntu/ # Docker Compose, configs
│ ├── grizzley/ # RPi5 edge configs
│ ├── ice/ # Control plane configs
│ └── proxmox/ # VM/LXC configs
├── scripts/ # Shared automation
├── ansible/ # Playbooks for deployment
├── obsidian-vault/ # Wiki (IS the vault)
└── .opencode/ # OpenCode agent config
```
## Git Triggers
| Action | What Happens |
|--------|-------------|
| Agent commits & pushes | Configs pushed to Gitea |
| Other host pulls | Gets latest configs |
| Drift detected | `detect-drift.py` or `drift_detector.py` flags differences |
| Manual deploy | `ansible-playbook deploy-services.yml --limit <host>` |
## Agents Using GitOps
| Agent | Host | Role |
|-------|------|------|
| Hermes | ice, grizzley | Commit infra changes, push to Gitea |
| OpenCode | ubuntu, ice | Read/write configs, run Ansible |
| Gitea | ubuntu | GitOps hub — all repos live here |
## Key Files
- `scripts/homelab/deploy-service.py` — Deploy services to remote hosts
- `scripts/homelab/detect-drift.py` — Detect config drift between repo and hosts
- `ansible/playbooks/deploy-services.yml` — Restart Docker services
- `ansible/playbooks/sync-configs.yml` — Pull/push docker-compose configs
## Related
- [[gitea]] — Git host and GitOps runner hub
- [[ubuntu]] — Primary Docker host where most configs deploy
- [[ice]] — Control plane, primary Hermes Agent host
- [[deployment-scripts]] — Full automation scripts inventory

52
homelab/concepts/hermes-opencode-cluster.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: Hermes OpenCode Cluster
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, ai, homelab, agents]
confidence: high
---
# Hermes OpenCode Cluster
AI agent cluster setup — OpenCode instances deployed as systemd services across the homelab, with Hermes gateway providing model routing.
## Instance Overview
| Instance | Host | IP | Port | Traefik Route | Status |
|----------|------|-----|------|---------------|--------|
| ubuntu | Ubuntu VM | 192.168.50.61 | 4096 | opencode.tophermayor.com | Active (systemd) |
| ice | Raspberry Pi 4 | 192.168.50.197 | 4096 | opencode-ice.tophermayor.com | Active (systemd) |
| grizzley | Raspberry Pi 5 | 192.168.50.84 | 4096 | — | Inactive/disabled |
## Host Context Detection
Each host clone has a `.host-context` file that identifies the local context. See [[host-context-detection]] for the full detection table.
## Skills
Skills are located in `.agents/skills/` and `.opencode/`:
- `proxmox-management` — VM/LXC operations
- `traefik-diagnostic` — Router/service health
- `truenas-storage` — ZFS pool/share management
- `authentik-sso` — SSO/OIDC configuration
- `media-stack` — Radarr, Sonarr, Jellyfin management
- `komodo-management` — Docker stack deployment
- `host-power-management` — Wake-on-LAN, VM control
- `infra-audit` — Live infrastructure verification
## Hermes Gateway
Hermes runs on grizzley as the central gateway, providing:
- Telegram notifications (topic 1033 "Cron Jobs")
- Model routing across providers
- DeepSeek V4 integration (primary), Anthropic (fallback)
- Watchdog monitoring for gateway health
## Related
- [[host-context-detection]] — Per-host agent detection
- [[forge-ai|Forge AI]] — ForgeCode CLI coding harness
- [[hermes-gateway|Hermes gateway]] — model routing and notifications
- [[opencode-cluster|OpenCode cluster]] — detailed OpenCode systemd deployment

363
homelab/concepts/homelab-network-architecture.md Normal file
View File

@@ -0,0 +1,363 @@
---
title: Homelab Network Architecture
created: 2026-04-29
updated: 2026-04-29
type: concept
tags: [concept, networking, homelab, traefik, ha]
sources: []
---
# Homelab Network Architecture
Complete traffic flow and routing topology for the homelab cluster. Covers Traefik dual-instance HA, VRRP failover, certificate distribution, Docker network segmentation, and all routing rules.
## Traffic Flow Overview
```
Internet (Cloudflare DNS)
│
▼ *.tophermayor.com A → home public IP
══════════════════════════════════════════════════════════════════════
VRRP VIP 192.168.50.80/27 (eth0.50) — keepalived
┌─────────────────────────────────────────────────────────────┐
│ PRIMARY: ubuntu traefik (when up) │
│ BACKUP: grizzley traefik-pi (when ubuntu fails) │
└─────────────────────────────────────────────────────────────┘
│
▼ port 80/443
┌──────────────────────────────────────────────────────────────────┐
│ grizzley traefik-pi │
│ Edge ingress controller (ACME master, Cloudflare DNS challenge) │
│ IP: 192.168.50.84 | Ports: 80,443,2222,8080,19132udp,19134udp │
│ Network: traefik-proxy │
│ Certs: /mnt/truenas/traefik-certs/grizzley (NFS) │
└──────────────────────────────────────────────────────────────────┘
│
├──[grizzley-local services]──────────────────────────► served directly
│ vaultwarden, uptime-kuma, komodo, homepage,
│ aiostreams, aiomanager, aiometadata,
│ opencode-ice, homeassistant, proxmox, truenas
│
└──[everything else]────────────────────────────────────► forwarded to ubuntu
(upstream-ingress.yml load-balances to ubuntu:443)
```
## DNS Zones
| Zone | Example | Resolution |
|------|---------|------------|
| Public (`*.tophermayor.com`) | `gitea.tophermayor.com`, `jellyfin.tophermayor.com` | Cloudflare → home public IP |
| Local (`*.local.tophermayor.com`) | `sonarr.local.tophermayor.com`, `proxmox.local.tophermayor.com` | UniFi Controller DHCP/DNS |
Cloudflare proxies all `*.tophermayor.com` — origin IP is hidden, DDoS protection active.
## Network Segmentation
### Physical / VLAN
| Network | Subnet | Gateway | Hosts |
|---------|--------|---------|-------|
| Production (VLAN 50) | 192.168.50.0/24 | 192.168.50.1 | ice, grizzley, ubuntu, proxmox, truenas |
| Default (VLAN 1) | 192.168.1.0/24 | 192.168.1.1 | Management workstations |
| Trusted (VLAN 3) | 192.168.3.0/24 | — | Trusted devices |
| WireGuard VPN | 192.168.4.0/24 | — | VPN clients |
| Docker bridge | 172.16.0.0/12 | — | Container internal networking |
### Docker Networks (ubuntu)
| Network | Driver | Subnet | Connected Services |
|---------|--------|--------|-------------------|
| `proxy-net` | bridge | 172.18.0.0/16 | traefik (primary ingress), homepage-ubuntu |
| `app-net` | bridge | 172.20.0.0/16 | general application containers |
| `uefi-proxynet` | bridge | 172.26.0.0/16 | — |
| `authentik_authentik-internal` | bridge | — | authentik server/worker/redis |
| `monitoring_monitoring-internal` | bridge | — | prometheus, grafana, loki, alertmanager |
| `immich_immich-internal` | bridge | — | immich stack |
| `reccollection-internal` | bridge | — | reccollection stack |
| `ai-subscriptions_default` | bridge | — | ai-subscriptions |
| `infisical_infisical` | bridge | — | infisical stack |
### Docker Networks (grizzley)
| Network | Driver | Connected Services |
|---------|--------|-------------------|
| `traefik-proxy` | bridge | traefik-pi, homepage-grizzley, komodo, aiostreams, aiomanager, aiometadata, vaultwarden, uptime-kuma |
| `aiomanager_default` | bridge | aiomanager stack |
| `aiometadata_aiometadata-internal` | bridge | aiometadata stack |
| `komodo_komodo-internal` | bridge | komodo stack |
| `homepage_default` | bridge | homepage-grizzley |
| `desktop-test_default` | bridge | test containers |
## High Availability (VRRP / Keepalived)
Two Traefik instances provide failover via keepalived VRRP on VLAN 50.
| Parameter | Value |
|-----------|-------|
| Interface | `eth0.50` (VLAN 50) |
| Virtual Router ID | 51 |
| ubuntu priority | **PRIMARY** (higher) |
| grizzley priority | **BACKUP** (90) |
| Virtual IP | `192.168.50.80/27` |
| Auth | PASS (`HomelabH`) |
| Health check | `/etc/keepalived/check_traefik.sh` — 2s interval, fall 2, rise 2 |
When ubuntu Traefik fails health checks, keepalived promotes grizzley to MASTER and the VIP moves to grizzley's interface. Traffic for `*.tophermayor.com` and `*.local.tophermayor.com` then routes to grizzley's traefik-pi (192.168.50.84).
## Certificate Architecture
```
Cloudflare DNS Challenge (grizzley traefik-pi)
│
▼
ACME writes certs to /etc/traefik/certs/acme.json
│
▼ (real-time via NFS)
/mnt/truenas/traefik-certs/grizzley (NFS share from TrueNAS)
│
▼ (read by ubuntu traefik at startup/reread)
ubuntu traefik serves same wildcard certs (*.tophermayor.com)
```
Both instances serve the **same** Cloudflare-issued wildcard certificate (`*.tophermayor.com`) for all public-facing services. The ACME challenge only runs on grizzley — ubuntu syncs certs via NFS.
## Traefik Instance Comparison
| Aspect | ubuntu (PRIMARY) | grizzley (BACKUP / ACME) |
|--------|-----------------|--------------------------|
| Container | `traefik` | `traefik-pi` |
| Image | `traefik:v3.6.7` | `traefik:v3.6.7` |
| IP | 192.168.50.61 | 192.168.50.84 |
| Port 80/443 | Direct | Direct |
| HTTP→HTTPS | ✓ | ✓ |
| Cloudflare ACME | ✗ (reads via NFS) | ✓ (origin) |
| Static configs | `middlewares.yml` | `middlewares.yml` |
| Dynamic configs | 29 files | 4 files |
| Networks | `proxy-net`, `app-net`, `uefi-proxynet` | `traefik-proxy` |
| Metrics port | — | 8080 |
| SSH proxy port | — | 2222 |
| UDP Minecraft | — | 19132, 19134 |
| upstream-ingress | (receives traffic) | forwards to ubuntu |
## Traefik Dynamic Configs
### grizzley (Edge / ACME)
| File | Contents |
|------|---------|
| `pi-routers.yml` | Wildcard cert triggers (`traefik-wildcard.local.tophermayor.com`, `traefik-wildcard.tophermayor.com`) |
| `grizzley-services.yml` | 11 local routers: vaultwarden, uptime-kuma, komodo, homepage, opencode-ice, aiostreams, aiomanager, aiometadata, homeassistant, proxmox, truenas |
| `upstream-ingress.yml` | Forwards all unmatched traffic to ubuntu Traefik (HTTPS 192.168.50.61) |
| `metrics.yml` | Internal metrics endpoints |
| `middlewares.yml` | IP allowlists (`local-only`, `homepage-localonly`), security headers |
### ubuntu (Primary Router)
| File | Contents |
|------|---------|
| `gitea.yml` | gitea.tophermayor.com → gitea:3000 |
| `immich.yml` | immich.tophermayor.com → immich_server:2283 |
| `jellyfin.yml` | jellyfin.tophermayor.com → jellyfin:8096 (rate limit + jellyfin headers) |
| `media-stack.yml` | sonarr, radarr, lidarr, prowlarr, qbittorrent, sabnzbd, readarr, sonarr-anime, radarr-anime, lazylibrarian, nzbdav → via gluetun VPN tunnel |
| `opencode.yml` | opencode.tophermayor.com → host.docker.internal:4096 |
| `proxmox.yml` | proxmox.local.tophermayor.com → https://192.168.50.11:8006 |
| `homepage-widgets.yml` | Internal routes (sonarr-internal, radarr-internal, etc.) → gluetun VPN tunnel |
| `upstream-ingress.yml` | Homepage routes to homepage-ubuntu:3003 and homepage-grizzley:3000 |
| `whisper.yml` | whisper.local.tophermayor.com → faster-whisper-server:8394 |
| `truenas.yml` | truenas.local.tophermayor.com → TrueNAS web UI |
| `navidrome.yml` | navidrome.tophermayor.com |
| `audiobookshelf.yml` | audiobooks.tophermayor.com |
| `calibre-web.yml` | calibre-web.local.tophermayor.com |
| `kavita.yml` | kavita.tophermayor.com |
| `rustfs.yml` | rustfs S3 routes |
| `stremio.yml` | stremio routes |
| `jellyseerr.yml` | jellyseerr.tophermayor.com |
| `comparaison.yml` | comparison service |
| `inventory.yml` | inventory service |
| `cabo-voting.yml` | Cabo voting app |
| `gsd-mcp.yml` | GSD MCP server |
| `ai-subscriptions.yml` | AI subscriptions service |
| `hermes-dashboard.yml` | Hermes dashboard routes |
| `homeassistant.yml` | Home Assistant route |
| `umm.yml` | Unified media manager |
| `middlewares.yml` | Full middleware stack (see below) |
## All Traefik Routes
### grizzley traefik-pi (Local Services)
| Domain | Service | Backend | Middleware | Cert |
|--------|---------|---------|------------|------|
| `vaultwarden.tophermayor.com` | vaultwarden | vaultwarden:80 | — | cloudflare |
| `status.tophermayor.com` | uptime-kuma | uptime-kuma:3001 | — | cloudflare |
| `komodo.local.tophermayor.com` | komodo | komodo:9120 | — | cloudflare |
| `homepage.local.tophermayor.com` | homepage | homepage-grizzley:3000 | homepage-localonly | cloudflare |
| `opencode-ice.local.tophermayor.com` | opencode-ice | 192.168.50.197:4096 | local-only | cloudflare |
| `aiostreams.tophermayor.com` | aiostreams | aiostreams:3002 | — | cloudflare |
| `aiomanager.tophermayor.com` | aiomanager | aiomanager:1610 | — | cloudflare |
| `aiometadata.tophermayor.com` | aiometadata | aiometadata:1337 | — | cloudflare |
| `ha.tophermayor.com` | homeassistant | 192.168.30.196:8123 | — | cloudflare |
| `proxmox.local.tophermayor.com` | proxmox | 192.168.50.11:8006 | local-only | cloudflare |
| `truenas.local.tophermayor.com` | truenas | 192.168.50.12:8080 | local-only | cloudflare |
| `traefik-grizzley.local.tophermayor.com` | dashboard | api@internal | local-only | cloudflare |
| `metrics-grizzley.local.tophermayor.com` | metrics | api@internal | local-only | cloudflare |
### grizzley traefik-pi (Upstream → ubuntu)
Traffic NOT matched above is forwarded via `upstream-ingress.yml`:
| Rule | Target |
|------|--------|
| `HostRegexp(^[a-z0-9-]+\.local\.tophermayor\.com$) && !homepage && !traefik-grizzley && !metrics-grizzley && !traefik-wildcard && !opencode-ice` | → ubuntu:443 |
| `HostRegexp(^[a-z0-9-]+\.tophermayor\.com$) && !traefik-wildcard` | → ubuntu:443 |
### ubuntu traefik (Public Routes — *.tophermayor.com)
| Domain | Backend | Middleware |
|--------|---------|------------|
| `gitea.tophermayor.com` | gitea:3000 | homelab-public |
| `immich.tophermayor.com` | immich_server:2283 | homelab-public |
| `jellyfin.tophermayor.com` | jellyfin:8096 | ratelimit, jellyfin-headers |
| `audiobooks.tophermayor.com` | audiobookshelf | homelab-public |
| `navidrome.tophermayor.com` | navidrome | homelab-public |
| `kavita.tophermayor.com` | kavita:5000 | homelab-public |
| `opencode.tophermayor.com` | host.docker.internal:4096 | local-only, opencode-streaming, opencode-cors |
| `ha.tophermayor.com` | 192.168.30.196:8123 | (see homeassistant.yml) |
| `jellyseerr.tophermayor.com` | jellyseerr | homelab-public |
### ubuntu traefik (Local Routes — *.local.tophermayor.com)
| Domain | Backend | Middleware | Notes |
|--------|---------|------------|-------|
| `sonarr.local.tophermayor.com` | gluetun:8989 | local-only | Via VPN tunnel |
| `radarr.local.tophermayor.com` | gluetun:7878 | local-only | Via VPN tunnel |
| `lidarr.local.tophermayor.com` | gluetun:8686 | local-only | Via VPN tunnel |
| `sabnzbd.local.tophermayor.com` | gluetun:8080 | local-only | Via VPN tunnel |
| `qbittorrent.local.tophermayor.com` | qbittorrent | local-only | |
| `prowlarr.local.tophermayor.com` | prowlarr | local-only | |
| `readarr.local.tophermayor.com` | readarr | local-only | |
| `sonarr-anime.local.tophermayor.com` | sonarr-anime | local-only | Via VPN tunnel |
| `radarr-anime.local.tophermayor.com` | radarr-anime | local-only | Via VPN tunnel |
| `flaresolverr.local.tophermayor.com` | flaresolverr | local-only | |
| `bazarr.local.tophermayor.com` | bazarr:6767 | local-only | |
| `lazylibrarian.local.tophermayor.com` | lazylibrarian | local-only | |
| `nzbdav.local.tophermayor.com` | nzbdav | local-only | |
| `calibre-web.local.tophermayor.com` | calibre-web:8083 | local-only | |
| `stremio.local.tophermayor.com` | stremio-server | local-only | |
| `proxmox.local.tophermayor.com` | 192.168.50.11:8006 | proxmox-headers, local-only | |
| `truenas.local.tophermayor.com` | 192.168.50.12:8080 | local-only | |
| `opencode-ice.local.tophermayor.com` | 192.168.50.197:4096 | local-only | |
| `whisper.local.tophermayor.com` | faster-whisper-server:8394 | local-only | |
| `traefik.local.tophermayor.com` | api@internal | local-only | Dashboard |
### Internal Widget Routes (sonarr-internal, etc.)
These are `*-internal.local.tophermayor.com` routes for Homepage widgets, accessible only inside the network via the gluetun VPN tunnel. From `homepage-widgets.yml`:
| Internal Domain | Backend (via gluetun) |
|-----------------|----------------------|
| `sonarr-internal.local.tophermayor.com` | gluetun:8989 |
| `radarr-internal.local.tophermayor.com` | gluetun:7878 |
| `lidarr-internal.local.tophermayor.com` | gluetun:8686 |
| `sabnzbd-internal.local.tophermayor.com` | gluetun:8080 |
| `seerr-internal.local.tophermayor.com` | seerr:5055 |
| `jellyfin-internal.local.tophermayor.com` | jellyfin:8096 |
| `prometheus-internal.local.tophermayor.com` | prometheus:9090 |
### Special Protocols
| Protocol | Port | Host | Purpose |
|----------|------|------|---------|
| HTTP→HTTPS | 80 | grizzley | Redirects to 443 |
| HTTPS | 443 | grizzley | All TLS traffic |
| QUIC/HTTP3 | 443/udp | grizzley | HTTP3 support |
| Traefik metrics | 8080 | grizzley | Prometheus scraping |
| Gitea SSH proxy | 2222 | grizzley | → ubuntu:2222 |
| Minecraft Bedrock | 19132/udp | grizzley | Bedrock server (standby) |
| Minecraft Bedrock | 19134/udp | grizzley | Bedrock server (sison) |
## Middleware Chains (ubuntu)
### homelab-public
Applied to: gitea, immich, audiobookshelf, navidrome, kavita, jellyseerr, etc.
```
chain: [compress, security-headers, buffering, ratelimit]
```
### Security Headers
Applied to most services:
```yaml
browserXssFilter: true
contentTypeNosniff: true
forceSTSHeader: true
stsIncludeSubdomains: true
stsPreload: true
stsSeconds: 31536000 # 1 year
customFrameOptionsValue: SAMEORIGIN
```
### Jellyfin-specific Headers
Adds CSP allowing jsDelivr CDN for the Ultrachromic theme:
```yaml
contentSecurityPolicy: "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; ..."
```
### Authentik ForwardAuth (SSO)
Applied to: sonarr, radarr, lidarr, prowlarr, bazarr, sabnzbd, transmission, qbittorrent, flaresolverr, jellyseerr, listsync, dockge, it-tools, bentopdf, code-ai, and more.
Each service has its own middleware with `X-authentik-host` query param:
```
http://authentik-server:9000/outpost.goauthentik.io/auth/traefik?X-authentik-host=<domain>
```
### local-only IP Allowlist
```yaml
sourceRange:
- 127.0.0.1/32
- 192.168.50.0/24 # Production
- 192.168.1.0/24 # Management
- 192.168.3.0/24 # Trusted
- 192.168.4.0/24 # WireGuard VPN
- 172.16.0.0/12 # Docker
- 10.0.0.0/8 # VPN/Docker
```
### Rate Limiting
```yaml
average: 100
burst: 50
```
## VPN Tunnel (gluetun)
Media automation services route through **gluetun** VPN container for privacy when connecting to torrent/indexer services:
- sonarr → gluetun:8989
- radarr → gluetun:7878
- lidarr → gluetun:8686
- sabnzbd → gluetun:8080
gluetun ports: 8000, 8388, 8888 (TCP), 8388 (UDP) — exposed on ubuntu's Docker network.
## SSH Routing
Gitea SSH is proxied through grizzley:
```
Internet → grizzley:2222 (SNI * → any)
→ forwards to ubuntu:2222
→ gitea container handles git SSH protocol
```
## UniFi Controller
Network services (DHCP, DNS, VLAN tagging) managed by UniFi Controller at 192.168.1.1 (or similar). All internal DNS for `*.local.tophermayor.com` resolves through the UniFi DNS forwarder.
## Related
- [[traefik]] — Traefik entity page
- [[grizzley]] — RPi5 edge node (ACME master, backup ingress)
- [[ubuntu]] — Primary Docker host (primary ingress router)
- [[truenas]] — NFS storage for cert sync
- [[traefik-ha]] — HA concept page
- [[homepage]] — Dashboard services with widget routes
- [[authentik]] — SSO identity provider
- [[sso-authentik]] — SSO configuration details

53
homelab/concepts/host-context-detection.md Normal file
View File

@@ -0,0 +1,53 @@
---
title: Host Context Detection
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, homelab, agents]
confidence: high
---
# Host Context Detection
Detects which host's filesystem a repository clone represents, enabling AI agents to understand their operational context without asking.
## Quick Reference
| Host | IP | Context | Agent | Port |
|------|-----|---------|-------|------|
| **ubuntu** | 192.168.50.61 | ubuntu | OpenCode | 4096 |
| **grizzley** | 192.168.50.84 | grizzley | Hermes | 8644 |
| **ice** | 192.168.50.197 | ice | OpenCode | 4096 |
## Detection Methods
```bash
# Via Python
python3 scripts/detect_host_context.py
# Via Shell
source scripts/load-host-context.sh
```
## Context Files
| File | Purpose |
|------|---------|
| `.host-context` | Context marker per host (gitignored) |
| `scripts/detect_host_context.py` | Python detector |
| `scripts/load-host-context.sh` | Shell loader |
## Agent Integration
| Agent | Harness | Context Detection |
|-------|---------|-------------------|
| OpenCode | systemd | `.opencode/opencode.json` init |
| Hermes | systemd | Runs on grizzley (implicit) |
| Claude Code | CLI | direnv / shell env |
| Cline | VS Code | Terminal env |
## Related
- [[opencode-cluster|OpenCode cluster]] — OpenCode instances across the cluster
- [[hermes-gateway|Hermes gateway]] — runs on grizzley
- [[forge-ai|Forge AI]] — ForgeCode CLI coding harness

55
homelab/concepts/index.md Normal file
View File

@@ -0,0 +1,55 @@
---
title: Homelab Concepts Index
created: 2026-04-28
updated: 2026-05-24
type: index
tags: [meta]
---
# Concepts Index
> Content catalog for homelab concepts. Every concept page listed with a one-line summary.
> Last updated: 2026-05-24 | Total pages: 19
## Architecture & Infrastructure
| Concept | Summary |
|---------|---------|
| [[docker-traefik-stack]] | Docker + Traefik orchestration — two Traefik instances, 15+ dynamic routes, 7 networks |
| [[forge-ai]] | Forge AI (ForgeCode) — CLI coding harness, agents, custom commands, MCP integration |
| [[gitops]] | GitOps workflow — repo IS the infrastructure, all hosts pull from Gitea |
| [[traefik-ha]] | Traefik HA across ubuntu + grizzley — edge ACME, primary router, cert sync |
| [[nfs-storage]] | TrueNAS NFS mount strategy — media on NFS, configs on local disk |
| [[subscriptions]] | Full catalog of paid subscriptions + self-hosted services with cost breakdown |
## Smart Home / IoT
> Start at [[smart-home]] — the Map of Content for everything IoT.
| Concept | Summary |
|---------|---------|
| [[smart-home]] | MOC — hub page with floor map, ecosystem controllers, quick navigation to all IoT pages |
| [[matter-multi-fabric]] | Matter multi-admin architecture — fabric topology, hub-to-device mapping, commissioning |
| [[iot-device-inventory]] | 38 IoT devices by room — Zigbee parents, Matter fabrics, ecosystem exposure |
| [[network-device-census]] | Canonical classification of all 46 UniFi clients + 10 Zigbee devices |
| [[smart-home-handbook]] | Operational handbook — architecture, quick reference, troubleshooting, improvement plan |
| [[device-placement-policy]] | VLAN placement rules for every device class — decision tree, firewall rules, exceptions |
## Operations
| Concept | Summary |
|---------|---------|
| [[deployment-scripts]] | Homelab scripts, Ansible playbooks, maintenance automation |
| [[hermes-opencode-cluster]] | OpenCode systemd cluster across ice/ubuntu/grizzley + Hermes gateway |
| [[host-context-detection]] | Per-host context detection for AI agents (ice, ubuntu, grizzley) |
| [[monitoring-pipeline]] | Prometheus → Alertmanager → Hermes webhook → Telegram alerting chain |
| [[sso-authentik]] | Authentik SSO identity provider — OAuth2/OIDC, group bindings, Traefik middleware |
## Automation & AI
| Concept | Summary |
|---------|---------|
| [[ai-applications]] | AI application pipeline — Ollama GPU inference, embedding generation, Qdrant vector DB |
| [[media-stack]] | Media automation stack — Sonarr, Radarr, Jellyfin, Tdarr, Gluetun VPN |
| [[vm-storage-policy]] | Storage rules for Ubuntu VM — NFS for media/data, local for configs |
| [[opencode-cluster]] | OpenCode AI coding assistant deployed as systemd services across hosts |

159
homelab/concepts/iot-device-inventory.md Normal file
View File

@@ -0,0 +1,159 @@
---
title: IoT Device Inventory
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [iot, smart-home, zigbee-device, wifi-device, sensor, actuator, home-assistant]
confidence: high
sources: [UniFi Network clients, HA integrations, network-device-census]
---
# IoT Device Inventory
> All IoT devices (iot-smart-home, iot-appliance, iot-camera) grouped by room/area. Includes Matter fabric membership, Zigbee parent, and ecosystem exposure. For full classification of all 46 network clients, see [[network-device-census]].
## By Room / Area
### baby\_room (3rd Floor)
- **Aqara Light Switch H2 US** — Zigbee → ZHA | Actuator | Fabric: via [[aqara-hub-m3]] Matter bridge†
- **Aqara Colorful Ceiling Light 36W** — Zigbee → ZHA | Actuator | Fabric: via [[aqara-hub-m3]] Matter bridge†
- **eufy Baby Camera** — WiFi | `192.168.10.110` | VLAN 10 | Camera | No HA integration
- **eufy Baby Camera** — WiFi | `192.168.10.113` | VLAN 10 | Camera | No HA integration
- **eufy Baby Monitor** — WiFi | `192.168.10.120` | VLAN 10 | Camera | No HA integration
- **Rest 2nd Gen** — WiFi | `192.168.30.177` | VLAN 30 | Sleep sound device | No HA integration
### bedroom (3rd Floor)
- **Aqara Hub M3** — Wired | `192.168.30.59` | VLAN 30 | Hub | HA: matter, zha | Fabrics: HA ✓, Apple†, Google†, Alexa† | Zigbee coordinator + Matter bridge
- **Shelly 1PM Gen4** — WiFi | `192.168.30.75` | VLAN 30 | Actuator | HA: shelly | Ecosystem: HA | Ceiling light relay
- **Govee Floor Lamp Left** — WiFi | `192.168.30.91` | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA
- **Govee Floor Lamp R** — WiFi | `192.168.30.217` | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA
- **Govee LED Strip** — WiFi | IP TBD | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA
- **Echo Dot (Bedroom)** — WiFi | `192.168.30.170` | VLAN 30 | Voice | HA: alexa\_devices | Ecosystem: HA, Alexa | Matter controller
### dining\_room (2nd Floor)
- No devices currently assigned
### entrance (1st Floor)
- **Aqara Light Switch H2 US** — Zigbee → ZHA | Actuator | Fabric: via [[aqara-hub-m3]] Matter bridge†
- **Aqara Light Switch H2 US** (Front Door) — Zigbee → ZHA | Actuator | Fabric: via [[aqara-hub-m3]] Matter bridge†
- **Aqara Smart Lock U100** — Zigbee/BLE → ZHA | Actuator | Fabric: via [[aqara-hub-m3]] Matter bridge†
- **Aqara Video Doorbell G410** — WiFi | `192.168.30.118` | VLAN 30 | Camera | Ecosystem: HA
### garage (1st Floor)
- **Aqara Camera Hub G3** — WiFi | `192.168.30.113` | VLAN 30 | Camera | Ecosystem: HA
- **Echo Dot (Garage)** — WiFi | `192.168.30.68` | VLAN 30 | Voice | HA: alexa\_devices | Ecosystem: HA, Alexa | Unnamed in UniFi (MAC 18:74:2e:d9:d7:28) | Matter controller
### guest\_bathroom (3rd Floor)
- No devices currently assigned
### hall\_area (3rd Floor)
- No devices currently assigned
### kitchen (2nd Floor)
- **Echo Dot (Kitchen)** — WiFi | `192.168.30.26` | VLAN 30 | Voice | HA: alexa\_devices | Ecosystem: HA, Alexa | Matter controller
### laundry\_room (3rd Floor)
- No devices currently assigned
### living\_room (2nd Floor)
- **LG OLED65C5AUA TV** — WiFi | `192.168.30.79` | VLAN 30 | Display | HA: webostv | Ecosystem: HA
- **Aqara Motion Sensor P1** — Zigbee → ZHA | Sensor | Fabric: via [[aqara-hub-m3]] Matter bridge†
- **IKEA STARKVIND Air Purifier** — Zigbee → ZHA | Actuator | Ecosystem: HA
- **TP-Link KP115** — WiFi | `192.168.30.193` | VLAN 30 | Actuator | HA: tplink | Ecosystem: HA | Tall lamp plug
- **Govee TV Backlight** — WiFi | IP TBD | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA
- **Govee Shelf Light** — WiFi | IP TBD | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA
- **Govee Square Light** — WiFi | IP TBD | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA
- **Govee unnamed** — WiFi | `192.168.30.34` | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA | Possibly TV Backlight/Shelf/Square
- **Govee unnamed** — WiFi | `192.168.30.242` | VLAN 30 | Actuator | HA: govee\_light\_local | Ecosystem: HA | Possibly TV Backlight/Shelf/Square
### office (1st Floor)
- **Apple TV 4K gen 3** — WiFi | IP TBD | VLAN 30 | Display | HA: apple\_tv | Ecosystem: HA, Apple | Matter controller (not in UniFi dump)
- **Echo Dot (Office)** — WiFi | `192.168.30.150` | VLAN 30 | Voice | HA: alexa\_devices | Ecosystem: HA, Alexa | Matter controller
- **Shelly 1PM Gen4** — WiFi | `192.168.30.7` | VLAN 30 | Actuator | HA: shelly | Ecosystem: HA | Light relay
- **LG webOS Monitor** — WiFi | IP TBD | VLAN 30 | Display | HA: webostv | Ecosystem: HA
### rooftop\_door (Rooftop)
- **Aqara Door/Window Sensor** — Zigbee → ZHA | Sensor | Ecosystem: HA
- **Aqara Vibration Sensor T1** — Zigbee → ZHA | Sensor | Ecosystem: HA
### 1st Floor (unspecified)
- **Aqara Light Switch H2 US** — Zigbee → ZHA | Actuator | Ecosystem: HA
### Unassigned Room
- **TP-Link HS103** — WiFi | `192.168.30.116` | VLAN 30 | Actuator | HA: tplink | Ecosystem: HA
- **TP-Link HS103** — WiFi | `192.168.30.165` | VLAN 30 | Actuator | HA: tplink | Ecosystem: HA
- **TP-Link HS103** — WiFi | `192.168.30.210` | VLAN 30 | Actuator | HA: tplink | Ecosystem: HA
- **Nest Thermostat** — WiFi | `192.168.30.179` | VLAN 30 | Climate | HA: nest | Ecosystem: HA, Google | Google Home native
- **eufy Omni C20** — WiFi | `192.168.30.50` | VLAN 30 | Vacuum | No HA integration | Robot vacuum
- **Levoit Vital 200S** — WiFi | `192.168.30.21` | VLAN 30 | Purifier | HA: vesync | Ecosystem: HA
- **HA Voice PE** — WiFi | `192.168.30.25` | VLAN 30 | Voice | HA: wyoming | Ecosystem: HA | ESPHome voice assistant
## Zigbee Mesh Map
All Zigbee devices coordinated by [[home-assistant-connect-zbt-2]] (Connect ZBT-2 dongle on [[panda]]):
```
ZBT-2 (Coordinator)
├── Aqara Hub M3 (Matter bridge, also wired Thread BR)
├── Aqara Door/Window Sensor (rooftop)
├── Aqara Vibration Sensor T1 (rooftop)
├── Aqara Motion Sensor P1 (living room)
├── Aqara Light Switch H2 US × 4 (baby room, front door, entrance, 1st floor)
├── Aqara Colorful Ceiling Light 36W (baby room)
├── Aqara Smart Lock U100 (front door)
└── IKEA STARKVIND Air Purifier (TBD)
```
## Matter Fabric Membership
See [[matter-multi-fabric]] for full fabric topology and commissioning details.
| Device | Protocol | HA Fabric | Apple Fabric | Google Fabric | Alexa Fabric |
|--------|----------|-----------|--------------|---------------|--------------|
| Aqara Hub M3 | Matter/Thread | ✓ Commissioned | † Pending | † Pending | † Pending |
| Connect ZBT-2 | Thread OTBR | ✓ Controller | — | — | — |
| Nest Thermostat | WiFi/Matter | ✓ nest | — | ✓ Native | — |
| Echo Dots ×4 | WiFi/Matter | ✓ alexa\_devices | — | — | ✓ Controllers |
| Apple TV 4K | WiFi/Matter | ✓ apple\_tv | ✓ Controller | — | — |
† Not yet commissioned into this fabric.
## Statistics
- **IoT devices total**: 28 WiFi/wired + 10 Zigbee = **38**
- **By type**: 22 actuators, 4 sensors, 5 cameras, 6 voice/display, 1 climate, 2 appliances
- **By protocol**: 10 Zigbee, 25 WiFi, 2 wired, 1 Thread/Matter
- **HA integrated**: 28 of 38 (74%)
- **Ecosystem coverage**: HA (28), Alexa (4 Echo controllers), Google (1 Nest), Apple (1 Apple TV)
- **Matter capable**: 6 controllers/bridges, end-device commissioning in progress
## Relationships
- Canonical source: [[network-device-census]]
- Architecture overview: [[matter-multi-fabric]]
- Operational guide: [[smart-home-handbook]]
- Primary coordinator: [[home-assistant-connect-zbt-2]] on [[panda]]
- Matter bridge: [[aqara-hub-m3]]
## Open Tasks
- [ ] Match unnamed Govee devices (192.168.30.34, .242) to specific models (TV Backlight / Shelf Light / Square Light)
- [ ] Verify Apple TV 4K IP address and UniFi presence
- [ ] Confirm eufy cameras integration into HA (currently no integration found)
- [ ] Assign rooms to unassigned HS103 plugs
- [ ] Identify "Office" wired device at 192.168.30.234
- [ ] Add BLE iBeacon tracker documentation

197
homelab/concepts/matter-multi-fabric.md Normal file
View File

@@ -0,0 +1,197 @@
---
title: Matter Multi-Fabric Architecture
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [matter, thread, smart-home, iot, ecosystem, concept, hub]
confidence: high
sources: [UniFi Network clients, HA integrations, network-device-census]
---
# Matter Multi-Fabric Architecture
> The smart home uses Matter's native multi-admin capability to unify devices across HA, Apple, Google, and Alexa ecosystems. Home Assistant is the central controller; all other ecosystems are secondary fabrics.
## Why Multi-Fabric?
Matter **multi-admin** allows a single device to be commissioned into multiple fabrics simultaneously:
- Same lock/switch/light appears in Apple Home, Google Home, Alexa, AND Home Assistant
- Native Matter protocol — no cloud bridges or vendor workarounds
- Each ecosystem gets independent control; device responds to commands from any fabric
- Most Matter devices support 4–5 simultaneous fabric memberships
## Fabric Topology
```
┌───────────────────────────────────────────────────────────┐
│ MATTER END DEVICES │
│ Aqara Zigbee devices (via M3 bridge) │ Nest Thermostat │
└──────┬──────────┬──────────────┬───────────┬──────────────┘
│ │ │ │
┌─────▼───┐ ┌───▼────┐ ┌──────▼───┐ ┌─────▼──────┐
│ Fabric 1 │ │Fabric 2│ │ Fabric 3 │ │ Fabric 4 │
│ HA │ │ Apple │ │ Google │ │ Alexa │
│ (ZBT-2) │ │(AppleTV)│ │ (Nest) │ │ (4× Echo) │
└─────┬───┘ └───┬────┘ └────┬─────┘ └─────┬──────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────────┐
│ Thread Network (single mesh) │
│ Thread Border Routers share credentials │
│ ZBT-2 (primary) │ Aqara Hub M3 │ Apple TV │ Echo │
└──────────────────────────────────────────────────────┘
```
## Ecosystem Controllers
### Fabric 1: Home Assistant (Primary)
- **Controller**: [[home-assistant-connect-zbt-2]] on [[panda]] (HAOS)
- **Thread role**: Primary OTBR — owns Thread network credentials
- **Network**: `192.168.30.196` (wired), `192.168.30.12` (WiFi)
- **Access**: `https://ha.tophermayor.com` (via Traefik on [[ubuntu]])
- **Capabilities**: Full automation, scripts, scenes, voice pipeline, all integrations
- **Devices seen**: Everything (central hub)
### Fabric 2: Apple Home
- **Controller**: Apple TV 4K gen 3 (Office, WiFi VLAN 30)
- **Thread role**: Potential OTBR
- **HA integration**: `apple_tv`
- **Capabilities**: Siri voice, Home app, automations
- **Devices**: Aqara devices via Matter multi-admin through [[aqara-hub-m3]]
### Fabric 3: Google Home
- **Controller**: Nest Thermostat (`192.168.30.179`, WiFi VLAN 30)
- **HA integration**: `nest`
- **Capabilities**: Google Assistant voice, Google Home app
- **Devices**: Nest Thermostat (native), Aqara devices via Matter multi-admin
- **Note**: Consider adding Nest Hub as dedicated controller + Thread BR
### Fabric 4: Amazon Alexa
- **Controllers**: 4× Echo Dot
- Office Echo (`192.168.30.150`)
- Kitchen Echo (`192.168.30.26`)
- Bedroom Echo (`192.168.30.170`)
- Garage Echo (`192.168.30.68`, unnamed in UniFi)
- **HA integration**: `alexa_devices` (cloud)
- **Capabilities**: Alexa voice, routines, "Everywhere" speaker group
- **Thread role**: Echo Dots (gen 5) can act as Thread BRs
## Hub-to-Device Mapping
Which devices sit behind which hub, and how they reach each ecosystem:
### Direct WiFi Devices (no hub needed)
| Device | IP | HA Integration | Apple | Google | Alexa |
|--------|-----|---------------|-------|--------|-------|
| Nest Thermostat | 192.168.30.179 | nest | — | ✓ Native | — |
| Office Echo | 192.168.30.150 | alexa\_devices | — | — | ✓ Native |
| Kitchen Echo | 192.168.30.26 | alexa\_devices | — | — | ✓ Native |
| Bedroom Echo | 192.168.30.170 | alexa\_devices | — | — | ✓ Native |
| Garage Echo | 192.168.30.68 | alexa\_devices | — | — | ✓ Native |
| Apple TV 4K | TBD | apple\_tv | ✓ Native | — | — |
| Shelly 1PM (bedroom) | 192.168.30.75 | shelly | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| Shelly 1PM (office) | 192.168.30.7 | shelly | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| Govee Floor Lamp L | 192.168.30.91 | govee\_light\_local | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| Govee Floor Lamp R | 192.168.30.217 | govee\_light\_local | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| Govee unnamed ×2 | .34, .242 | govee\_light\_local | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| TP-Link HS103 ×3 | .116, .165, .210 | tplink | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| TP-Link KP115 | 192.168.30.193 | tplink | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| Levoit Purifier | 192.168.30.21 | vesync | ‡ Bridge | ‡ Bridge | ‡ Bridge |
| LG OLED TV | 192.168.30.79 | webostv | ‡ Bridge | ‡ Bridge | ‡ Bridge |
‡ Requires HA Matter Bridge — not yet configured.
### Aqara Zigbee Devices (via [[aqara-hub-m3]] Matter bridge)
All Zigbee devices are managed by ZHA via [[home-assistant-connect-zbt-2]]. The Aqara Hub M3 can additionally bridge them to Apple/Google/Alexa via Matter.
| Device | Location | Zigbee Parent | HA (ZHA) | Apple (M3) | Google (M3) | Alexa (M3) |
|--------|----------|---------------|----------|------------|-------------|------------|
| Light Switch H2 US | Baby Room | ZBT-2 | ✓ | † | † | † |
| Light Switch H2 US | Front Door | ZBT-2 | ✓ | † | † | † |
| Light Switch H2 US | Entrance | ZBT-2 | ✓ | † | † | † |
| Light Switch H2 US | 1st Floor | ZBT-2 | ✓ | † | † | † |
| Ceiling Light 36W | Baby Room | ZBT-2 | ✓ | † | † | † |
| Smart Lock U100 | Front Door | ZBT-2 | ✓ | † | † | † |
| Motion Sensor P1 | Living Room | ZBT-2 | ✓ | † | † | † |
| Door/Window Sensor | Rooftop | ZBT-2 | ✓ | † | † | † |
| Vibration Sensor T1 | Rooftop | ZBT-2 | ✓ | † | † | † |
| STARKVIND Purifier | TBD | ZBT-2 | ✓ | † | † | † |
† Pending Aqara Hub M3 Matter bridge commissioning into Apple/Google/Alexa fabrics.
### Aqara WiFi Devices (direct)
| Device | IP | HA Integration | Apple | Google | Alexa |
|--------|-----|---------------|-------|--------|-------|
| Hub M3 | 192.168.30.59 | matter, zha | † | † | † |
| Camera Hub G3 | 192.168.30.113 | — | — | — | — |
| Doorbell G410 | 192.168.30.118 | — | — | — | — |
† Hub M3 is the bridge device — commissioning it into other fabrics exposes all bridged Zigbee devices.
## Thread Border Router Strategy
All border routers must join a **single Thread mesh** with matching credentials:
| Border Router | Host | Status | Role |
|---------------|------|--------|------|
| [[home-assistant-connect-zbt-2]] OTBR | [[panda]] | ✅ Active | Primary — owns credentials |
| [[aqara-hub-m3]] | Bedroom | ⚠️ Verify credentials match | Secondary BR |
| Apple TV 4K gen 3 | Office | Potential OTBR | Not yet configured |
| Echo Dot (gen 5?) | Various | Potential OTBR | Not yet configured |
**Rule**: Export Thread credentials from ZBT-2 OTBR. Ensure all other BRs join same network (Network Key, PAN ID, channel).
## Non-Matter Devices → HA Matter Bridge
HA can expose non-Matter devices to other ecosystems via **Matter Bridge**:
| Device Type | Protocol | HA Integration | Bridge Status |
|-------------|----------|---------------|---------------|
| Shelly 1PM Gen4 ×2 | WiFi | shelly | ⬚ Not configured |
| Govee lights ×5 | WiFi/LAN | govee\_light\_local | ⬚ Not configured |
| TP-Link Kasa ×4 | WiFi | tplink | ⬚ Not configured |
| VeSync purifier | WiFi/Cloud | vesync | ⬚ Not configured |
| LG TV ×2 | WiFi | webostv | ⬚ Not configured |
| IKEA purifier | Zigbee | ZHA | ⬚ Not configured |
## Commissioning Checklist
When adding a new Matter device:
1. Commission into **HA first** (Settings → Devices & Services → Matter → Add Device)
2. Get multi-admin pairing code from HA device info
3. Commission into **Apple Home** using pairing code
4. Commission into **Google Home** using pairing code
5. Commission into **Alexa** using pairing code
For non-Matter devices:
1. Add to HA via native integration
2. Enable **HA Matter Bridge** in HA Settings → Matter → Bridge
3. Commission HA Bridge into target ecosystems
## Relationships
- Central hub: [[panda]] running HAOS
- Primary coordinator: [[home-assistant-connect-zbt-2]]
- Secondary hub: [[aqara-hub-m3]]
- Full device catalog: [[iot-device-inventory]]
- All network clients: [[network-device-census]]
- Operational guide: [[smart-home-handbook]]
## Open Tasks
- [ ] Verify Thread credentials match between ZBT-2 and Aqara Hub M3
- [ ] Commission Aqara Hub M3 into Apple Home via Matter
- [ ] Commission Aqara Hub M3 into Google Home via Matter
- [ ] Commission Aqara Hub M3 into Alexa via Matter
- [ ] Set up HA Matter Bridge for Shelly/Govee/TP-Link/VeSync/LG devices
- [ ] Test multi-admin with Lock U100 across all 4 ecosystems
- [ ] Consider adding Nest Hub for Google Thread BR
- [ ] Evaluate Echo Dot Thread BR capability (gen 5 required)

95
homelab/concepts/media-stack.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: Media Automation Stack
created: 2026-04-28
updated: 2026-05-14
type: concept
tags: [concept, media, services]
sources: [../../homelab/architecture.md]
---
# Media Automation Stack
Full media automation ecosystem spanning ubuntu Docker (~25 containers) and Proxmox LXCs (CT 105–110). VPN-protected downloads, GPU-accelerated transcoding. Undergoing migration from monolithic Docker to individual LXCs (May 2026).
## Download & Index
| Service | URL | Purpose |
|---------|-----|---------|
| Prowlarr | prowlarr.local.tophermayor.com | Indexer management |
| qBittorrent | — | Torrent client (via Gluetun VPN) |
| SABnzbd | sabnzbd.local.tophermayor.com | Usenet downloader |
| Gluetun | — | WireGuard VPN (NordVPN) — all media traffic routes here |
| Flaresolverr | — | CAPTCHA solver for indexers |
| [[decypharr]] | decypharr.local.tophermayor.com | Black hole Usenet indexer (CT 110, 192.168.50.175:8282) |
## Automation
| Service | Purpose |
|---------|---------|
| Sonarr | TV automation |
| Sonarr Anime | Anime TV |
| Radarr | Movie automation |
| Radarr Anime | Anime movies |
| Lidarr | Music automation |
| Bazarr | Subtitle management |
| Recyclarr | Quality profile sync |
| LazyLibrarian | Book automation |
| MusicSeerr | Music request system |
## Media Server
| Service | URL | Purpose |
|---------|-----|---------|
| Jellyfin | jellyfin.tophermayor.com | Media streaming (GPU transcoding) |
| Jellyseerr | jellyseerr.tophermayor.com | Request management |
| Stremio Server | stremio.local.tophermayor.com | Stremio streaming |
## Transcoding
| Service | URL | Purpose |
|---------|-----|---------|
| Tdarr | tdarr.local.tophermayor.com | Media transcoding (GPU via GTX 1080) |
| Analyzarr | — | Media file analysis |
## Book & Audio
| Service | Purpose |
|---------|---------|
| Calibre | eBook management |
| Calibre-Web | eBook reader |
| Kavita | Manga/comic reader |
| Audiobookshelf | Audiobook/podcast server |
| Navidrome | Music streaming |
## VPN Topology
All download clients route through **Gluetun** (WireGuard/NordVPN):
- qBittorrent → Gluetun → Internet
- SABnzbd → Gluetun → Internet
- Prowlarr (indexer checks) → Gluetun → Internet
## LXC Migration (May 2026)
Media services are migrating from monolithic Docker on ubuntu to dedicated Proxmox LXCs:
| LXC | Services | IP |
|-----|----------|-----|
| CT 105 | media-arr (Sonarr, Radarr, Lidarr, etc.) | — |
| CT 106 | media-request (Jellyseerr, Overseerr) | — |
| CT 107 | media-music (Navidrome) | — |
| CT 108 | media-reading (Kavita, Audiobookshelf) | — |
| CT 109 | media-db (PostgreSQL) | — |
| CT 110 | [[decypharr]] (black hole indexer) | 192.168.50.175 |
**Traefik routing update:** All `*arr` service routes now point to LXC IPs instead of `gluetun:container_name` Docker DNS. Dynamic YAML files rewritten during May 14 outage recovery.
**postgres-shared:** Restored on ubuntu Docker for gitea DB after migration (media DBs moved to CT 109).
## Related
- [[jellyfin]] — Media server entity
- [[ubuntu]] — Hosts Docker portion of stack with GTX 1080
- [[proxmox]] — Hosts LXC portion (CT 105–110)
- [[decypharr]] — Black hole indexer (CT 110)
- [[nfs-storage]] — Media stored on TrueNAS NFS
- [[traefik-ha]] — Ingress routing for media services

101
homelab/concepts/monitoring-pipeline.md Normal file
View File

@@ -0,0 +1,101 @@
---
title: Monitoring Pipeline
created: 2026-04-28
updated: 2026-04-29
type: concept
tags: [concept, monitoring, alerting, docker]
sources: [../../homelab/architecture.md]
---
# Monitoring Pipeline
Prometheus-based monitoring with Loki log aggregation, Grafana dashboards, and Telegram alerting via Hermes Gateway watchdog. All monitoring services run on [[ubuntu]].
## Metrics Pipeline
```
Node Exporters (all hosts: ubuntu, grizzley, ice, proxmox, truenas, panda)
→ Prometheus (ubuntu:9090)
→ Grafana (ubuntu:3000)
→ Alertmanager (ubuntu:9093)
→ Hermes Gateway webhook
→ Telegram (@AigentZeroHermes)
```
**Alert routing:**
- Alertmanager receives Prometheus alerts
- Routes to Hermes Gateway webhook (POST to gateway endpoint)
- Gateway sends Telegram to: topic 1033 "Cron Jobs" in AigentZeroHermes (-1003820156994)
- Bot token: `836803270:AAH-Ac5Y`
## Log Pipeline
```
Docker containers (all hosts)
→ Promtail (Docker socket service discovery)
→ Loki (ubuntu:3100)
→ Grafana dashboards
```
Promtail runs as a Docker container on [[ubuntu]], reading container logs via the Docker socket.
## Scrape Targets
Prometheus monitors: ubuntu (local), proxmox, truenas, grizzley, ice, panda.
Scrape endpoints:
- `prometheus` (9090) — Prometheus itself
- `node-exporter` (9100) — host hardware metrics
- `blackbox-exporter` (9115) — HTTP/TCP/ICMP probing
- `cadvisor` (8080) — container metrics
- `loki` (3100) — log metrics
- Traefik instances (8080/metrics)
## Blackbox Exporter Targets
15+ HTTPS probe targets configured. See `homelab/ubuntu/docker/monitoring/` for the blackbox exporter config.
## Alert Rules
Prometheus alert rules → Alertmanager → Hermes Gateway → Telegram.
Key alerts:
- `ContainerLogError` — Container logging errors detected by Promtail
- `ServiceDown` — Blackbox-probed service unavailable
- `JellyfinDown` — Jellyfin health check failed
- `TraefikDown` — Traefik not responding
See [[homelab-servicedown-triage]] and [[homelab-containerlogerror-triage]] skills for triage procedures.
## Hermes Gateway Watchdog
Hermes Gateway is monitored by a watchdog script on both [[ice]] and [[grizzley]]:
```
/home/bear/hermes-gateway-watchdog.sh
```
Runs via **system cron** (not systemd user service) on both hosts:
1. Checks if hermes-gateway is responsive
2. On failure: direct restart → tmux+OpenCode rescue if still down
3. Sends Telegram notification on failure to topic 1033 "Cron Jobs" (bot: `836803270:AAH-Ac5Y`)
**Note:** On [[grizzley]], the systemd override for the watchdog is deployed directly to `/etc/systemd/system/` (not tracked in the homelab repo — it's a system unit).
## External Uptime Monitoring
- **Uptime Kuma** (grizzley:3001) — external/internal availability checks
- **Blackbox Exporter** (ubuntu:9115) — 15+ HTTPS probe targets
## Dashboards
- Grafana (ubuntu:3000) — metrics dashboards
- Loki + Grafana — log exploration
- Prometheus (ubuntu:9090) — expression browser, alertmanager
## Related
- [[ubuntu]] — Hosts Prometheus, Grafana, Loki, Alertmanager
- [[grizzley]] — Hosts Hermes Agent, Telegram webhook, Uptime Kuma
- [[hermes-gateway]] — AI gateway with watchdog pattern
- [[traefik]] — Traefik metrics

193
homelab/concepts/network-device-census.md Normal file
View File

@@ -0,0 +1,193 @@
---
title: Network Device Census
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [iot, smart-home, concept, inventory]
sources: [raw/inventories/unifi-clients-2026-05-10.md, raw/inventories/ha-device-registry-2026-05-10.md, raw/inventories/arp-neighbors-2026-05-10.md]
confidence: high
---
# Network Device Census
> Canonical classification of every device on the network.
> Cross-referenced from UniFi controller (46 clients), HA device registry (61 devices), and ARP tables.
> Updated: 2026-05-10 | Sources: `raw/inventories/unifi-clients-2026-05-10.md`, `raw/inventories/ha-device-registry-2026-05-10.md`
## Classification Key
- **iot-smart-home** — Smart home actuator/sensor/hub managed by [[panda]]
- **iot-appliance** — Smart appliance with HA integration
- **iot-camera** — Security/monitoring camera
- **iot-infra** — Infrastructure device with HA integration
- **infrastructure** — Core network/server hardware (not IoT)
- **personal** — Personal device (phone, laptop, watch, tablet)
- **unidentified** — Unknown device, needs investigation
## VLAN Map
- **VLAN 10** "Family of D." — Personal devices
- **VLAN 20** "Will of D. (Guest)" — Guest network
- **VLAN 30** "Will of D. IoT" — IoT devices + infra with .30 IPs
- **VLAN 50** "Production" — Server infrastructure
- **Default** — Switch management
---
## iot-smart-home (18 devices)
### Hubs & Coordinators
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| homeassistant | 192.168.30.196 | e4:5f:01:5d:ca:06 | 30 | WiFi | HA Core (self) | — | ALL | [[panda]] RPi HAOS host |
| homeassistant | 192.168.30.12 | 98:17:3c:60:45:d8 | 30 | WiFi | — | — | — | Duplicate HA entry? Same hostname, different MAC |
| Aqara-Hub-M3-9C5B | 192.168.30.59 | 18:c2:3c:59:9e:c1 | 30 | WiFi | [[matter]] | Bedroom | Apple, Google, Alexa, HA | [[aqara-hub-m3]] Matter bridge |
| home-assistant-voice-0abc82 | 192.168.30.25 | 20:f8:3b:0a:bc:82 | 30 | WiFi | ESPHome | Office | HA | [[panda]] Voice PE |
### Lighting & Switches
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| shelly1pmg4-a085e3bb2898 | 192.168.30.7 | a0:85:e3:bb:28:98 | 30 | WiFi | Shelly | Bedroom | HA, Alexa | Bedroom ceiling light relay |
| shelly1pmg4-a085e3b7fc74 | 192.168.30.75 | a0:85:e3:b7:fc:74 | 30 | WiFi | Shelly | Office | HA, Alexa | Office ceiling light relay |
| Govee Floor Lamp Left | 192.168.30.91 | 98:17:3c:15:93:38 | 30 | WiFi/BLE | Govee Local | Living Room | HA | H6076 TV backlight #1 |
| Govee Floor Lamp R | 192.168.30.217 | d0:c9:07:f6:5b:ea | 30 | WiFi/BLE | Govee Local | Living Room | HA | H6076 TV backlight #2 |
| (unnamed) | 192.168.30.34 | 98:17:3c:4c:bd:aa | 30 | WiFi/BLE | Govee Local | Living Room | HA | H60A4 shelf/ambient strip |
| (unnamed) | 192.168.30.242 | 98:17:3c:38:8f:e2 | 30 | WiFi/BLE | Govee Local | Bedroom | HA | H60A1 bedroom LED strip |
| HS103 | 192.168.30.116 | 34:60:f9:23:c4:57 | 30 | WiFi | TP-Link | Bedroom | HA, Alexa | Left Lamp plug |
| HS103 | 192.168.30.210 | 34:60:f9:23:c4:b5 | 30 | WiFi | TP-Link | Bedroom | HA, Alexa | Right Lamp plug |
| HS103 | 192.168.30.165 | 34:60:f9:23:c4:88 | 30 | WiFi | TP-Link | Office | HA, Alexa | Grizzley host power (rename!) |
| KP115 | 192.168.30.193 | 00:5f:67:96:47:eb | 30 | WiFi | TP-Link | Living Room | HA, Alexa | Tall Lamp plug |
### Sensors, Locks & Doorbell
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| 09AA01AC171702RL | 192.168.30.179 | 18:b4:30:c2:d2:c0 | 30 | Thread/Matter | [[matter]] | Hall (3rd floor) | HA, Google | Nest Thermostat |
| Camera-Hub-G3-1180 | 192.168.30.113 | 54:ef:44:7a:11:80 | 30 | Zigbee→Matter | [[matter]] | Garage | HA | Aqara Camera Hub G3 |
| Doorbell | 192.168.30.118 | 54:ef:44:8b:c1:da | 30 | Zigbee→Matter | [[matter]] | Entrance | HA | Aqara Video Doorbell G410 |
### Voice Assistants
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| Bedroom Echo | 192.168.30.170 | 7c:d5:66:fe:94:bc | 30 | WiFi | Alexa | Bedroom | Alexa, HA | Echo Dot |
| Kitchen Echo | 192.168.30.26 | 0c:ee:99:09:a7:2f | 30 | WiFi | Alexa | Kitchen | Alexa, HA | Echo Dot |
| Office Echo | 192.168.30.150 | 14:91:38:83:a4:cd | 30 | WiFi | Alexa | Office | Alexa, HA | Echo Dot |
| (unnamed) | 192.168.30.68 | 18:74:2e:d9:d7:28 | 30 | WiFi | Alexa | Living Room | Alexa, HA | 2nd Floor Echo Dot |
### Non-Networked Zigbee/Thread Devices (via [[home-assistant-connect-zbt-2]])
These devices don't appear in UniFi (no IP) but are in HA via ZHA/Matter:
| HA Device | Area | Protocol | Integration | Hub |
|-----------|------|----------|-------------|-----|
| Aqara Light Switch H2 US (Baby Room) | Baby Room | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Light Switch H2 US (Front Door) | Entrance | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Light Switch H2 US (Entrance) | Entrance | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Light Switch H2 US (1st Floor) | — | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Colorful Ceiling Light 36W | Baby Room | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Door and Window Sensor | Rooftop | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Vibration Sensor T1 | Rooftop | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Motion Sensor P1 | Living Room | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| Aqara Smart Lock U100 | Entrance | Zigbee→Matter | [[matter]] via M3 | [[aqara-hub-m3]] |
| IKEA STARKVIND Air Purifier | Office | Zigbee | ZHA | [[home-assistant-connect-zbt-2]] |
---
## iot-appliance (2 devices)
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| Levoit-purifier | 192.168.30.21 | cc:ba:97:b7:3d:0c | 30 | WiFi | VeSync | Kitchen | HA | Vital 200S air purifier |
| eufyOmniC20 | 192.168.30.50 | 4c:37:de:56:41:1b | 30 | WiFi | — | — | — | Eufy robot vacuum, no HA integration yet |
---
## iot-camera (3 devices)
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| eufy_Baby_Camera | 192.168.10.110 | 90:bf:d9:ce:8c:e0 | 10 | WiFi | — | — | — | Eufy baby cam on Family VLAN |
| eufy_Baby_Camera | 192.168.10.113 | 90:bf:d9:84:a1:48 | 10 | WiFi | — | — | — | Second Eufy baby cam |
| eufy_Baby_Monitor | 192.168.10.120 | 90:bf:d9:55:63:de | 10 | WiFi | — | — | — | Eufy baby monitor hub |
---
## iot-infra (5 devices)
| Hostname | IP | MAC | VLAN | Protocol | HA Integration | Area | Ecosystems | Notes |
|----------|-----|-----|------|----------|---------------|------|------------|-------|
| Office | 192.168.30.234 | c4:f7:c1:2b:fc:89 | 30 | WiFi | Apple TV | Office | Apple Home, HA | Apple TV 4K gen 3 — Matter controller |
| LGwebOSTV | 192.168.30.79 | 60:45:e8:7f:c2:1a | 30 | WiFi | webOS TV | Living Room | HA, Alexa, AirPlay | LG OLED65C5AUA |
| Rest2ndGen-62CEEE | 192.168.30.177 | ec:e3:34:62:ce:ec | 30 | WiFi | — | — | — | Withings Sleep mat, possible HA integration |
| sky0008606C | 192.168.30.161 | 60:8a:10:e6:86:6c | 30 | WiFi | — | — | — | Somfy / blinds device? Microchip OUI |
| (unnamed iPhone) | 192.168.20.190 | 00:22:f2:06:60:b3 | 20 | WiFi | — | — | — | SunPower OUI — solar panel monitor? |
---
## infrastructure (6 devices)
| Hostname | IP | MAC | VLAN | Protocol | Role | Notes |
|----------|-----|-----|------|----------|------|-------|
| grizzley | 192.168.30.84 | 2c:cf:67:38:8b:c8 | 30 | Wired | Edge ingress RPi5 | Also .50.84 on Production VLAN |
| ubuntu | 192.168.30.61 | bc:24:11:16:a9:e2 | 30 | Wired | Primary Docker host | Also .50.61 on Production VLAN |
| Ice | 192.168.30.197 | e4:5f:01:29:cb:c5 | 30 | Wired | Control plane RPi4 | Also .50.197 on Production VLAN |
| Truenas Virtual NIC | 192.168.50.12 | bc:24:11:32:a5:82 | 50 | Wired | TrueNAS NAS | [[truenas]] on Proxmox |
| truenas | 192.168.50.11 | 3c:7c:3f:23:5c:c5 | 30 | Wired | TrueNAS physical | Also .50.12 virtual |
| TL-SG108PE | 192.168.1.92 | 34:60:f9:2e:bc:bf | — | Wired | TP-Link managed switch | 8-port PoE, IoT VLAN trunk |
---
## personal (7 devices)
| Hostname | IP | MAC | VLAN | Connection | OUI | Notes |
|----------|-----|-----|------|------------|-----|-------|
| iPhone | 192.168.10.151 | 22:b7:b2:b4:88:ab | 10 | WiFi | — | TophPhone14 (HA mobile app) |
| iPhone | 192.168.10.158 | 22:0a:9d:c7:ea:1a | 10 | WiFi | — | Second iPhone |
| iPhone | 192.168.10.133 | d2:46:b3:46:4c:84 | 10 | WiFi | — | Third iPhone (private Wi-Fi MAC) |
| iPad | 192.168.10.116 | 3a:a3:c7:47:df:de | 10 | WiFi | — | Family iPad |
| Watch | 192.168.10.150 | ca:df:bd:1b:75:7e | 10 | WiFi | — | Apple Watch |
| Mac | 192.168.10.125 | 76:4f:65:d6:e2:1a | 10 | WiFi | — | MacBook |
| ice | 192.168.10.178 | e4:5f:01:29:cb:c7 | 10 | WiFi | RPi | Ice on Family VLAN (WiFi) |
---
## unidentified (3 devices)
| Hostname | IP | MAC | VLAN | Connection | OUI | Notes |
|----------|-----|-----|------|------------|-----|-------|
| HYTERevolt | 192.168.1.143 | 74:56:3c:ba:a9:6d | — | Wired | Giga-Byte | Gaming PC? On Default VLAN |
| VectorPro | 192.168.1.77 | b0:25:aa:48:53:5a | — | Wired | Private | Unknown wired device, Default VLAN |
| Caesar's Aivo Connect | — | — | — | WiFi | Alexa | iottie car mount, Alexa integration only |
---
## Statistics
| Classification | Count | % of Network |
|---------------|-------|-------------|
| iot-smart-home | 18+10 non-net | 39% |
| iot-appliance | 2 | 4% |
| iot-camera | 3 | 7% |
| iot-infra | 5 | 11% |
| infrastructure | 6 | 13% |
| personal | 7 | 15% |
| unidentified | 3 | 7% |
## Open Questions
- ~~**98:17:3c:60:45:d8** — Likely a TrueNAS IP, not HA. Confirmed panda is only at .30.196. Stale DHCP lease or old reservation.~~ ✅ Resolved 2026-05-10
- **sky0008606C** — AMWAY smart air filter (Microchip Technology OUI, .30.161). Not in HA — consider adding integration if available.
- **00:22:f2:06:60:b3** — Solar panel monitor (SunPower OUI) on Guest VLAN 20. Verify if this should be on IoT VLAN 30 or if Guest is intentional for internet-only reporting.
- **3 Eufy baby cameras** on VLAN 10 (Family) — intentional for phone accessibility. Correct placement; VLAN 30 would require firewall rules for VLAN 10→30 Eufy traffic.
- **Aqara Light Switch H2 US** — 5 switches confirmed: 1st Floor (1), 2nd Floor (2), 3rd Floor (2: Baby Room + Hallway Area). Two via_device paths suggest some are paired via ZHA and some via Aqara Hub M3 Matter bridge.
## Related Pages
- [[iot-device-inventory]] — IoT-only view grouped by room
- [[matter-multi-fabric]] — Matter fabric membership and hub-to-device mapping
- [[smart-home-handbook]] — Operational handbook
- [[home-assistant-connect-zbt-2]] — Zigbee/Thread coordinator details
- [[aqara-hub-m3]] — Aqara Matter hub details

66
homelab/concepts/nfs-storage.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: NFS Storage Strategy
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, storage, nas]
sources: [../../homelab/architecture.md, ../../ai-assistant/workflows.md]
---
# NFS Storage Strategy
TrueNAS NFS shares are used for user-uploaded data and media. Configs and databases stay on local VM disk.
## Storage Hierarchy
```
TrueNAS (192.168.50.12)
├── ZFS Pool "TrueNAS" (25.4TB, 65% used)
│ ├── /mnt/truenas/mediadata/ ← Movies, TV, Music
│ ├── /mnt/truenas/traefik-certs/ ← TLS certificates (NFS to grizzley)
│ └── /mnt/truenas-backup/ ← Application backups
└── ZFS Pool "RPiPool" (10.9TB, 5% used)
└── /mnt/rpipooldata/ ← Reserve storage
PersonalMediaLibrary (separate NFS)
└── /mnt/PersonalMediaLibrary/ ← Immich external library (photos)
```
## Mount Rules
| Data Type | Storage Location | Example |
|-----------|-----------------|---------|
| User uploads (photos, media) | NFS (TrueNAS) | Immich photos, Jellyfin library |
| App configs | VM local disk | docker-compose.yml, config/ |
| Databases | VM local (postgres-shared) | PostgreSQL, Redis |
| Media library | NFS (TrueNAS) | Movies, TV, Music |
| Backups | NFS (TrueNAS) | Application backups |
| TLS certificates | NFS (TrueNAS) | Wildcard certs synced to grizzley |
## NFS Exports
| Export | Mounted On | Consumer |
|--------|-----------|---------|
| `/mnt/truenas/mediadata` | `/mnt/truenas/mediadata` on ubuntu | Jellyfin, *Arrs, Immich uploads |
| `/mnt/PersonalMediaLibrary` | `/mnt/PersonalMediaLibrary` on ubuntu | Immich external library |
| `/mnt/truenas/traefik-certs/grizzley` | NFS on grizzley | Traefik TLS certificates |
## NFS Mount Checklist
Before using an NFS path in docker-compose, verify it exists in `/etc/fstab`:
```bash
cat /etc/fstab | grep nfs
```
## Known Issues
- **Pool corruption** — TrueNAS pool has known corruption issues (as of 2026-04-28). Monitor `truenas` entity page.
- **rustfs ignores env vars** — S3 object storage ignores environment variables on first boot. See [[rustfs]].
## Related
- [[truenas]] — TrueNAS NAS entity
- [[ubuntu]] — Ubuntu host with NFS mounts
- [[jellyfin]] — Media server using NFS
- [[vm-storage-policy]] — VM Storage Policy with full mount rules

73
homelab/concepts/opencode-cluster.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: OpenCode Cluster
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, ai, services]
sources: [../../homelab/docs/opencode-cluster.md, ../../ai-assistant/host-context.md]
---
# OpenCode Cluster
OpenCode AI coding assistant deployed as systemd services across the homelab cluster, accessible via Traefik-routed HTTPS endpoints.
## Instances
| Instance | Host | IP | Port | Traefik Route | Status |
|----------|------|-----|------|---------------|--------|
| ubuntu | Ubuntu VM | 192.168.50.61 | 4096 | opencode.tophermayor.com | Active/Enabled |
| ice | Raspberry Pi 4 | 192.168.50.197 | 4096 | opencode-ice.tophermayor.com | Active/Enabled |
| grizzley | Raspberry Pi 5 | 192.168.50.84 | 4096 | — | Inactive/Disabled |
## Service Management
All instances run as `opencode-web.service` via systemd:
```bash
# Check status
systemctl status opencode-web
# Restart
sudo systemctl restart opencode-web
# View logs
journalctl -u opencode-web -f
```
## Shared Infrastructure
- **Qdrant** (192.168.50.61:6333) — Shared vector memory backend for OpenCode cluster
- **Ollama** (192.168.50.61:11434) — Local embedding generation
## Configuration
Per-host config files in `homelab/<host>/opencode/`:
- `opencode.json` — Main OpenCode configuration
- `oh-my-opencode.json` — Framework configuration
## Traefik Routing
OpenCode instances use dedicated Traefik middlewares:
- `local-only@file` — IP whitelist
- `opencode-streaming@file` — SSE support
- `opencode-cors@file` — CORS headers
## Agent Context Detection
Each OpenCode instance detects its host context via:
- `.opencode/opencode.json` init file
- Environment variables (`HOST_CONTEXT`, `WIKI_PATH`)
- `detect_host_context.py` script
See [[host-context-detection]] for full detection table.
## Wiki Integration
All OpenCode instances have `WIKI_PATH=/home/bear/homelabagentroot/obsidian-vault` in their environment, enabling them to read and write to the shared wiki.
## Related
- [[ice]] — RPi4 control plane running OpenCode
- [[ubuntu]] — Primary host running OpenCode
- [[host-context-detection]] — Per-host agent detection
- [[vm-storage-policy]] — AI assistant workflows

108
homelab/concepts/smart-home-handbook.md Normal file
View File

@@ -0,0 +1,108 @@
---
title: Smart Home Handbook
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [smart-home, iot, home-assistant, matter, concept, runbook]
confidence: high
---
# Smart Home Handbook
> Operational overview for the homelab smart home. Canonical orientation page linking to all smart home entities and concepts.
## Architecture Summary
The smart home is built around **Home Assistant** on [[panda]] as the central automation hub, with Matter multi-fabric providing cross-ecosystem access to devices.
```
┌─────────────────────────────────────────────────────┐
│ USER INTERFACES │
│ HA UI │ Apple Home │ Google Home │ Alexa │ Voice │
├─────────────────────────────────────────────────────┤
│ HOME ASSISTANT (panda) │
│ Automations │ Scripts │ Scenes │ Dashboards │
├──────────┬──────────┬──────────┬──────────┬─────────┤
│ ZHA │ Matter │ Cloud │ Local │ ESPHome │
│ Zigbee │ Thread │ APIs │ LAN │ BLE/Voice│
├──────────┴──────────┴──────────┴──────────┴─────────┤
│ DEVICES (~35) │
│ Aqara │ Govee │ Shelly │ TP-Link │ IKEA │ Echo │
│ Apple TV │ LG TV │ Nest │ VeSync │ Aivo │
└─────────────────────────────────────────────────────┘
```
## Key Entities
| Entity | Role | Page |
|--------|------|------|
| [[panda]] | HA host (RPi, HAOS) | [[panda]] |
| [[home-assistant-connect-zbt-2]] | Zigbee + Thread coordinator | [[home-assistant-connect-zbt-2]] |
| [[aqara-hub-m3]] | Aqara Matter bridge + Zigbee hub | [[aqara-hub-m3]] |
## Key Concepts
| Concept | Description | Page |
|---------|-------------|------|
| Matter Multi-Fabric | Cross-ecosystem device sharing | [[matter-multi-fabric]] |
| IoT Device Inventory | Complete device catalog | [[iot-device-inventory]] |
## Quick Reference
### Accessing Home Assistant
- **Web UI**: `https://ha.tophermayor.com`
- **SSH**: `ssh bear@192.168.30.196` (password auth)
- **API**: `http://192.168.30.196:8123/api/` (requires bearer token)
- **Traefik**: Routed from both [[ubuntu]] and [[grizzley]]
### Adding a New Matter Device
1. Open HA → Settings → Devices & Services → Matter → Add Device
2. Follow pairing flow using QR code or numeric code
3. Once in HA, use multi-admin pairing code to add to Apple/Google/Alexa
4. See [[matter-multi-fabric]] for full commissioning flow
### Adding a Non-Matter Device
1. Add to HA via native integration (Zigbee, Wi-Fi, cloud)
2. If needed in other ecosystems, enable HA Matter Bridge
3. Commission the bridge into target ecosystem
4. See [[matter-multi-fabric]] → Non-Matter Devices section
### Troubleshooting
| Problem | Solution |
|---------|----------|
| Device not responding | Check VLAN 30 connectivity, verify device power |
| Zigbee device offline | Check ZHA → Settings → Network → visualization for mesh health |
| Thread device not connecting | Verify Thread credentials match across all border routers |
| HA SSH access denied | Add SSH key to Advanced SSH add-on config via HA web UI |
| Matter multi-admin fails | Check device's fabric limit (some only support 2-3) |
| Govee lights won't pair | Ensure on same VLAN 30, use govee_light_local integration |
### Voice Pipeline
```
openWakeWord → Whisper (STT) → HA Assist (intent) → Piper (TTS)
```
- **Wake word**: "Hey Jarvis" (configurable via openWakeWord)
- **Hardware**: Home Assistant Voice PE (ESPHome)
- **Fallback**: Echo Dots → Alexa, Apple TV → Siri
### Network Placement
All IoT devices sit on **VLAN 30 (IoT subnet 192.168.30.0/24)**:
- [[panda]] has dual-homed: 192.168.30.196 (IoT) + 192.168.50.196 (Servers)
- Physical path: UGC Ultra Port 2 → TP-Link SG108PE trunk
- Firewall: IoT VLAN is isolated from Server and Family VLANs
- Management: Access HA via Traefik reverse proxy from any VLAN
## Improvement Opportunities
- [ ] Add grizzley SSH key to panda's SSH add-on for agent automation
- [ ] Verify unified Thread credentials across all border routers
- [ ] Set up HA Matter Bridge to expose non-Matter devices to Apple/Google/Alexa
- [ ] Commission Aqara Hub M3 into Apple Home and Google Home fabrics
- [ ] Consider ESP32 Bluetooth proxies for improved BLE coverage
- [ ] Evaluate moving panda's primary IP to VLAN 50 for easier management
- [ ] Add Nest Hub as Google Thread Border Router
- [ ] Document automations and scenes in a dedicated wiki page

74
homelab/concepts/smart-home.md Normal file
View File

@@ -0,0 +1,74 @@
---
title: Smart Home
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [smart-home, iot, concept, home-assistant, matter, moc]
aliases: [IoT, Smart Home, Home Automation]
confidence: high
---
# 🏠 Smart Home
> Start here for everything smart home. All IoT devices, ecosystems, and automation documentation linked from this page.
## Architecture at a Glance
- **Central hub**: [[panda]] running Home Assistant OS (RPi, IoT VLAN 30)
- **Zigbee/Thread coordinator**: [[home-assistant-connect-zbt-2]] (Connect ZBT-2 dongle)
- **Matter bridge**: [[aqara-hub-m3]] (bridges Zigbee devices to Apple/Google/Alexa)
- **Voice pipeline**: Whisper (STT) → Piper (TTS) → openWakeWord on [[panda]]
- **38 IoT devices** across 12 rooms, 3 floors
## Quick Navigation
### 📋 Inventories
- **[[network-device-census]]** — Every device on the network, classified
- **[[iot-device-inventory]]** — IoT devices by room with protocol details
- **[[device-placement-policy]]** — Which VLAN each device class belongs on
### 🔗 Ecosystems
- **[[matter-multi-fabric]]** — How devices are shared across HA / Apple / Google / Alexa
- **[[smart-home-handbook]]** — Operational guide (access, troubleshooting, improvements)
### 🖥️ Hardware
- **[[panda]]** — HA host (RPi, HAOS, dual-homed)
- **[[home-assistant-connect-zbt-2]]** — Zigbee + Thread coordinator
- **[[aqara-hub-m3]]** — Aqara Matter hub/bridge
## Ecosystem Controllers
| Ecosystem | Controller | Location | Protocol |
|-----------|-----------|----------|----------|
| Home Assistant | [[panda]] + Connect ZBT-2 | Office | Matter/Thread/Zigbee |
| Apple Home | Apple TV 4K gen 3 | Office | Matter |
| Google Home | Nest Thermostat | Hall (3rd) | WiFi/Matter |
| Amazon Alexa | 4× Echo Dot | Office/Kitchen/Bedroom/Garage | Matter |
## Devices by Floor
### 1st Floor (Office, Entrance, Garage)
- Apple TV 4K, Office Echo, Shelly 1PM (office light)
- Aqara Lock U100, Doorbell G410, Light Switches (×2)
- Camera Hub G3, Garage Echo
### 2nd Floor (Living Room, Kitchen, Dining)
- LG OLED TV, Kitchen Echo, KP115 (tall lamp)
- Aqara Motion Sensor P1, IKEA STARKVIND purifier
- Govee lights (×3), Levoit Vital 200S purifier
### 3rd Floor (Bedroom, Baby Room, Hall, Laundry)
- Aqara Hub M3, Bedroom Echo, Shelly 1PM (bedroom light)
- Aqara Light Switches (Baby Room + Hallway)
- Aqara Ceiling Light 36W, Govee LED strip
- Nest Thermostat, HA Voice PE
### Rooftop
- Aqara Door/Window Sensor, Aqara Vibration Sensor T1
## Open Tasks
- [ ] Commission Aqara Hub M3 into Apple Home
- [ ] Commission Aqara Hub M3 into Google Home
- [ ] Commission Aqara Hub M3 into Alexa
- [ ] Set up HA Matter Bridge for WiFi devices
- [ ] Verify Thread credentials match across all border routers

62
homelab/concepts/sso-authentik.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: SSO with Authentik
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, sso, services]
sources: [../../homelab/architecture.md, ../../platform-config/overview.md]
---
# SSO with Authentik
Authentik provides SSO identity provider for the homelab via OAuth2/OIDC. Traefik middleware enforces authentication on internal services.
## Architecture
```
User → Service (protected by authentik-auth middleware)
↓
Traefik middleware
↓
Authentik Server (ubuntu)
auth.tophermayor.com
↓
OAuth2/OIDC flow
↓
Redirect with token
```
## Services Using SSO
| Service | URL | SSO Method |
|---------|-----|-----------|
| Authentik | auth.tophermayor.com | Direct |
| Jellyfin | jellyfin.tophermayor.com | Authentik OAuth2 |
| Immich | immich.tophermayor.com | Authentik OAuth2 |
| Traefik Dashboard | traefik.local.tophermayor.com | local-only middleware |
## Authentik Components
| Component | Description |
|-----------|-------------|
| Authentik Server | Main SSO application (ubuntu) |
| Authentik Worker | Background task processing |
| Authentik Redis | Session caching |
## Database
Authentik uses the `postgres-shared` PostgreSQL instance on ubuntu (`authentik` database).
## Traefik Middleware
```
authentik-auth@file
```
Applied to services that need SSO. Users are redirected to Authentik login, then back with a valid session cookie.
## Related
- [[authentik]] — Authentik entity page
- [[ubuntu]] — Hosts Authentik server
- [[docker-traefik-stack]] — Docker, Traefik, and container orchestration

110
homelab/concepts/subscriptions.md Normal file
View File

@@ -0,0 +1,110 @@
---
title: Subscriptions & Paid Services
created: 2026-05-24
updated: 2026-05-24
type: concept
tags: [services, infrastructure, billing]
confidence: high
---
# Subscriptions & Paid Services
## Overview
Comprehensive catalog of all paid subscriptions — both self-hosted services (infrastructure Chris pays for) and external SaaS/cloud services.
---
## External Subscriptions (Paid Services)
### Cloud Infrastructure
| Service | Cost | Purpose | Payment Method |
|---------|------|---------|----------------|
| **Cloudflare** | ~$20/mo | DNS + proxy + TLS certs for `*.tophermayor.com` | Credit card |
| **Backblaze B2** | ~$7/mo | Off-site backup storage (Cold tier, ~2TB) | Credit card |
### VPN
| Service | Cost | Purpose | Payment Method |
|---------|------|---------|----------------|
| **NordVPN** | ~$12/mo | WireGuard tunnel for media stack downloads | Credit card |
### Development Tools
| Service | Cost | Purpose | Payment Method |
|---------|------|---------|----------------|
| **GitHub** | ~$4/mo | Private repos (copilot, actions) | GitHub billing |
| **Obsidian Sync** | ~$8/mo | Vault sync across devices | Obsidian account |
### Historical / Retired
| Service | Cost | Purpose | Status |
|---------|------|---------|--------|
| **Tailnet (Tailscale)** | ~$5/mo/person | VPN mesh for outside players to reach Bedrock servers | Active for Bedrock sharing only |
| **Backblaze Personal** | — | Decommissioned — B2 replaced this | Retired |
| **Google Workspace** | — | Decommissioned — moved to self-hosted | Retired |
---
## Self-Hosted Services (Infrastructure You Pay For)
These are services Chris runs on homelab hardware. The "cost" is the hardware + power + internet, not a subscription fee.
### Primary Infrastructure Hosts
| Host | Hardware | Cost Basis | Role |
|------|----------|-----------|------|
| **ubuntu** (Proxmox VM) | Intel NUC or similar | Power + hardware amortized | ~70 containers: Traefik, media stack, Gitea, monitoring |
| **grizzley** | Raspberry Pi 5 | ~$150 one-time + power | Edge ingress, Traefik ACME, Minecraft Bedrock, Hermes |
| **ice** | Raspberry Pi 4 | ~$100 one-time + power | OpenCode control node, Hermes gateway |
| **pve** (Proxmox) | Bare metal | ~$800 one-time + power | Hypervisor for ubuntu VM + TrueNAS VM |
| **truenas** | TrueNAS SCALE VM | Runs on pve | 36TB raw storage (ZFS), NFS exports |
### Self-Hosted Services (No Subscription Fee)
All of these run on homelab hardware — no per-service license fee:
| Service | Host | URL | Purpose |
|---------|------|-----|---------|
| **Traefik** | ubuntu + grizzley | `traefik.local.tophermayor.com` | Reverse proxy / ingress |
| **Authentik** | ubuntu | `auth.tophermayor.com` | SSO identity provider |
| **Gitea** | ubuntu | `gitea.tophermayor.com` | Private Git server |
| **Jellyfin** | grizzley | `jellyfin.tophermayor.com` | Media streaming |
| **Immich** | ubuntu | `immich.tophermayor.com` | Photo/video backup |
| **Sonarr/Radarr/Lidarr** | ubuntu | `sonarr.local.tophermayor.com` etc. | Media automation |
| **Prometheus + Grafana** | ubuntu | `grafana.local.tophermayor.com` | Monitoring |
| **Home Assistant** | panda | `ha.tophermayor.com` | Smart home hub |
| **Vaultwarden** | grizzley | `vaultwarden.tophermayor.com` | Password manager |
| **OpenCode** | ice + ubuntu | `opencode.tophermayor.com` | AI coding assistant |
| **Hermes Agent** | grizzley + ice | Port 8644 | Telegram AI agent |
| **Navidrome** | ubuntu | — | Music streaming |
| **Kavita** | ubuntu | — | Ebook/comic reader |
| **Audiobookshelf** | ubuntu | — | Audiobook/podcast server |
| **Tdarr** | ubuntu | `tdarr.local.tophermayor.com` | Media transcoding |
| **Komodo** | grizzley | `komodo.local.tophermayor.com` | Container management |
| **Uptime Kuma** | grizzley | — | Uptime monitoring |
| **Minecraft Bedrock** | grizzley | — | Game server |
---
## Cost Summary
| Category | Monthly Cost |
|----------|-------------|
| Cloud services (Cloudflare + Backblaze) | ~$27/mo |
| VPN (NordVPN) | ~$12/mo |
| Developer tools (GitHub + Obsidian) | ~$12/mo |
| Hardware (amortized over 3 years) | ~$30/mo |
| **Total** | **~$81/mo** |
---
## Related
- [[ubuntu]] — primary Docker host running most services
- [[grizzley]] — edge ingress node
- [[ice]] — OpenCode control node
- [[truenas]] — storage with B2 backup tier
- [[media-stack]] — media automation services
- [[monitoring-pipeline]] — alerting and observability

108
homelab/concepts/traefik-ha.md Normal file
View File

@@ -0,0 +1,108 @@
---
title: Traefik High Availability
created: 2026-04-28
updated: 2026-05-14
type: concept
tags: [concept, networking, services]
sources: [../../homelab/architecture.md, ../../platform-config/overview.md]
---
# Traefik High Availability
Two Traefik v3.6.7 instances provide ingress — one on ubuntu (primary router), one on grizzley (edge ACME). Certificates are synced via NFS.
## Architecture
```
Internet → Cloudflare DNS → *.tophermayor.com
↓
┌────────────────┴────────────────┐
↓ ↓
grizzley Traefik ubuntu Traefik
(edge ACME) (primary router)
192.168.50.84 192.168.50.61
│ │
│ TLS certs on NFS │
└──────────→ /mnt/truenas/traefik-certs/grizzley ←─┘
```
## Roles
| Instance | Host | Primary Role |
|----------|------|-------------|
| Traefik Pi | grizzley (192.168.50.84) | Edge ACME — generates wildcard certs via Cloudflare DNS challenge |
| Traefik (ubuntu) | ubuntu (192.168.50.61) | Primary router — handles ~90% of traffic, syncs certs from grizzley |
## Certificate Flow
1. Grizzley Traefik runs Cloudflare DNS challenge, writes certs to NFS mount `/mnt/truenas/traefik-certs/grizzley`
2. Ubuntu Traefik references same certs via NFS share
3. Both instances serve the same wildcard `*.tophermayor.com` cert
## Dynamic Config Files
Located in `homelab/ubuntu/traefik/config/dynamic/`:
| File | Services |
|------|----------|
| `canonical-hosts.yml` | Grizzley ingress proxy, PVE OpenCode |
| `gitea.yml` | gitea.tophermayor.com |
| `immich.yml` | immich.tophermayor.com |
| `jellyfin.yml` | jellyfin.tophermayor.com |
| `media-stack.yml` | Sonarr, Radarr, SABnzbd, Prowlarr, qBittorrent |
| `middlewares.yml` | 30+ middleware definitions |
| `opencode.yml` | opencode.tophermayor.com |
| `proxmox.yml` | proxmox.local.tophermayor.com |
| `homepage-widgets.yml` | Homepage service definitions |
| `audiobookshelf.yml` | Audiobookshelf (CT 108) |
| `jellyseerr.yml` | Jellyseerr (CT 106) |
| `kavita.yml` | Kavita (CT 108) |
| `navidrome.yml` | Navidrome (CT 107) |
| `stremio.yml` | Stremio Server |
## Common Middlewares
| Middleware | Purpose |
|------------|---------|
| `local-only@file` | Restrict to local network IPs |
| `authentik-auth@file` | SSO authentication |
| `security-headers@file` | Add security headers |
| `crowdsec-bouncer@file` | Rate limiting and threat protection |
## Entry Points
- `web` — port 80, HTTP → HTTPS redirect
- `websecure` — port 443, TLS termination
- `metrics` — port 8080, Prometheus metrics
## Outage Postmortem: 2026-05-14
**Severity:** Complete file provider failure — all `@file` routers and dependent `@docker` routers offline.
**Root Cause:** Media migration wrote 7 YAML dynamic config files with mangled backtick quoting, causing Traefik's file provider to fail parsing entirely.
**Affected Files:**
- `homepage-widgets.yml`
- `audiobookshelf.yml`
- `jellyseerr.yml`
- `kavita.yml`
- `navidrome.yml`
- `stremio.yml`
- `media-stack.yml`
**Impact:**
- ALL `@file` routers down (no traffic routed to static-defined services)
- ALL `@docker` routers depending on `local-only@file` middleware also failed
- Homepage, media services, and any service using file-defined middlewares unreachable
**Fix:** Rewrote all 7 YAML files with correct quoting. Renamed conflicting service names in `homepage-widgets.yml` that were colliding with other provider definitions.
**Lesson:** Traefik file provider is all-or-nothing — one broken YAML file crashes the entire provider, taking down all file-defined routers and middlewares (even unrelated ones). Validate YAML before deploying.
## Related
- [[traefik]] — Traefik entity page
- [[grizzley]] — RPi5 edge node running edge Traefik
- [[ubuntu]] — Primary Docker host running primary Traefik
- [[truenas]] — NFS storage for cert sync
- [[docker-traefik-stack]] — Docker, Traefik, and container orchestration

60
homelab/concepts/vm-storage-policy.md Normal file
View File

@@ -0,0 +1,60 @@
---
title: VM Storage Policy
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, storage, ubuntu, homelab]
confidence: high
---
# VM Storage Policy
Storage rules for application data on the Ubuntu host (192.168.50.61). All agents and developers managing services on Ubuntu MUST follow these rules.
## Rule 1: User-Uploaded Data on NFS
Store ALL user-uploaded data on TrueNAS NFS shares, NOT on the VM's local disk.
**Allowed NFS Paths:**
- `/mnt/PersonalMediaLibrary/` — Personal media, photos (Immich)
- `/mnt/truenas/mediadata/` — Media library (Movies, TV, Music)
- `/mnt/truenas-backup/` — Backups
**Examples:**
```yaml
volumes:
- /mnt/PersonalMediaLibrary/immich/upload:/usr/src/app/upload
- /mnt/truenas/mediadata/media:/media
```
## Rule 2: Config Files on VM
Configuration files, databases, and cached data CAN stay on VM local disk.
**Allowed Local Paths:**
- `/home/bear/homelab/ubuntu/{service}/` — Docker compose and config
- `./config`, `./cache` (relative to docker-compose) — Config/cache directories
## Rule 3: NFS Mounts Must Be in fstab
Before using an NFS path in docker-compose, verify it exists in `/etc/fstab` for persistence.
```bash
cat /etc/fstab | grep nfs
```
## Summary
| Data Type | Storage Location | Example |
|-----------|-----------------|---------|
| User uploads | NFS (TrueNAS) | Photos, media |
| App config | VM local | docker-compose.yml, config/ |
| Databases | VM local (postgres-shared) | PostgreSQL, Redis |
| Media library | NFS (TrueNAS) | Movies, TV, Music |
| Backups | NFS (TrueNAS) | Application backups |
## Related
- [[nfs-storage|NFS Storage]] — TrueNAS NFS mount strategy
- [[truenas|TrueNAS]] — network-attached storage host
- [[ubuntu|ubuntu]] — primary Docker host