# Uptime Kuma Monitoring Stack

> Self-hosted uptime monitoring with notifications, status pages, and integrations.

- Category: Monitoring & Observability
- Difficulty: beginner
- Components: uptime-kuma, mariadb, nginx
- Tags: uptime-kuma, uptime-monitoring, status-page, notifications
- Source: https://docker.recipes/monitoring/uptime-kuma-stack

## Overview

Uptime Kuma is a modern, self-hosted monitoring solution that emerged as an open-source alternative to commercial services like Uptime Robot and StatusCake. Created by Louis Lam, it provides comprehensive monitoring capabilities for websites, APIs, servers, and network services through an intuitive web interface. Unlike cloud-based monitoring services, Uptime Kuma gives you complete control over your monitoring data while supporting over 90 notification channels including Discord, Slack, Telegram, and email.

This monitoring stack combines Uptime Kuma with MariaDB for robust data persistence and Nginx as a reverse proxy for SSL termination and load balancing. MariaDB ensures reliable storage of monitoring history, downtime records, and configuration data, while Nginx handles SSL certificates, custom domains, and can serve as an entry point for multiple monitoring instances. The combination creates a production-ready monitoring infrastructure that can handle hundreds of monitors with detailed historical data.

This stack is ideal for DevOps teams, system administrators, and organizations requiring comprehensive uptime monitoring without vendor lock-in or usage limits. Whether you're monitoring a single website or managing infrastructure for multiple clients, this configuration provides enterprise-grade monitoring capabilities with the flexibility to customize notification workflows, create public status pages, and maintain complete data ownership.

## Features

- Multiple monitor types including HTTP/HTTPS, TCP, Ping, DNS Record, Docker Container, and Certificate expiry monitoring
- Beautiful, customizable status pages for public or private use with incident management
- 90+ notification integrations including Slack, Discord, Telegram, PagerDuty, and webhooks
- Two-factor authentication (2FA) support with time-based one-time passwords
- Proxy support for monitoring services behind firewalls or in private networks
- Real-time monitoring dashboard with customizable check intervals from 20 seconds to 24 hours
- MariaDB persistence for comprehensive historical data, uptime statistics, and incident tracking
- Nginx SSL termination with automatic HTTP to HTTPS redirection and custom domain support

## Use cases

- Website and API uptime monitoring for SaaS applications with public status pages for customers
- Internal service monitoring for microservices architectures with Slack/Teams notifications
- E-commerce platform monitoring including payment gateways, CDNs, and third-party integrations
- Multi-client monitoring for web agencies and hosting providers with separate status pages
- Homelab and self-hosted service monitoring with mobile push notifications
- SSL certificate expiration tracking for multiple domains and subdomains
- Database and server health monitoring using TCP and ping checks with escalation workflows

## Prerequisites

- Docker and Docker Compose installed with at least 512MB available RAM for the complete stack
- Ports 80, 443, and 3001 available on the host system for web access and SSL termination
- Domain name and SSL certificates if enabling HTTPS access through Nginx
- Basic understanding of reverse proxy configuration for customizing Nginx settings
- Email server credentials or notification service API keys for alert delivery
- At least 2GB disk space for MariaDB data storage and monitoring history retention

## docker-compose.yml

```yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    ports:
      - "3001:3001"
    volumes:
      - uptime_kuma_data:/app/data
    environment:
      - UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=false
    networks:
      - uptime-net
    restart: unless-stopped

  mariadb:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - uptime-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - uptime-kuma
    networks:
      - uptime-net
    restart: unless-stopped

volumes:
  uptime_kuma_data:
  mariadb_data:

networks:
  uptime-net:
    driver: bridge
```

## .env

```bash
# MariaDB Configuration
MYSQL_ROOT_PASSWORD=secure_root_password
MYSQL_DATABASE=uptime
MYSQL_USER=uptime
MYSQL_PASSWORD=secure_mysql_password
```

## Usage notes

- Uptime Kuma at http://localhost:3001
- First visit to set up admin account
- Configure nginx.conf for SSL termination
- Supports 90+ notification services

## Troubleshooting

- Uptime Kuma shows 'Cannot connect to database': Verify MariaDB container is running and check MYSQL_* environment variables match between services
- 502 Bad Gateway from Nginx: Ensure uptime-kuma service is healthy and accessible on port 3001 within the Docker network
- Monitors showing false positives: Adjust timeout values in monitor settings and verify DNS resolution from within the container
- Status page not updating: Check if 'Public Status Page' is enabled in Uptime Kuma settings and verify the correct URL format
- Notifications not sending: Verify notification service credentials and test connectivity from the Uptime Kuma container to external APIs
- MariaDB connection errors on startup: Ensure proper file permissions on the mariadb_data volume and check Docker logs for initialization errors

