docker-infrastructure/uptime-kuma/README.md

# Uptime Kuma Management

Complete documentation for managing Uptime Kuma monitors and tags via CLI and API.

## Quick Reference

### Prerequisites
```bash
# Set credentials (add to ~/.bashrc for persistence)
export UPTIME_KUMA_USERNAME="poprhythm"
export UPTIME_KUMA_PASSWORD="your_password"
```

### Common Commands

```bash
# List all monitors
./manage_monitors.py list

# Add a monitor
./manage_monitors.py add --name "Service" --url "https://example.com"

# Update a monitor
./manage_monitors.py update --id 123 --interval 120

# Delete a monitor
./manage_monitors.py delete --id 123

# Tag a monitor
./tag_monitor.sh 123 3 4  # Tag as application + web

# View all tags
./check_tags.py
```

## Documentation Files

| File | Purpose |
|------|---------|
| **[SETUP.md](SETUP.md)** | Initial setup and installation |
| **[API.md](API.md)** | Complete API usage and examples |
| **[TAG_MANAGEMENT.md](TAG_MANAGEMENT.md)** | Comprehensive tag management guide |
| **[TAG_SUMMARY.md](TAG_SUMMARY.md)** | Current tag schema and assignments |

## Scripts

| Script | Purpose |
|--------|---------|
| `manage_monitors.py` | Main CLI for monitor CRUD operations |
| `tag_monitor.sh` | Quick script to tag monitors |
| `check_tags.py` | View current tag assignments |
| `add_tags.py` | Bulk tag assignment (requires editing) |
| `fix_missing_tags.py` | Add specific tags to specific monitors |

## Complete Workflow: Adding a New Monitor

### Step 1: Add the Monitor
```bash
./manage_monitors.py add \
  --name "New Service" \
  --url "https://newservice.com" \
  --type http \
  --interval 60
```

### Step 2: Get Monitor ID
```bash
./manage_monitors.py list | grep "New Service"
# Output: 16     New Service     http     https://newservice.com
```

### Step 3: Tag the Monitor
```bash
# Choose appropriate tags based on service type:
# - Web service: 3 (application) + 4 (web)
# - Database: 3 (application) + 5 (database)
# - Storage: 7 (infrastructure) + 8 (storage)
# - VM: 7 (infrastructure) + 10 (vm)

./tag_monitor.sh 16 3 4
```

### Step 4: Verify
```bash
./check_tags.py | grep "New Service"
# Should show the monitor with its tags
```

## Tag Reference

| ID | Tag | Use For |
|----|-----|---------|
| 1 | hardware | Physical hardware monitoring |
| 2 | monitoring | Monitoring systems |
| 3 | application | Software applications |
| 4 | web | Web services |
| 5 | database | Database systems |
| 6 | media | Media servers |
| 7 | infrastructure | Core infrastructure |
| 8 | storage | Storage systems |
| 9 | virtualization | Virtualization platforms |
| 10 | vm | Virtual machines |

## Monitor Types

| Type | Example URL | Use For |
|------|-------------|---------|
| `http` | `https://example.com` | HTTP/HTTPS endpoints |
| `tcp` | `hostname:port` | TCP port checks |
| `ping` | `192.168.1.1` | ICMP ping |
| `dns` | `example.com` | DNS resolution |
| `docker` | Container name | Docker container health |

## Common Tagging Patterns

```bash
# Web application
./manage_monitors.py add --name "GitLab" --url "https://gitlab.example.com"
./tag_monitor.sh NEW_ID 3 4  # application + web

# Database
./manage_monitors.py add --name "PostgreSQL" --url "db.example.com:5432" --type tcp
./tag_monitor.sh NEW_ID 3 5  # application + database

# Storage/NAS
./manage_monitors.py add --name "Storage" --url "nas.example.com" --type ping
./tag_monitor.sh NEW_ID 7 8  # infrastructure + storage

# Virtual Machine
./manage_monitors.py add --name "VM Host" --url "vm.example.com" --type ping
./tag_monitor.sh NEW_ID 7 10  # infrastructure + vm

# Hardware monitoring
./manage_monitors.py add --name "Server Fan" --url "..." --type mqtt
./tag_monitor.sh NEW_ID 1 2  # hardware + monitoring
```

## Troubleshooting

### Authentication Issues
```bash
# Check credentials are set
echo $UPTIME_KUMA_USERNAME
echo $UPTIME_KUMA_PASSWORD

# If not set, export them
export UPTIME_KUMA_USERNAME="poprhythm"
export UPTIME_KUMA_PASSWORD="your_password"
```

### Monitor Not Found
```bash
# List all monitors to verify ID
./manage_monitors.py list
```

### Tag Already Exists
This is normal if you try to add a tag that's already assigned. It can be ignored.

### SSL Certificate Warnings
These warnings are expected for self-signed certificates and can be ignored. The scripts use `ssl_verify=False` to handle this.

## Web UI

Access the web interface at: **https://uptime.kolpacksoftware.com**

- Filter by tags
- View status pages
- Manage notifications
- Configure settings

## Best Practices

1. **Always tag new monitors** immediately after creation
2. **Use 2-3 tags** per monitor for better organization
3. **Document custom tags** if you add new tag types
4. **Run audits** periodically with `check_tags.py`
5. **Set credentials** persistently in your shell profile
6. **Use descriptive names** for monitors (include service purpose)
7. **Group related services** using consistent tagging

## Getting Help

- **Setup issues**: See [SETUP.md](SETUP.md)
- **API questions**: See [API.md](API.md)
- **Tag management**: See [TAG_MANAGEMENT.md](TAG_MANAGEMENT.md)
- **Current tags**: See [TAG_SUMMARY.md](TAG_SUMMARY.md)
- **Uptime Kuma docs**: https://github.com/louislam/uptime-kuma/wiki

## Maintenance

### Regular Tasks

**Weekly:**
- Review untagged monitors: `./check_tags.py | grep "No tags"`
- Verify critical monitors are up

**Monthly:**
- Review and update monitor intervals
- Clean up old/unused monitors
- Verify tag schema still makes sense

**As Needed:**
- Update documentation when adding new tag types
- Adjust check intervals based on service criticality
- Review and optimize notification rules