Uptime Kuma Docker Compose: 129 MiB Idle, 30 Monitors

This Uptime Kuma Docker Compose file runs one container, louislam/uptime-kuma:2.5.7, with SQLite in a named volume and the web interface on 127.0.0.1:3001. We tested it on Oct 26, 2026 as the median of three runs on a 2-vCPU GitHub Actions runner. A fresh install with an admin account and no monitors idled at 129 MiB (range 128 to 129). With 30 monitors checking every 20 s for 10 minutes it peaked at 146 MiB (144 to 147), and all 928 heartbeats stored in each run were up. The highest reading in any run, 158.5 MiB, came at startup, so by our sizing rule it needs 1 GB of RAM.

Verified compose file

One service, uptime-kuma, and one named volume. The image is pinned to a full v2 release, with the digest we tested in a comment, so an upgrade is a step you take on purpose. Uptime Kuma’s Docker Tags wiki page lists 2 as the recommended floating tag for the latest v2 release and calls latest deprecated, “always pointing to v1”. The comments in the file are the lab’s.

# Verified compose for Uptime Kuma, tested 2026-10-26 by the SelfHostBench lab (3 runs; the figures are the median).
# Lab host: AMD EPYC 9V45 96-Core Processor, 2 vCPU, 7.8 GiB RAM, x86_64, Docker 28.0.4.
# Floating image tags below were replaced by the version resolved at test time;
# the registry digest is in the comment on each image line.
# Measurements: uptime-kuma.json (schema 3).
# Lab difference: Adds a `target` container (nginx 1.30.6-alpine, answers 200 on every path, no access log) that the 30 monitors watch, so the test sends no traffic outside the Compose network. The published file has Uptime Kuma alone.

# Uptime Kuma 2.5.7: self-hosted uptime monitor. Single container, SQLite in /app/data.
# Pinned to a full v2 release so upgrades are a deliberate step (the floating `2` tag follows the v2 stable line; `latest` still pointed at v1 as of 2026-10).
# UPTIME_KUMA_DB_TYPE=sqlite picks the database up front. Without it v2 opens a "setup database" wizard (SQLite or MariaDB) on the first visit
# and does not start until you have answered it. Wiki: https://github.com/louislam/uptime-kuma/wiki/Environment-Variables
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.7  # sha256:4b95dbe7ac5343b768f8e04e3035ccd59997872b1a35ab9b0f082d2cc279070e  (version 2.5.7, from exec)
    restart: unless-stopped
    environment:
      # Use the built-in SQLite database (/app/data/kuma.db) and skip the database wizard. The first visit then asks for the admin account only.
      UPTIME_KUMA_DB_TYPE: sqlite
    volumes:
      # Monitors, history and settings. Back this up.
      - kuma-data:/app/data
    ports:
      - "127.0.0.1:3001:3001"

volumes:
  kuma-data:

How it differs from the compose file in the project’s repository: that file uses the floating 2 tag, a ./data bind mount and publishes 3001:3001 on all interfaces. Ours pins 2.5.7, uses a named volume, binds the port to 127.0.0.1 and sets the database up front (next section). The port binding means the interface is not reachable from other machines until you put a reverse proxy in front or change the port line. Uptime Kuma’s installation wiki page maps /app/data to a directory or volume and warns that SQLite needs a filesystem with POSIX file locks: NFS is its example of a place where locking problems appear. Keep the volume on local disk.

The database choice

Uptime Kuma 2 asks which database to use on the first visit, and the server does not start until you answer. The published file avoids the question with one line, UPTIME_KUMA_DB_TYPE: sqlite. The official environment variables page lists that variable (sqlite or mariadb, since 2.0.0) and a flag for an embedded MariaDB, which it lists under “For Development only”.

We ran both versions of the file on 2.5.7 on a fresh volume (manual check, Oct 27, 2026; raw output in lab/notes/uptime-kuma-2026-10-26.md, sections 2 and 3):

Without the setting the container still passes its health check, so docker compose up -d --wait reports it healthy while it waits for a browser. In all three lab runs the setup step confirmed the other case: the server answered that it needed no database setup, we created the admin account through the same Socket.IO API the web page uses, and a login worked. The lab’s idle figure is therefore a running Uptime Kuma with an admin account and no monitors. We did not try MariaDB, embedded or external.

Install steps

We ran the harness steps in all three lab runs: docker compose up -d, an HTTP check on http://uptime-kuma:3001/ that expected status 200, and the account step above. The other commands below ran by hand on our sandbox host on Oct 27, 2026 (Docker 29.6.2, Compose 5.3.1), one time each, on 2.5.7; the raw output is in lab/notes/uptime-kuma-2026-10-26.md.

1. Install Docker Engine with the Compose plugin.

2. Make a folder and save the file above as compose.yaml in it. The download link is on the block.

   mkdir uptime-kuma
   cd uptime-kuma

3. Start it. --wait returns when Docker reports the container healthy. The first start pulls 616.8 MB (compressed).

   docker compose up -d --wait

   The image ships its own health check (extra/healthcheck; interval 60 s, start period 180 s, per docker inspect), which is why the compose file has none.

4. Open http://127.0.0.1:3001/. On a remote machine, use an SSH tunnel, or put a reverse proxy in front (see Gotchas). Not run in our lab: the pages in a browser. The root address redirected to /dashboard, and the server log said No user, need setup.

5. Create the first account. We created ours through the API with a script, and it reported the account created and a working login; a browser was not used.

To stop it, docker compose down removes the container and keeps the named volume. Adding -v deletes the volume, which holds your monitors, history and settings.

Measured resources

Source: uptime-kuma.json, three runs on Oct 26, 2026, each from a fresh stack with docker compose up -d, on the lab host (a GitHub Actions ubuntu-latest runner: 2 vCPU AMD EPYC 9V45, 7.8 GiB RAM, Docker 28.0.4, Compose 2.38.2). Every figure is the median of the three runs with the range, lowest to highest (why we repeat runs). Each run went through three states:

• Idle: an admin account, no monitors. The figure is the mean of the samples over about 31 s, taken after the container’s memory had settled (124.3 s after it was healthy, 123.4 to 125.3 over the three runs; rule on the methodology page).
• Startup peak: the highest reading between healthy and settled.
• 30 monitors: 25 HTTP, 3 TCP port and 2 ping monitors, each at a 20 s interval with no retries and no notifications, added through the API and left running for 10 minutes with no dashboard open. That is 30 checks every 20 s, about 90 a minute. All 30 pointed at one stock nginx container on the Compose network that answers 200 on every path, so no traffic left the lab.

That nginx container, target, is in the lab’s second compose file and not in the file above. Every RAM figure on this page and in the Test box is the Uptime Kuma container alone and leaves target out. It used 3.25 MiB at idle; the result file’s own stack totals add it (131.74 MiB idle, 149.74 MiB peak).

The highest CPU sample sits in the first seconds, while the 30 monitors are created (0.4 to 0.5 s in the three runs); the mean over the 10 minutes is the number to plan with. The heartbeats are what the database held after the window, read back through the API: 775 from the HTTP monitors, 93 from the TCP monitors and 60 from the ping monitors in every run, none down, and all 30 monitors were created in each run. The container did not restart and was not killed for memory in any run. Peak RAM is the highest sample (about one every 2 to 3 s) of the 10-minute window; shorter spikes between samples are not seen.

The compressed size is the registry’s number for linux/amd64. The unpacked size is what Docker reports on the lab host, which uses the classic overlay2 image store. Docker Engine 29 and later uses the containerd store on fresh installs, which also keeps the compressed layers; for disk we plan for unpacked plus compressed size plus 10% (how we size disk), which is 2,600 MB for this image.

What the numbers say:

• The container used 129 MiB at idle with an account and no monitors. During the 10 minutes with 30 monitors its RAM averaged 142.8 MiB, about 14 MiB above idle, and its highest reading was 146.0 MiB. CPU averaged 1.5% of one core on the lab host.
• By our sizing rule (the highest reading in any run, 158.5 MiB, times 1.5, rounded up to 1, 2, 4, 8, 16 or 32 GB) it needs 1 GB. The highest reading came at startup, not under the 30-monitor load. For comparison, our Home Assistant Docker Compose guide measured 309 MiB idle.
• The load is light: 30 checks against a container on the same network, answered in about a millisecond (the mean response time of the UP heartbeats was 1.1 to 1.4 ms). A real install also pays for DNS lookups and TLS handshakes to other people’s sites, which these checks do not show.

Gotchas, upgrade and backup

Reverse proxy: WebSockets

The reverse proxy wiki page says Uptime Kuma is based on WebSocket, so the proxy has to pass the Upgrade and Connection headers (Nginx Proxy Manager has a “WebSockets Supports” switch). It gives this Caddy example for a proxy on the same machine. Not run in our lab:

subdomain.domain.com {
    reverse_proxy 127.0.0.1:3001
}

The same page says to set Settings, Reverse Proxy, “Trust Proxy” to Yes when the app is reachable only through a proxy, so the logs show the real client address. For a working Caddy-in-front setup with HTTPS, see our Vaultwarden Docker Compose guide; we did not put Caddy in front of Uptime Kuma.

Tags: slim and rootless

The Docker Tags page says the full image includes the embedded MariaDB and Chromium (for the browser-engine monitor type) and that the -slim images omit both and are 300 to 400 MB smaller; it also lists -rootless tags with the warning that some features may not work. We tested the full 2.5.7 image only.

Run the monitor on a different machine

Our advice, not a measurement: a monitor on the same machine as the apps it watches cannot report that machine going down. A small separate host is the usual answer. At 129 MiB idle the container fits a 1 GB plan by our sizing rule (see Where to run it).

Update

Not run in our lab. Within v2, set the new tag and recreate the container:

docker compose pull
docker compose up -d

Back up first. We did not test any upgrade between 2.x versions.

Upgrading from 1.x

Not run in our lab; this is the official v1 to v2 migration page as we read it on Oct 26, 2026:

• Stop Uptime Kuma, then back up the data directory. The page says this is currently the only supported backup method.
• Change the image to louislam/uptime-kuma:2, start it with the same volume, and watch docker compose logs -f.
• The upgrade aggregates the heartbeat table into a new format. The page’s own example (20 monitors, 90 days of data) took about 7 minutes; the page warns it can take hours on slower hardware or with more monitors, and not to interrupt it. If it is interrupted, restore from the backup and retry.
• The page lists breaking changes, including Alpine-based images no longer being supported, rootless images not being recommended for the upgrade, new monitors defaulting to 0 retries, and JSON backup and restore being removed.
• Moving from SQLite to MariaDB is not officially supported, and the page advises against the third-party converter it names.

Back up and restore

The official guidance is the data directory, copied with the app stopped. We ran this on Oct 27 on 2.5.7 with SQLite, an empty database and one account. The volume is named <folder>_kuma-data by Compose; ours was uptime-kuma_kuma-data. We used the app image itself to run tar, so nothing else is pulled:

docker compose stop
mkdir backup
docker run --rm --user root -v uptime-kuma_kuma-data:/data:ro -v "$PWD/backup":/backup --entrypoint tar louislam/uptime-kuma:2.5.7 czf /backup/kuma-data.tar.gz -C /data .

The archive held kuma.db, db-config.json, upload, screenshots and docker-tls (14,599 bytes). tar ran as root, so expect the archive file to be owned by root on the host (we did not check). The restore below is a drill: we extracted the archive into a new empty volume and started a second container on that volume, next to the stopped stack, not in place of it:

docker volume create kumarestore
docker run --rm --user root -v kumarestore:/data -v "$PWD/backup":/backup:ro --entrypoint tar louislam/uptime-kuma:2.5.7 xzf /backup/kuma-data.tar.gz -C /data
docker run -d --name kumarestore -e UPTIME_KUMA_DB_TYPE=sqlite -v kumarestore:/app/data -p 127.0.0.1:3002:3001 louislam/uptime-kuma:2.5.7

The restored container did not ask for setup, and logging in with the original account succeeded (Successfully logged in user labadmin in its log). To remove the drill container and volume afterwards:

Not run in our lab.

docker rm -f kumarestore
docker volume rm kumarestore

Not tested: monitors and history in the backup, a backup taken while the container runs, a MariaDB setup, and restoring over a live volume. On a different app (Vaultwarden, SQLite) we showed that a plain copy of a running database file can look fine and still lose recent data; see how to back up self-hosted Bitwarden. We did not test that for Uptime Kuma, so stop the container first. For a tool that copies the archive off the machine on a schedule, see restic vs Borg vs Kopia, measured on one generated dataset.

What we did not measure

• More than 30 monitors, monitors with a shorter interval than 20 s or with retries, HTTPS and keyword monitors against real sites, notification providers, the status page feature, and an open dashboard (an open dashboard receives every heartbeat; ours was closed during the window).
• History growth and long-term memory: the window was 10 minutes, on a database that started empty.
• MariaDB (embedded or external), the -slim and -rootless images, and ARM hosts.
• Any update between versions.
• The setup pages and the dashboard in a browser, and a reverse proxy in front.

Related

• Other apps in the same format: the Vaultwarden Docker Compose guide (a password server, 25 MiB idle with Caddy), the Home Assistant Docker Compose guide (309 MiB idle) and the Immich Docker Compose guide, a stack where RAM decides the host.
• Another small always-on container for the same box: AdGuard Home vs Pi-hole v6, a DNS ad blocker pair measured the same way. We did not run it next to Uptime Kuma.
• How the lab measures RAM, CPU and image sizes: methodology. More apps: the self-hosted apps index.
• Official sources used on this page, read Oct 26, 2026 (the 2.5.7 release notes again on Oct 27): the Uptime Kuma wiki pages on installation, Docker tags, environment variables, the v1 to v2 migration and reverse proxy, the repository’s compose.yaml, and the release notes for 2.5.7. The pages were read through a web fetch tool that summarizes them, so quotes are limited to short phrases.