Skip to content
zefıly
← All posts

Self-hosting Uptime Kuma 2: monitoring on your own server

4 min read

How to run Uptime Kuma 2 with Docker. The new database choice on first start, the reverse proxy settings it needs, where to run it so that it can actually tell you about an outage, plus backups and updates. Tested with 2.5.

Uptime Kuma checks your websites and services every minute and tells you when one stops answering. It is one container with a friendly interface, and it sends alerts to email, Telegram, Slack, Discord and many other channels.

We tested the commands here on 12 November 2026 with the image tag 2, which was Uptime Kuma 2.5.11 that day.

In short

  • One container, one volume (/app/data).
  • Version 2 asks on first start which database to use. SQLite is right for almost everybody.
  • The interface needs WebSocket support in the reverse proxy.
  • Our idle container used about 130 MB of memory.
  • Do not run it only on the server it monitors. If that server goes down, so does the alarm.

1. Start the container

docker volume create kuma_data

docker run -d --name uptime-kuma --restart unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v kuma_data:/app/data \
  docker.io/louislam/uptime-kuma:2

127.0.0.1:3001 keeps the port private; the web server in front adds HTTPS. The tag 2 follows the newest 2.x release. For full control, pin an exact version such as 2.5.11.

2. Reverse proxy

Uptime Kuma updates its pages over a WebSocket connection. Without the upgrade headers the page loads and then stays empty.

server {
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

3. First start: choose the database

This is new in version 2. The first visit is redirected to /setup-database, where you choose:

  • SQLite: a file in the data volume. Nothing else to run. Choose this unless you have a reason not to.
  • MariaDB: embedded in the container, or an external server. Useful for hundreds of monitors with long history.

After that you create the admin account. Do it at once: until it exists, whoever opens the address first becomes the administrator.

4. Add monitors

A good first set:

  • HTTP(s) for each website, with a keyword check so that an error page with status 200 still counts as down.
  • Certificate expiry, which is part of the HTTP monitor: get a warning days before a certificate runs out.
  • TCP port for databases and mail servers.
  • Ping for the server itself.
  • Push for cron jobs: the job calls a URL when it finishes, and Kuma alerts you when the call does not come.

Set up at least one notification channel and send a test message. A monitor that nobody hears is decoration.

5. Where to run it

A monitor on the same server as the website it watches has a blind spot. When the server loses power or network, the site is down and the monitor is down with it. Nobody is told.

Better:

  • Run Uptime Kuma on a different server, ideally at a different provider or at least in another region.
  • Or keep it where it is and add one external check of the Kuma instance itself.

A small, cheap VPS is enough for it.

6. Status pages

Uptime Kuma can publish status pages: a public page that shows chosen monitors and incidents. You can map a status page to its own domain, such as status.example.com. The admin interface stays behind your login.

If the admin interface should not be reachable by everybody, restrict the site by IP address or add a password in front, and leave only the status page path open.

7. Backups

Everything is in /app/data: the database, uploaded images and settings.

docker stop uptime-kuma
docker run --rm -v kuma_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/kuma-$(date +%F).tar.gz -C /data .
docker start uptime-kuma

Copy the archive off the server.

8. Updates

docker pull docker.io/louislam/uptime-kuma:2
docker stop uptime-kuma && docker rm uptime-kuma
# run the same docker run command again

Coming from version 1? The first start of version 2 migrates the database, and with a long history this can take a while. Back up the data volume first, and do not interrupt the migration.

With Zefily

Uptime Kuma is a one-click app in Zefily: a rootless container under the site's own Linux user, on 127.0.0.1 behind the web server with HTTPS and WebSocket support, with its data in a volume that survives updates. The site starts behind a password, and a First step notice reminds you to create the admin account. See Container apps.

Zefily also has its own uptime checks and status pages built into the panel. See Status pages.

Frequently asked questions

Which database should I choose for Uptime Kuma 2?

SQLite, unless you have hundreds of monitors. It is a file in the data volume and needs nothing else.

Why is the Uptime Kuma page empty behind nginx?

The interface uses WebSockets. Add the Upgrade and Connection headers and proxy_http_version 1.1 to the proxy configuration.

How much memory does Uptime Kuma use?

Our idle Uptime Kuma 2.5.11 container used about 130 MB. It grows with the number of monitors.

Should Uptime Kuma run on the same server as my sites?

Preferably not. If that server goes down, the monitor goes down too and sends no alert. Run it elsewhere, or add an external check of the monitor itself.

Where does Uptime Kuma store its data?

In /app/data inside the container. Back up that volume.

See Containers for running your own images with Zefily.

More posts

Black Friday & Cyber Monday

Before you go: lifetime plans are on sale

Pay once for a lifetime plan, or get 30% off the first year of any yearly plan.

Only 100 lifetime plans per plan. When they are gone, they are gone.

See the campaign

Amazing November

See the campaign →