poprhythm
3a990fc686
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
190 lines
4.5 KiB
Markdown
190 lines
4.5 KiB
Markdown
# 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
|
|
```
|