383 lines
8.9 KiB
Markdown
383 lines
8.9 KiB
Markdown
# 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
|