Initial infrastructure documentation - comprehensive homelab reference
This commit is contained in:
Funky (OpenClaw)
317
N8N-UPTIME-KUMA-GUIDE.md
Normal file
317
N8N-UPTIME-KUMA-GUIDE.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# n8n + Uptime Kuma Integration Guide
|
||||
|
||||
**n8n for Beginners:** This guide will walk you through setting up smart notifications for your infrastructure monitoring.
|
||||
|
||||
---
|
||||
|
||||
## What This Does
|
||||
|
||||
This n8n workflow receives alerts from Uptime Kuma and routes them intelligently:
|
||||
|
||||
- **CRITICAL alerts** → Email + Discord/Slack (immediate)
|
||||
- **PUBLIC alerts** → Discord (after retry threshold)
|
||||
- **INTERNAL/METRICS/UTILITY** → Logged only (no spam)
|
||||
|
||||
All alerts are logged for debugging and historical tracking.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Import Workflow into n8n
|
||||
|
||||
### 1.1 Access n8n
|
||||
Go to http://10.0.10.22:5678
|
||||
|
||||
### 1.2 Import the Workflow
|
||||
1. Click **Workflows** (left sidebar)
|
||||
2. Click **Add Workflow** (top right)
|
||||
3. Click the **⋮** menu (top right) → **Import from File**
|
||||
4. Select: `C:\Users\Fred\projects\n8n-uptime-kuma-workflow.json`
|
||||
5. Click **Import**
|
||||
|
||||
### 1.3 Activate the Workflow
|
||||
1. The workflow editor will open
|
||||
2. Toggle the **Active** switch (top right) to **ON**
|
||||
3. You should see "Workflow activated" message
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Get Your Webhook URL
|
||||
|
||||
### 2.1 Find the Webhook URL
|
||||
1. In the workflow editor, click on the **"Webhook - Uptime Kuma"** node (first blue node)
|
||||
2. Look for **Test URL** or **Production URL**
|
||||
3. Copy the production URL - it should look like:
|
||||
```
|
||||
http://10.0.10.22:5678/webhook/uptime-kuma
|
||||
```
|
||||
|
||||
**Save this URL** - you'll need it for Uptime Kuma!
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Configure Uptime Kuma Notifications
|
||||
|
||||
### 3.1 Create n8n Notification Channel
|
||||
1. Go to Uptime Kuma: http://10.0.10.26:3001
|
||||
2. Click **Settings** (left sidebar)
|
||||
3. Click **Notifications** tab
|
||||
4. Click **Add New Notification**
|
||||
|
||||
### 3.2 Configure Webhook
|
||||
- **Notification Type:** Select **Webhook**
|
||||
- **Friendly Name:** `n8n Alert Router`
|
||||
- **POST URL:** `http://10.0.10.22:5678/webhook/uptime-kuma`
|
||||
- **Content Type:** `application/json`
|
||||
- **Notification Sound:** (your preference)
|
||||
- Click **Test** to verify
|
||||
- Click **Save**
|
||||
|
||||
### 3.3 Assign to Monitors
|
||||
Now assign this notification to your monitors:
|
||||
|
||||
1. Go to **Dashboard**
|
||||
2. Click on a **CRITICAL** monitor (e.g., "Proxmox - main-pve")
|
||||
3. Click **Edit**
|
||||
4. Scroll to **Notifications**
|
||||
5. Select **n8n Alert Router**
|
||||
6. **Apply on:** Select **When status is DOWN**
|
||||
7. Click **Save**
|
||||
|
||||
**Repeat for all CRITICAL monitors** (you can select multiple monitors and edit in bulk)
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Enable Notification Channels
|
||||
|
||||
By default, all notification nodes are **disabled** (to prevent errors). Enable the ones you want to use:
|
||||
|
||||
### Option A: Discord (Recommended for Beginners)
|
||||
|
||||
**4.1 Create Discord Webhook:**
|
||||
1. Open Discord
|
||||
2. Go to your server → Settings → Integrations
|
||||
3. Click **Webhooks** → **New Webhook**
|
||||
4. Name it "Uptime Kuma Alerts"
|
||||
5. Select channel (e.g., #monitoring)
|
||||
6. Copy the **Webhook URL**
|
||||
|
||||
**4.2 Configure in n8n:**
|
||||
1. In the workflow, click **"Discord - CRITICAL Alert"** node
|
||||
2. Click **Parameters**
|
||||
3. Paste your Discord webhook URL
|
||||
4. Toggle the node **Enabled** (remove checkmark from "Disabled")
|
||||
5. Click **Save** (top right)
|
||||
|
||||
**Repeat for "Discord - PUBLIC Alert"** if you want public service alerts too.
|
||||
|
||||
### Option B: Email (SMTP)
|
||||
|
||||
**4.1 Configure in n8n:**
|
||||
1. Click **"Email - CRITICAL Alert"** node
|
||||
2. Click **Credentials** → **Create New**
|
||||
3. Choose your email provider:
|
||||
- **Gmail:** Use App Password (not your main password)
|
||||
- **Outlook/Office365:** Use SMTP settings
|
||||
- **Custom SMTP:** Enter your SMTP details
|
||||
|
||||
**Example: Gmail Setup**
|
||||
- **From Email:** your-gmail@gmail.com
|
||||
- **To Email:** your-alert-email@gmail.com
|
||||
- **SMTP Host:** smtp.gmail.com
|
||||
- **SMTP Port:** 587
|
||||
- **Username:** your-gmail@gmail.com
|
||||
- **Password:** (App Password from Google Account settings)
|
||||
- **Secure:** TLS
|
||||
|
||||
4. Click **Test** to verify
|
||||
5. Click **Save**
|
||||
6. Enable the node (uncheck "Disabled")
|
||||
|
||||
### Option C: Slack
|
||||
|
||||
**4.1 Create Slack App:**
|
||||
1. Go to https://api.slack.com/apps
|
||||
2. Click **Create New App** → **From scratch**
|
||||
3. Name: "Uptime Kuma"
|
||||
4. Select your workspace
|
||||
5. Go to **OAuth & Permissions**
|
||||
6. Add Bot Token Scopes: `chat:write`, `chat:write.public`
|
||||
7. Click **Install to Workspace**
|
||||
8. Copy the **Bot User OAuth Token**
|
||||
|
||||
**4.2 Configure in n8n:**
|
||||
1. Click **"Slack - CRITICAL Alert"** node
|
||||
2. Click **Credentials** → **Create New**
|
||||
3. Paste your Bot Token
|
||||
4. Click **Save**
|
||||
5. Enable the node
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Test Your Setup
|
||||
|
||||
### 5.1 Trigger a Test Alert
|
||||
Let's test with a non-critical monitor:
|
||||
|
||||
1. Go to Uptime Kuma
|
||||
2. Find **"[UTILITY] CA Server"** monitor
|
||||
3. Click **Edit**
|
||||
4. Temporarily change port from `8443` to `9999` (invalid port)
|
||||
5. Click **Save**
|
||||
6. Wait 30-60 seconds for the monitor to check
|
||||
|
||||
### 5.2 Check n8n Execution
|
||||
1. Go to n8n: http://10.0.10.22:5678
|
||||
2. Click **Executions** (left sidebar)
|
||||
3. You should see a new execution
|
||||
4. Click it to view details
|
||||
|
||||
### 5.3 Verify Alert Received
|
||||
- **Discord:** Check your #monitoring channel
|
||||
- **Email:** Check your inbox
|
||||
- **Slack:** Check your channel
|
||||
|
||||
### 5.4 Fix the Monitor
|
||||
1. Go back to Uptime Kuma
|
||||
2. Edit the CA Server monitor
|
||||
3. Change port back to `8443`
|
||||
4. Save
|
||||
|
||||
---
|
||||
|
||||
## Workflow Overview
|
||||
|
||||
Here's what happens when a monitor goes down:
|
||||
|
||||
```
|
||||
Uptime Kuma Alert
|
||||
↓
|
||||
n8n Webhook Receives
|
||||
↓
|
||||
Format Alert Data
|
||||
(Parses monitor info, status, error)
|
||||
↓
|
||||
┌──────────────┬──────────────┐
|
||||
↓ ↓ ↓
|
||||
Is CRITICAL? Is PUBLIC? Log All
|
||||
↓ ↓ Alerts
|
||||
↓ ↓
|
||||
Email + Discord
|
||||
Discord + (Optional)
|
||||
Slack
|
||||
(Optional)
|
||||
```
|
||||
|
||||
**Smart Routing:**
|
||||
- CRITICAL monitors (VPS, Proxmox, PostgreSQL) → Immediate multi-channel alerts
|
||||
- PUBLIC monitors (websites) → Discord only
|
||||
- Everything else → Logged for review
|
||||
|
||||
---
|
||||
|
||||
## Customization Ideas
|
||||
|
||||
### Add SMS Alerts (via Twilio)
|
||||
1. Add **Twilio** node after "Is CRITICAL?"
|
||||
2. Configure with your Twilio account
|
||||
3. Send SMS for CRITICAL alerts only
|
||||
|
||||
### Add Phone Call Alerts
|
||||
1. Use **Twilio** or **VoIP.ms** node
|
||||
2. Trigger phone calls for critical infrastructure failures
|
||||
3. Only for CRITICAL monitors to avoid spam
|
||||
|
||||
### Create Alert Batching
|
||||
1. Add **Wait** node before Discord/Email
|
||||
2. Collect multiple alerts for 5 minutes
|
||||
3. Send one consolidated message
|
||||
|
||||
### Add Status Page Integration
|
||||
1. After "Format Alert Data", add **HTTP Request** node
|
||||
2. POST to your status page API
|
||||
3. Auto-update public status page
|
||||
|
||||
### Store Alerts in Database
|
||||
1. Add **PostgreSQL** node (connect to 10.0.10.20)
|
||||
2. Create `alerts` table
|
||||
3. Log all alerts for historical analysis
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Webhook Not Receiving Data
|
||||
- Check workflow is **Active** (toggle at top right)
|
||||
- Verify webhook URL is correct in Uptime Kuma
|
||||
- Check n8n executions for errors
|
||||
|
||||
### Discord/Email Not Sending
|
||||
- Make sure node is **Enabled** (not grayed out)
|
||||
- Check credentials are configured
|
||||
- Look at n8n execution details for error messages
|
||||
|
||||
### Too Many Alerts
|
||||
- Increase retry counts in Uptime Kuma monitors
|
||||
- Change "Apply on" to only DOWN (not also UP)
|
||||
- Add filtering logic in n8n (only alert after X failures)
|
||||
|
||||
### Not Enough Alerts
|
||||
- Check monitor has notification assigned
|
||||
- Verify "Apply on" includes DOWN status
|
||||
- Check n8n workflow is active
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Alert Suppression (Prevent Spam)
|
||||
|
||||
Add this after "Format Alert Data" to suppress duplicate alerts:
|
||||
|
||||
1. Add **Function** node
|
||||
2. Code:
|
||||
```javascript
|
||||
// Suppress duplicate alerts within 15 minutes
|
||||
const alertKey = `${$json.fullName}-${$json.status}`;
|
||||
const lastAlert = $workflow.staticData[alertKey] || 0;
|
||||
const now = Date.now();
|
||||
|
||||
if (now - lastAlert < 15 * 60 * 1000) {
|
||||
// Alert sent less than 15 min ago - suppress
|
||||
return [];
|
||||
}
|
||||
|
||||
// Send alert and remember timestamp
|
||||
$workflow.staticData[alertKey] = now;
|
||||
return [$input.item];
|
||||
```
|
||||
|
||||
This prevents getting the same alert repeatedly.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Import workflow into n8n
|
||||
2. ✅ Activate workflow and get webhook URL
|
||||
3. ✅ Configure Uptime Kuma notification
|
||||
4. ✅ Enable Discord/Email/Slack notifications
|
||||
5. ✅ Test with a non-critical monitor
|
||||
6. ✅ Assign notifications to all CRITICAL monitors
|
||||
7. ⏸️ Customize alert routing (optional)
|
||||
8. ⏸️ Add SMS/phone call alerts (optional)
|
||||
9. ⏸️ Create alert dashboard in Grafana (optional)
|
||||
|
||||
---
|
||||
|
||||
**n8n Dashboard:** http://10.0.10.22:5678
|
||||
**Uptime Kuma:** http://10.0.10.26:3001
|
||||
**Workflow File:** `C:\Users\Fred\projects\n8n-uptime-kuma-workflow.json`
|
||||
|
||||
---
|
||||
|
||||
**Pro Tip:** Once you're comfortable with n8n, you can create workflows for:
|
||||
- Auto-restarting failed services
|
||||
- Creating GitHub issues when monitors fail
|
||||
- Sending daily/weekly uptime reports
|
||||
- Integration with your homelab automation
|
||||
|
||||
Welcome to n8n! 🎉
|
||||
Reference in New Issue
Block a user