Uptime Kuma with Docker Compose

That's genuinely all it takes. The rest of this page covers what the file does, the choices the v2 image tags give you, and the two catches people run into: storage and the Docker socket.

#The official compose file

This is the file from the repository as of 2026-09-29:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

The README's install steps are:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

A few notes on it:

• Port 3001 listens on all interfaces. The README suggests binding to 127.0.0.1:3001:3001 if you only want local access, which is the right choice when a reverse proxy sits in front.
• ./data must be on a local disk or a Docker volume. The README warns that NFS is not supported. The install wiki explains why: the data directory needs POSIX file locks to avoid SQLite corruption. Don't point it at a NAS share.
• The :2 tag tracks the latest v2 release. Pin a specific version if you'd rather control upgrades.
• Behind a reverse proxy, remember that Uptime Kuma uses WebSockets. The wiki says to pass the Upgrade and Connection headers, or the UI won't work.

If you'd rather not use Compose, the one-line equivalent from the README is docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2.

#Full vs slim image, and MariaDB

The Docker Tags wiki lists full, slim and rootless variants of the v2 image. The differences, as documented:

So if the search that brought you here was "uptime kuma docker compose mariadb", you have two routes. The full image can use its embedded MariaDB, which the wiki describes as a low-maintenance storage backend. Or you add a MariaDB/MySQL service to the compose file and point Kuma at it. The default is SQLite in the data directory.

One warning from the migration guide: moving an existing SQLite database to MariaDB isn't officially supported. Pick your backend before you build up history.

The wiki also says rootless images "may not work as expected" for some features, and aren't recommended when upgrading from v1 to v2.

#Monitoring Docker containers

Uptime Kuma can watch container state directly. To do that it needs to reach the Docker daemon, most simply by adding this to the compose file:

    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock

The wiki is clear about the cost. Exposing the socket (or the daemon's TCP port) gives Uptime Kuma full control of the Docker daemon on the host. If the container is compromised, so is the host. The wiki's advice is not to expose Uptime Kuma to the internet when you use this monitor type. For a public status page, consider plain HTTP or TCP checks instead.

#What it monitors

From the README:

• Monitor types: HTTP(s), TCP, HTTP(s) keyword, HTTP(s) JSON query, WebSocket, ping, DNS record, push, Steam game server and Docker containers
• Notifications: Telegram, Discord, Gotify, Slack, Pushover, SMTP email and "90+" services in total
• Check interval: as short as 20 seconds
• Status pages: multiple, each mappable to its own domain
• Also: ping charts, certificate info, proxy support, 2FA and a multilingual UI

Outside Docker, the non-Docker install needs Node.js 20.4 or newer, Git and pm2. It runs on major Linux distros and on Windows 10 / Server 2012 R2 (x64) or later. The README says FreeBSD, OpenBSD, NetBSD, Replit and Heroku are not supported.

#The one thing to plan for

A monitor on the same box as the things it watches goes dark at exactly the moment you need it. If that server dies, nothing sends the alert. Run Uptime Kuma on a separate small VPS, a Pi at home, or a second provider, and have it watch your main server from outside.

#Licence and activity

The repository licence is MIT. The latest release from the GitHub API is 2.5.5, published 2026-09-16. Its notes list a fix for a memory leak in the TCP monitor. The repo had 91,913 stars as of 2026-09-29.

#Related pages

If you're weighing it against a hosted service, see /alternatives/uptimerobot. Uptime Kuma also ships as a template in both self-hosted PaaS panels covered here (Coolify's templates/compose folder and Dokploy's templates repository both have one): /software/coolify and /software/dokploy. For a cheap separate box to run it on, see /best/vps-for-self-hosting.

This is a profile built from the project's README, wiki and releases. It is not a hands-on review.