Add Uptime Kuma API management tooling

Implements programmatic monitor management via Socket.IO API: - manage_monitors.py: CLI script for CRUD operations on monitors - API.md: Comprehensive API usage documentation - SETUP.md: Step-by-step setup and verification guide Key features: - Supports API key and username/password authentication - List, add, update, delete monitors via CLI - SSL verification disabled for self-signed certificates - Monitor types: HTTP, TCP, ping, DNS, docker
2026-02-08 19:59:43 +00:00
parent f46d493ca2
commit 3a990fc686
3 changed files with 562 additions and 0 deletions
@@ -0,0 +1,189 @@
+# Uptime Kuma API Setup Guide
+
+## Prerequisites Installation
+
+The management script requires Python 3.7+ and the `uptime-kuma-api` package.
+
+### Step 1: Install pip (if not already installed)
+
+```bash
+sudo apt update
+sudo apt install python3-pip -y
+```
+
+### Step 2: Install uptime-kuma-api Package
+
+```bash
+pip3 install uptime-kuma-api
+# Or if pip3 is not in PATH:
+python3 -m pip install uptime-kuma-api
+```
+
+**Verify installation:**
+```bash
+python3 -c "import uptime_kuma_api; print('Package installed successfully')"
+```
+
+## Authentication Setup
+
+You must configure API credentials before using the management script.
+
+### Option A: API Key (Recommended)
+
+1. **Access Uptime Kuma web UI:**
+   - URL: https://uptime.kolpacksoftware.com
+   - Log in with your credentials
+
+2. **Generate API Key:**
+   - Click the gear icon (Settings)
+   - Navigate to **API Keys** section
+   - Click **Generate**
+   - Set a descriptive name (e.g., "CLI Management")
+   - Set expiry (or "Never expire")
+   - **IMPORTANT:** Copy the key immediately - it's only shown once!
+
+3. **Configure Environment Variable:**
+
+   Add to `~/.bashrc` or `~/.zshrc`:
+   ```bash
+   export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
+   ```
+
+   Or set temporarily:
+   ```bash
+   export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
+   ```
+
+   Apply changes:
+   ```bash
+   source ~/.bashrc  # or source ~/.zshrc
+   ```
+
+### Option B: Username/Password
+
+```bash
+export UPTIME_KUMA_USERNAME="your_username"
+export UPTIME_KUMA_PASSWORD="your_password"
+```
+
+**Note:** Once you create the first API key, username/password authentication is permanently disabled for API endpoints. API keys are more secure and recommended.
+
+## Verification
+
+### Test 1: Check Script is Executable
+
+```bash
+cd /home/poprhythm/docker-infrastructure
+ls -l uptime-kuma/manage_monitors.py
+# Should show -rwxr-xr-x (executable permissions)
+```
+
+### Test 2: List Existing Monitors
+
+```bash
+cd /home/poprhythm/docker-infrastructure
+./uptime-kuma/manage_monitors.py list
+```
+
+**Expected output:**
+```
+ID     Name                           Type       URL
+------------------------------------------------------------------------------------------------
+1      Example Service                http       https://example.com
+...
+```
+
+### Test 3: Add a Test Monitor
+
+```bash
+./uptime-kuma/manage_monitors.py add --name "Test Monitor" --url "https://httpbin.org/status/200" --type http --interval 300
+```
+
+### Test 4: Delete the Test Monitor
+
+```bash
+# Find the ID from the list command
+./uptime-kuma/manage_monitors.py list
+
+# Delete it (replace 999 with actual ID)
+./uptime-kuma/manage_monitors.py delete --id 999
+```
+
+### Test 5: Verify in Web UI
+
+1. Access https://uptime.kolpacksoftware.com
+2. Check that the test monitor was created and deleted
+3. Verify existing monitors match the CLI list output
+
+## Troubleshooting
+
+### "No credentials provided" Error
+
+**Cause:** Environment variables not set.
+
+**Fix:**
+```bash
+# Check current environment
+echo $UPTIME_KUMA_API_KEY
+
+# If empty, set it:
+export UPTIME_KUMA_API_KEY="uk1_your_key"
+```
+
+### "ModuleNotFoundError: No module named 'uptime_kuma_api'"
+
+**Cause:** Package not installed or installed for wrong Python version.
+
+**Fix:**
+```bash
+# Install for your Python 3
+python3 -m pip install --user uptime-kuma-api
+
+# Or system-wide (requires sudo)
+sudo python3 -m pip install uptime-kuma-api
+```
+
+### Connection Errors
+
+**Cause:** Uptime Kuma service not running or URL incorrect.
+
+**Fix:**
+```bash
+# Check service is running
+docker ps | grep uptime-kuma
+
+# Test web UI access
+curl -k https://uptime.kolpacksoftware.com
+
+# If needed, start the service
+cd /home/poprhythm/docker-infrastructure/uptime-kuma
+docker compose up -d
+```
+
+### SSL Certificate Errors
+
+**Cause:** Self-signed certificate or certificate validation issues.
+
+**Fix:** If using self-signed certificates, you may need to modify the script to disable SSL verification (not recommended for production).
+
+## Next Steps
+
+1. ✅ Install prerequisites (`python3-pip`, `uptime-kuma-api`)
+2. ✅ Create API key in web UI
+3. ✅ Set environment variable
+4. ✅ Test with `./manage_monitors.py list`
+5. 📖 Read [API.md](API.md) for full usage documentation
+
+## Quick Reference
+
+```bash
+# Set credentials (add to ~/.bashrc for persistence)
+export UPTIME_KUMA_API_KEY="uk1_your_api_key"
+
+# Common commands
+cd /home/poprhythm/docker-infrastructure
+./uptime-kuma/manage_monitors.py list
+./uptime-kuma/manage_monitors.py add --name "Service" --url "https://example.com"
+./uptime-kuma/manage_monitors.py update --id 123 --interval 120
+./uptime-kuma/manage_monitors.py delete --id 123
+```