Add comprehensive Uptime Kuma management documentation
Complete documentation for monitor and tag management workflows: New documentation: - README.md: Quick reference and complete workflow guide - TAG_MANAGEMENT.md: Comprehensive tag management strategies - tag_monitor.sh: Quick CLI script to tag monitors Updated documentation: - API.md: Added tag management section with quick reference Coverage: - Adding monitors with tags (complete workflow) - Updating and deleting monitors - Tag management strategies and patterns - Common tagging patterns by service type - Troubleshooting guide - Best practices and maintenance tasks All common operations are now documented with examples.
This commit is contained in:
@@ -0,0 +1,206 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user