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