Auto-sync: 20260105-122831
This commit is contained in:
Hutson
382
N8N-INTEGRATIONS.md
Normal file
382
N8N-INTEGRATIONS.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user