docker-infrastructure/uptime-kuma/SETUP.md

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)

sudo apt update
sudo apt install python3-pip -y

Step 2: Install uptime-kuma-api Package

pip3 install uptime-kuma-api
# Or if pip3 is not in PATH:
python3 -m pip install uptime-kuma-api

Verify installation:

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:

   export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
   

   Or set temporarily:

   export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
   

   Apply changes:

   source ~/.bashrc  # or source ~/.zshrc
   

Option B: Username/Password

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

cd /home/poprhythm/docker-infrastructure
ls -l uptime-kuma/manage_monitors.py
# Should show -rwxr-xr-x (executable permissions)

Test 2: List Existing Monitors

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

./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

# 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:

# 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:

# 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:

# 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 for full usage documentation

Quick Reference

# 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