Uptime Kuma Monitoring Stack

beginner

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

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.

Key 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

Common Use Cases

1Website and API uptime monitoring for SaaS applications with public status pages for customers
2Internal service monitoring for microservices architectures with Slack/Teams notifications
3E-commerce platform monitoring including payment gateways, CDNs, and third-party integrations
4Multi-client monitoring for web agencies and hosting providers with separate status pages
5Homelab and self-hosted service monitoring with mobile push notifications
6SSL certificate expiration tracking for multiple domains and subdomains
7Database 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  uptime-kuma: 
3    image: louislam/uptime-kuma:latest
4    ports: 
5      - "3001:3001"
6    volumes: 
7      - uptime_kuma_data:/app/data
8    environment: 
9      - UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=false
10    networks: 
11      - uptime-net
12    restart: unless-stopped
13
14  mariadb: 
15    image: mariadb:11
16    environment: 
17      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
18      MYSQL_DATABASE: ${MYSQL_DATABASE}
19      MYSQL_USER: ${MYSQL_USER}
20      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
21    volumes: 
22      - mariadb_data:/var/lib/mysql
23    networks: 
24      - uptime-net
25    restart: unless-stopped
26
27  nginx: 
28    image: nginx:alpine
29    ports: 
30      - "80:80"
31      - "443:443"
32    volumes: 
33      - ./nginx.conf:/etc/nginx/nginx.conf:ro
34      - ./certs:/etc/nginx/certs:ro
35    depends_on: 
36      - uptime-kuma
37    networks: 
38      - uptime-net
39    restart: unless-stopped
40
41volumes: 
42  uptime_kuma_data: 
43  mariadb_data: 
44
45networks: 
46  uptime-net: 
47    driver: bridge

.env Template

.env

1# MariaDB Configuration
2MYSQL_ROOT_PASSWORD=secure_root_password
3MYSQL_DATABASE=uptime
4MYSQL_USER=uptime
5MYSQL_PASSWORD=secure_mysql_password

Usage Notes

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

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

uptime-kuma

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

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  uptime-kuma:
5    image: louislam/uptime-kuma:latest
6    ports:
7      - "3001:3001"
8    volumes:
9      - uptime_kuma_data:/app/data
10    environment:
11      - UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=false
12    networks:
13      - uptime-net
14    restart: unless-stopped
15
16  mariadb:
17    image: mariadb:11
18    environment:
19      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
20      MYSQL_DATABASE: ${MYSQL_DATABASE}
21      MYSQL_USER: ${MYSQL_USER}
22      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
23    volumes:
24      - mariadb_data:/var/lib/mysql
25    networks:
26      - uptime-net
27    restart: unless-stopped
28
29  nginx:
30    image: nginx:alpine
31    ports:
32      - "80:80"
33      - "443:443"
34    volumes:
35      - ./nginx.conf:/etc/nginx/nginx.conf:ro
36      - ./certs:/etc/nginx/certs:ro
37    depends_on:
38      - uptime-kuma
39    networks:
40      - uptime-net
41    restart: unless-stopped
42
43volumes:
44  uptime_kuma_data:
45  mariadb_data:
46
47networks:
48  uptime-net:
49    driver: bridge
50EOF
51
52# 2. Create the .env file
53cat > .env << 'EOF'
54# MariaDB Configuration
55MYSQL_ROOT_PASSWORD=secure_root_password
56MYSQL_DATABASE=uptime
57MYSQL_USER=uptime
58MYSQL_PASSWORD=secure_mysql_password
59EOF
60
61# 3. Start the services
62docker compose up -d
63
64# 4. View logs
65docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/uptime-kuma-stack/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

uptime-kumamariadbnginx

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download