DEV Community

Cover image for Deploying Uptime Kuma - Self-Hosted Status Page and Monitoring Tool
Vultr profile image Sanskriti Harmukh
Sanskriti Harmukh for Vultr

Posted on with Aashish Chaurasiya Originally published at docs.vultr.com

Deploying Uptime Kuma - Self-Hosted Status Page and Monitoring Tool

#docker #monitoring #selfhosted #traefik

Uptime Kuma is a self-hosted monitoring tool that tracks the availability of websites, APIs, TCP ports, DNS records, and other services. It provides a clean dashboard to display uptime metrics and trigger alerts through 90+ notification services, including email, Slack, and Telegram, when a service goes down or recovers. This guide deploys Uptime Kuma on a Linux server using Docker Compose behind a Traefik reverse proxy. By the end, you'll have a working Uptime Kuma instance with an active monitor, a notification channel, and a public status page.

Prerequisites

Before you begin, you need to:

  • Have access to a Linux-based server as a non-root user with sudo privileges.
  • Install Docker and Docker Compose.
  • Configure a domain A record, such as kuma.example.com, pointing to your server's public IP address.
  • Add your user to the docker group to run Docker commands without sudo, then start a new shell session to apply the change.

Set Up the Directory Structure and Environment Variables

The project directory holds the Docker Compose file, the persistent data directory, and the environment variables shared between the Traefik and Uptime Kuma containers.

1. Create the project directory:

$ mkdir ~/uptime-kuma
Enter fullscreen mode Exit fullscreen mode

2. Enter the project directory:

$ cd ~/uptime-kuma
Enter fullscreen mode Exit fullscreen mode

3. Create the persistent data directory for Uptime Kuma:

$ mkdir -p data
Enter fullscreen mode Exit fullscreen mode

4. Create the environment variable file:

$ nano .env
Enter fullscreen mode Exit fullscreen mode

5. Add the following variables to the file:

DOMAIN=kuma.example.com
LETSENCRYPT_EMAIL=admin@example.com
Enter fullscreen mode Exit fullscreen mode

Replace the following placeholders:

  • kuma.example.com: Your registered domain name pointing to the server's IP address.
  • admin@example.com: Your email address for Let's Encrypt certificate notifications.

Save and close the file.

Deploy with Docker Compose

Traefik and Uptime Kuma run as separate containers on a shared Docker network. Traefik terminates TLS on the configured domain and forwards requests to Uptime Kuma's internal port, keeping Uptime Kuma off the public internet entirely.

1. Create the Docker Compose file:

$ nano docker-compose.yaml
Enter fullscreen mode Exit fullscreen mode

2. Add the following configuration:

services:
  traefik:
    image: traefik:v3.7.11
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - kuma-net

  uptime-kuma:
    image: louislam/uptime-kuma:2.5.3
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    networks:
      - kuma-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kuma.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls=true"
      - "traefik.http.routers.kuma.tls.certresolver=le"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"

networks:
  kuma-net:
    driver: bridge
Enter fullscreen mode Exit fullscreen mode

Save and close the file.

In the above configuration:

  • traefik: The reverse proxy that listens on ports 80 and 443, redirects all HTTP traffic to HTTPS, and automatically provisions TLS certificates from Let's Encrypt using the HTTP challenge method.
  • uptime-kuma: The monitoring service that stores data in the ./data directory. The Traefik labels configure domain routing, enable HTTPS, and forward traffic to the Uptime Kuma application on port 3001.
  • kuma-net: A shared bridge network that allows Traefik and Uptime Kuma to communicate internally without exposing internal ports to the host.

3. Start all services in detached mode:

$ docker compose up -d
Enter fullscreen mode Exit fullscreen mode

4. Verify that all containers are running:

$ docker compose ps
Enter fullscreen mode Exit fullscreen mode

The output displays two running containers: Traefik and Uptime Kuma.

Configure Uptime Kuma

Uptime Kuma does not report any status information until you create an administrator account and configure at least one monitor.

  1. Open a web browser and navigate to the domain configured in the .env file. 
   https://kuma.example.com
Enter fullscreen mode Exit fullscreen mode

  1. On the database setup page, select SQLite, then click Next. SQLite requires no extra configuration and works with the single-container deployment in this guide. The MariaDB/MySQL option connects to a separate database server that this deployment does not provision.

  2. The account creation page appears. Enter a username, enter a strong password in both the Password and Repeat Password fields, then click Create.

  3. After you create the account, the Uptime Kuma dashboard opens. Click + Add New Monitor.

Uptime Kuma Dashboard

  1. Configure the monitor settings:
  • Monitor Type: Select the type of service to monitor. Choose HTTP(s) for websites and APIs, TCP Port for port-based services, or DNS for domain records.
  • Friendly Name: Enter a descriptive name for the monitor (for example, My Website).
  • URL: Enter the full URL of the service to monitor (for example, https://example.com).
  • Heartbeat Interval: Set the polling frequency in seconds. The default is 60.
  1. Click Save to activate the monitor. The dashboard adds the monitor with an Unknown status. The status updates to Up or Down after the first heartbeat check runs within 60 seconds.

Configure Alert Notifications

Uptime Kuma does not send alerts by default. You must configure a notification channel and assign it to individual monitors before it triggers on a status change.

  1. Click the profile avatar in the top-right corner and select Settings.
  2. Navigate to the Notifications tab and click Set Up Notification.
  3. Select a notification type from the dropdown. Supported channels include email (SMTP), Slack, Telegram, Discord, and PagerDuty, among others.
  4. Enter the required credentials or webhook URL of the selected notification channel.
  5. Click Test to send a test notification and verify the configuration is working.
  6. Click Save to confirm the notification setup.
  7. Open the settings for each monitor that should use this notification channel, select the notification from the Notifications list, and click Save.

Create a Status Page

A status page groups one or more monitors into a public view, separate from the administrator dashboard, so you can share it with users or team members without granting them access to the full Uptime Kuma interface.

  1. Click Status Pages in the top navigation bar.
  2. Click New Status Page.
  3. Enter a Name for the status page (for example, Service Status), then enter a Slug using only lowercase letters, numbers, and hyphens (for example, status creates the URL https://kuma.example.com/status/status). Click Next.
  4. The status page editor opens. The Title field is pre-filled with the name entered in the previous step. Add a Description if needed, then configure the remaining display settings as needed.
  5. Click Add Group to create a section, then use the Add a monitor dropdown to select a monitor and add it to the group.
  6. Click Save to publish the status page.
  7. Open the status page URL in a browser to verify it loads and displays the monitor statuses. 
   https://kuma.example.com/status/status
Enter fullscreen mode Exit fullscreen mode

Replace the path with the slug configured in step 3.

Next Steps

  • Add more monitors for your other websites, APIs, and internal services
  • Configure additional notification channels so different teams get alerted through their preferred tool
  • Build separate status pages for internal and public audiences
  • Explore Uptime Kuma's tag and group features to organize monitors at scale

For the full guide with additional tips, visit the original article on Vultr Docs.

Top comments (0)