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

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

Common Commands

# 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	Initial setup and installation
API.md	Complete API usage and examples
TAG_MANAGEMENT.md	Comprehensive tag management guide
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

./manage_monitors.py add \
  --name "New Service" \
  --url "https://newservice.com" \
  --type http \
  --interval 60

Step 2: Get Monitor ID

./manage_monitors.py list | grep "New Service"
# Output: 16     New Service     http     https://newservice.com

Step 3: Tag the Monitor

# 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

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

# 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

# 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

# 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
• API questions: See API.md
• Tag management: See TAG_MANAGEMENT.md
• Current tags: See 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