# n8n Homelab Integrations - Quick Start Guide

n8n is running on your homelab network (10.10.10.207) and can access all local services. This guide sets up useful automations.

---

## Network Access Verified

n8n can connect to:
- ✅ **Home Assistant** (10.10.10.110:8123)
- ✅ **Prometheus** (10.10.10.206:9090)
- ✅ **Grafana** (10.10.10.206:3001)
- ✅ **Syncthing** (10.10.10.200:8384)
- ✅ **PiHole** (10.10.10.10)
- ✅ **Gitea** (10.10.10.220:3000)
- ✅ **Proxmox** (10.10.10.120:8006, 10.10.10.102:8006)
- ✅ **TrueNAS** (10.10.10.200)
- ✅ **All external APIs** (via internet)

---

## Initial Setup (First-Time)

1. Open **https://n8n.htsn.io**
2. Complete the setup wizard:
   - **Owner Email:** hutson@htsn.io
   - **Owner Name:** Hutson
   - **Password:** (choose secure password)
3. Skip data sharing (optional)

---

## Credentials to Add in n8n

Go to **Settings → Credentials** and add:

### 1. Home Assistant

| Field | Value |
|-------|-------|
| **Credential Type** | Home Assistant API |
| **Host** | `http://10.10.10.110:8123` |
| **Access Token** | (get from Home Assistant) |

**Get Token:** Home Assistant → Profile → Long-Lived Access Tokens → Create Token

---

### 2. Prometheus

| Field | Value |
|-------|-------|
| **Credential Type** | HTTP Request (Generic) |
| **URL** | `http://10.10.10.206:9090` |
| **Authentication** | None |

---

### 3. Grafana

| Field | Value |
|-------|-------|
| **Credential Type** | Grafana API |
| **URL** | `http://10.10.10.206:3001` |
| **API Key** | (create in Grafana) |

**Get API Key:** Grafana → Administration → Service Accounts → Create → Add Token

---

### 4. Syncthing

| Field | Value |
|-------|-------|
| **Credential Type** | HTTP Request (Generic) |
| **URL** | `http://10.10.10.200:8384` |
| **Header Name** | `X-API-Key` |
| **Header Value** | `VFJ7XZPJoWvkYj6fKzpQxc9u3XC8KUBs` |

---

### 5. Telegram Bot

| Field | Value |
|-------|-------|
| **Credential Type** | Telegram API |
| **Access Token** | `8450212653:AAHoVBlNUuA0vtrVPMNUfSgJh_gmFMxlrBg` |

**Your Chat ID:** `1004084736`

---

### 6. Proxmox

| Field | Value |
|-------|-------|
| **Credential Type** | HTTP Request (Generic) |
| **URL** | `http://10.10.10.120:8006` |
| **Authentication** | API Token |
| **Token** | (use monitoring@pve token if needed) |

---

## Starter Workflows

### Workflow 1: Homelab Health Check (Every Hour)

**Nodes:**
1. **Schedule Trigger** (every hour)
2. **HTTP Request** → Prometheus query for down hosts
   - URL: `http://10.10.10.206:9090/api/v1/query`
   - Query param: `query=up{job=~"node.*"} == 0`
3. **If** → Check if any hosts are down
4. **Telegram** → Send alert if hosts down

**PromQL Query:**
```
up{job=~"node.*"} == 0
```

---

### Workflow 2: Daily Backup Status

**Nodes:**
1. **Schedule Trigger** (8am daily)
2. **HTTP Request** → Query Syncthing sync status
   - URL: `http://10.10.10.200:8384/rest/db/status?folder=backup`
   - Header: `X-API-Key: VFJ7XZPJoWvkYj6fKzpQxc9u3XC8KUBs`
3. **Function** → Check if folder is syncing
4. **Telegram** → Send daily status report

---

### Workflow 3: High CPU Alert

**Nodes:**
1. **Schedule Trigger** (every 5 minutes)
2. **HTTP Request** → Prometheus CPU query
   - URL: `http://10.10.10.206:9090/api/v1/query`
   - Query: `100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)`
3. **If** → CPU > 90%
4. **Telegram** → Send alert

---

### Workflow 4: UPS Power Event

**Webhook Trigger Setup:**
1. Create webhook trigger in n8n
2. Get webhook URL: `https://n8n.htsn.io/webhook/ups-alert`
3. Configure NUT to call webhook on power events

**Nodes:**
1. **Webhook Trigger** → Receive UPS event
2. **Switch** → Route by event type (on battery, low battery, online)
3. **Telegram** → Send appropriate alert

---

### Workflow 5: Gitea → Deploy on Push

**Nodes:**
1. **Webhook Trigger** → Gitea push event
2. **If** → Check if branch is `main`
3. **SSH** → Connect to target server
4. **Execute Command** → `git pull && docker-compose up -d`
5. **Telegram** → Notify deployment complete

---

### Workflow 6: Syncthing Folder Behind Alert

**Nodes:**
1. **Schedule Trigger** (every 30 minutes)
2. **HTTP Request** → Get all folder statuses
   - URL: `http://10.10.10.200:8384/rest/stats/folder`
3. **Function** → Check if any folder has errors or is significantly behind
4. **If** → Errors found
5. **Telegram** → Alert with folder name and status

---

### Workflow 7: Grafana Alert Forwarder

**Purpose:** Forward Grafana alerts to Telegram

**Nodes:**
1. **Webhook Trigger** → Grafana webhook
2. **Function** → Parse alert data
3. **Telegram** → Format and send alert

**Grafana Setup:**
- Contact Point → Add webhook: `https://n8n.htsn.io/webhook/grafana-alerts`

---

### Workflow 8: Daily Homelab Summary

**Nodes:**
1. **Schedule Trigger** (9am daily)
2. **Multiple HTTP Requests in parallel:**
   - Prometheus: System uptime
   - Prometheus: Average CPU usage (24h)
   - Prometheus: Disk usage
   - Syncthing: Sync status (all folders)
   - PiHole: Queries blocked (24h)
3. **Function** → Format data as summary
4. **Telegram** → Send daily report

**Example Output:**
```
🏠 Homelab Daily Summary

✅ All systems operational
⏱️  Uptime: 14 days
📊 Avg CPU: 12%
💾 Disk: 45% used
🔄 Syncthing: All folders in sync
🛡️  PiHole: 2,341 queries blocked

Last updated: 2025-12-27 09:00
```

---

### Workflow 9: VM State Change Monitor

**Nodes:**
1. **Schedule Trigger** (every 1 minute)
2. **HTTP Request** → Query Proxmox API for VM list
3. **Function** → Compare with previous state (use Set node)
4. **If** → VM state changed
5. **Telegram** → Notify VM started/stopped

---

### Workflow 10: Internet Speed Test Alert

**Nodes:**
1. **Schedule Trigger** (every 6 hours)
2. **HTTP Request** → Prometheus speedtest exporter
3. **If** → Download speed < 500 Mbps
4. **Telegram** → Alert about slow internet

---

## Advanced Integration Ideas

### Home Assistant Automations
- Turn on lights when server room temperature > 80°F
- Trigger workflows from HA button press
- Send sensor data to external services

### Proxmox Automation
- Auto-snapshot VMs before updates
- Clone VMs for testing
- Monitor resource usage and rebalance

### Media Management
- Notify when new Plex content added
- Auto-organize downloads
- Send weekly watch statistics

### Backup Monitoring
- Verify all Syncthing folders synced
- Alert on ZFS scrub errors
- Monitor snapshot ages

### Security
- Alert on failed SSH attempts (from logs)
- Monitor SSL certificate expiration
- Track unusual network traffic patterns

---

## n8n Best Practices

1. **Error Handling:** Always add error workflows to catch failures
2. **Rate Limiting:** Don't query APIs too frequently
3. **Credentials:** Never hardcode - always use credential store
4. **Testing:** Use manual trigger during development
5. **Logging:** Add Set nodes to track workflow state
6. **Backups:** Export workflows regularly (Settings → Export)

---

## Useful PromQL Queries for n8n

**CPU Usage:**
```promql
100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
```

**Memory Usage:**
```promql
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100
```

**Disk Usage:**
```promql
(node_filesystem_size_bytes{mountpoint="/"} - node_filesystem_avail_bytes{mountpoint="/"}) / node_filesystem_size_bytes{mountpoint="/"} * 100
```

**Hosts Down:**
```promql
up{job=~"node.*"} == 0
```

**Syncthing Disconnected:**
```promql
up{job=~"syncthing.*"} == 0
```

---

## Webhook URLs

After creating webhooks in n8n, you'll get URLs like:
- `https://n8n.htsn.io/webhook/your-webhook-name`

These can be called from:
- Grafana alerts
- Home Assistant automations
- Gitea webhooks
- Custom scripts
- UPS monitoring (NUT)

---

## Testing Credentials

Test each credential after adding:
1. Create simple workflow with manual trigger
2. Add HTTP Request node with credential
3. Execute and check response
4. Verify data returned correctly

---

## Troubleshooting

**Can't reach local service:**
- Verify service IP and port
- Check if service requires HTTPS
- Test with `curl` from docker-host2 first

**Webhook not triggering:**
- Check n8n is accessible: `curl https://n8n.htsn.io/webhook/test`
- Verify webhook URL in external service
- Check n8n execution logs

**Workflow fails silently:**
- Enable "Execute on Error" workflow
- Check workflow execution list
- Add Function nodes to log data

**API authentication fails:**
- Verify credential is saved
- Check API token hasn't expired
- Test with curl manually first

---

## Next Steps

1. **Add Credentials** - Start with Telegram and Prometheus
2. **Create Test Workflow** - Simple hourly health check
3. **Test Telegram** - Verify messages arrive
4. **Build Gradually** - Add one workflow at a time
5. **Export Backups** - Save workflows regularly

---

## Resources

- **n8n Docs:** https://docs.n8n.io
- **Community Workflows:** https://n8n.io/workflows
- **Your n8n:** https://n8n.htsn.io
- **Your API Docs:** [N8N.md](N8N.md)

**Last Updated:** 2025-12-27