What is Uptime Kuma?

Uptime Kuma is a self-hosted monitoring tool. It checks websites, TCP ports, DNS records, Docker containers, and more at regular intervals, sends a notification when something goes down, and can publish status pages. The project provides an official image, louislam/uptime-kuma, which listens on port 3001 and keeps everything in a /app/data folder.

Tool description

This tool builds a compose.yaml for Uptime Kuma. It starts from the file in the Uptime Kuma repository and adds the settings people usually need: the image version and variant, the host port and bind address, where the data is stored, access to the Docker socket for Docker host monitors, and the database. With a database of MariaDB in its own container, the tool adds a second service with a health check, so Uptime Kuma only starts once the database is ready. Settings the form has no field for can be added as environment variables. Everything is created in your browser.

Features

  • The 2, 1, and beta image tags, with the standard, slim, rootless, and slim rootless variants of version 2
  • Host port, and a bind address such as 127.0.0.1 for use behind a reverse proxy
  • A data folder on the host or a named Docker volume, which is declared for you
  • Optional access to /var/run/docker.sock for Docker host monitors, with a warning about what it allows
  • SQLite, the embedded MariaDB, a MariaDB container added to the file, or an external MariaDB server
  • A generated database password, with $ signs escaped so Compose keeps them
  • Options for embedding in an iframe, the WebSocket origin check, and a Cloudflare Tunnel token
  • Any other environment variable, comments that explain the file, and a download as compose.yaml

Examples

The default settings give the same file as the one in the Uptime Kuma repository:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Choosing a MariaDB container as the database adds a mariadb service and connects Uptime Kuma to it with UPTIME_KUMA_DB_TYPE, UPTIME_KUMA_DB_HOSTNAME, and the other UPTIME_KUMA_DB_* variables.

Tips

  • Save the result as compose.yaml in an empty folder and start it with docker compose up -d. Then open http://localhost:3001
  • File systems like NFS are not supported for the data folder. Use a local folder or a Docker volume
  • Slim images do not include Chromium, which the real browser monitor needs, and they do not include the embedded MariaDB
  • Rootless images run as the node user with UID 1000, so a data folder on the host must be writable by that user
  • Uptime Kuma uses WebSockets. When you put it behind a reverse proxy, the proxy has to pass the Upgrade and Connection headers
  • The Docker socket gives Uptime Kuma full control over Docker on the host. Only mount it when you need Docker host monitors, and do not expose Uptime Kuma to the internet
  • Version 1 only supports SQLite, so the database options are hidden for it
  • Password fields end up in the file in plain text. Keep the file private, or move the password to an .env file and reference it as ${DB_PASSWORD}