16: Uptime Kuma - Monitoring & Status Pages

Uptime Kuma is a self-hosted monitoring solution built with Node.js. It provides uptime monitoring, incident tracking, status pages, and 90+ notification integrations. Supports HTTP(s), TCP, Ping, DNS, Docker containers, and more. For API documentation, advanced configuration, and development guides, see the official Uptime Kuma repository.

Prerequisites

• ✅ Docker installed (Chapter 3)
• ✅ Docker Compose (Chapter 3)
• ✅ Optional: Traefik installed (Chapter 4) for HTTPS with Let's Encrypt
• ✅ Optional: Domain configured (Chapter 4.5), e.g., status.example.com

Installation via Infinity Tools

Menu Installation

📱 APPLICATIONS → Uptime Kuma → Install

CLI Installation

sudo bash /opt/InfinityTools/Solutions/setup-uptime-kuma.sh --install

# With domain (Traefik mode)
export BS_DOMAIN="status.example.com"
sudo -E bash /opt/InfinityTools/Solutions/setup-uptime-kuma.sh --install

Deployment Modes

Traefik Mode (Default)

Uses Traefik for SSL termination and domain routing:

• Automatic Let's Encrypt certificate provisioning
• Domain-based access: https://status.example.com
• Security headers configured
• Requires: Traefik running, DNS A record configured

Standalone Mode

Direct access with HTTP or HTTPS (self-signed):

• HTTP: http://SERVER_IP:3001
• HTTPS: https://SERVER_IP:3001 (self-signed cert via nginx proxy)
• Default port: 3001 (configurable)
• No domain required

Architecture

Container

• uptime-kuma - Main application (louislam/uptime-kuma:1)
• uptime-kuma-ssl-proxy - Nginx SSL proxy (standalone HTTPS mode only)

Data Persistence

• Data: /opt/speedbits/uptime-kuma/data/ (SQLite database, config)
• SSL: /opt/speedbits/uptime-kuma/ssl/ (standalone mode certificates)

Networks

• Traefik network: Joins Traefik's proxy network (Traefik mode)
• kuma-internal: Isolated bridge network (standalone mode)

Docker Socket Access

Optional read-only access to /var/run/docker.sock for Docker container monitoring:

• Enables Docker container monitoring
• Read-only mount (security best practice)
• Configured during installation

Installation Process

Configuration Steps

1. SSL Mode Selection: Choose Traefik (default) or Standalone
2. If Traefik: Provide domain name
3. If Standalone: Specify port (default: 3001) and SSL mode
4. Docker Monitoring: Optional enable Docker socket access
5. Timezone: Optional timezone configuration (default: UTC)

What Gets Created

• Directory: /opt/speedbits/uptime-kuma
• Container: uptime-kuma
• Docker Compose: /opt/speedbits/uptime-kuma/docker-compose.yml
• Data Volume: SQLite database and configuration

Access Methods

Traefik Mode

https://status.example.com

Direct web access after DNS propagation and SSL certificate generation (30-60 seconds).

Standalone Mode

HTTP:

http://SERVER_IP:3001

HTTPS:

https://SERVER_IP:3001

Accept self-signed certificate warning (Advanced → Proceed).

Authentication

First-Time Setup

• No default credentials - Admin account must be created on first access
• Setup wizard: "Create your admin account" appears on first visit
• Password requirements: Minimum 8 characters (12+ recommended)
• ⚠️ CRITICAL: Write down credentials immediately - no password reset on first setup

Password Reset

docker exec -it uptime-kuma npm run reset-password

Follow prompts to enter username and new password.

Monitor Types

Supported Protocols

• HTTP(s) - Websites, APIs, webhooks
• TCP - Port monitoring (SSH, databases, etc.)
• Ping (ICMP) - Server availability
• DNS - DNS record monitoring
• Docker Container - Container health (requires Docker socket)
• Keyword - Content-based monitoring
• SMTP - Email server monitoring
• gRPC - gRPC service monitoring

Monitor Configuration

• Check interval - Frequency of checks (default: 60 seconds)
• Retry attempts - Number of retries before marking as down
• Timeout - Request timeout
• Expected status codes - HTTP status codes to consider "up"
• Keyword detection - Check for specific text in response

Notification Integrations

Supported Providers

• Discord - Webhook integration
• Slack - Webhook integration
• Telegram - Bot API
• Email - SMTP
• Apprise - Self-hosted Apprise (80+ services)
• Webhooks - Custom HTTP endpoints
• 90+ providers - See full list in Uptime Kuma settings

Apprise Integration

If Apprise is installed (Chapter 5), use it for notifications:

• Type: Apprise (Self-hosted)
• URL: http://apprise:8000/notify/{YOUR-KEY}
• Enables access to all Apprise-supported services

Status Pages

Features

• Public status pages (no authentication required)
• Customizable appearance (colors, logo, theme)
• Monitor selection (choose which monitors to display)
• Incident history
• Uptime statistics
• RSS feed support

Use Cases

• Public service status (like status.github.com)
• Internal team dashboards
• Customer-facing status pages
• Service health transparency

Environment Variables

Uptime Kuma Container

• TZ - Timezone (default: UTC)

Data Storage

• SQLite database stored in /app/data
• Persisted via Docker volume mount
• Includes monitors, notifications, status pages, user accounts

Security Configuration

Access Security

• ✅ Traefik mode uses Let's Encrypt SSL (production-ready)
• ✅ Standalone HTTPS uses self-signed certificates (acceptable for internal use)
• ✅ Security headers configured (X-Frame-Options, CSP, etc.)
• ✅ Docker socket mounted read-only (if enabled)
• ✅ Security option: no-new-privileges:true

Container Security

• Runs as non-root user
• Read-only Docker socket access (if enabled)
• Network isolation
• Volume mounts for data persistence

Configuration Persistence

• Data Volume: data persists all configuration
• SQLite Database: Stored in data directory
• All monitors, notifications, and settings survive container restarts

Backup & Restore

Backup Strategy

# Full backup
cd /opt/speedbits
tar czf uptime-kuma-backup-$(date +%Y%m%d).tar.gz uptime-kuma/

# Using Uptime Kuma built-in backup
# Settings → Backup → Download Backup

Restore Process

1. Stop container: cd /opt/speedbits/uptime-kuma && docker compose down
2. Restore data: Extract backup to /opt/speedbits/uptime-kuma/
3. Start container: docker compose up -d

Troubleshooting

Container Not Starting

docker logs uptime-kuma
docker ps -a | grep uptime-kuma

SSL Certificate Issues

• Traefik mode: Check Traefik logs: docker logs traefik
• Traefik mode: Verify DNS: dig status.example.com
• Standalone mode: Check nginx proxy logs: docker logs uptime-kuma-ssl-proxy

Docker Monitoring Issues

• Verify Docker socket access: docker exec uptime-kuma ls /var/run/docker.sock
• Check container permissions
• Verify socket is mounted read-only

Monitor Not Responding

• Check monitor configuration (URL, port, etc.)
• Verify service is actually running
• Check network connectivity from container
• Review monitor logs in Uptime Kuma dashboard

Production Considerations

• Access Method: Use Traefik mode for production (trusted SSL)
• Password Policy: Enforce strong passwords (12+ characters)
• 2FA: Enable two-factor authentication (Settings → Security)
• Backup Strategy: Implement automated backups
• Monitoring: Monitor Uptime Kuma itself (meta-monitoring)
• Notifications: Configure multiple notification channels for redundancy
• Status Pages: Use public status pages instead of sharing admin access

Integration with Infinity Tools

Uptime Kuma complements Infinity Tools by providing:

• Monitoring for all Infinity Tools applications
• Docker container monitoring for infrastructure
• Status pages for public service transparency
• Notification integration with Apprise

Recommended Monitors:

• Traefik dashboard
• All Infinity Tools application endpoints
• Docker daemon health
• Server resources (via Netdata if installed)

API & Automation

REST API

• Uptime Kuma provides REST API for programmatic access
• API documentation available in web interface
• Useful for automation and integration

Webhooks

• Incoming webhooks for external integrations
• Outgoing webhooks for custom notifications
• Custom payload formatting

Next Steps

Uptime Kuma is now operational. Use it to:

• Monitor all Infinity Tools applications
• Track Docker container health
• Create public status pages
• Set up multi-channel notifications
• Track uptime statistics and incidents

For advanced features, API usage, custom themes, and development guides, refer to the official Uptime Kuma repository.