Skip to content
Monitoring

Set up Uptime Kuma for uptime monitoring

Step-by-step guide to set up Uptime Kuma on a dataforest Seed, monitor websites and services, send alerts and publish a public status page.

Tested with Uptime Kuma 2.5.12

TopicsUptime Kuma · Monitoring · Status Page · Docker · Caddy
Level Easy
Read9 min
Words1.550
AuthorLaurenz Seipel
PublishedNovember 12, 2026

Install in one click

The Seed runs the installation steps from this guide on its first boot. The software is ready a few minutes after you create it.

Details on Uptime Kuma

This guide shows how to set up Uptime Kuma on a Seed of your own, as a one-click app or with Docker Compose and Caddy. You then create your first monitors, set up notifications and publish a status page. With the one-click app this takes about 10 minutes.

What is Uptime Kuma?

Uptime Kuma regularly checks whether your websites, servers and services are reachable, and alerts you as soon as something goes down. Everything happens in a web interface.

  • Monitors: HTTP(S) with status code or keyword, TCP ports, ping, DNS, TLS certificates, databases and more.
  • Push monitors: cron jobs and backup scripts report in themselves. If the report does not arrive, you get an alert.
  • Notifications: email, Telegram, Slack, Microsoft Teams, webhooks and many other services.
  • Status pages: public pages where your customers see the state of your services.

Uptime Kuma is open source (MIT license) and keeps everything in a SQLite database.

Why a Seed of its own?

If Uptime Kuma runs on the same server as your website, it goes down with it and can no longer warn you. So run it on a Seed of its own, separate from the systems it monitors. For an overview of monitoring on dataforest cloud, see our monitoring solution.

Prerequisites

  • A Seed with an IPv4 address. The smallest model with 1 vCPU and 2 GB of RAM is enough to start. With the one-click app, the console adds the IPv4 address automatically.
  • SSH access to the Seed
  • Optionally your own domain (e.g. status.your-company.com) whose A record points to the Seed's IPv4 address. Without a domain, you reach Uptime Kuma under the Seed's hostname.

Path A: One-click app

1. Create the Seed

When you create the Seed, choose the app Uptime Kuma under App. Two settings are optional:

  • ADMIN_USERNAME sets the username of the admin account, the default is admin.
  • LETSENCRYPT is set to on, so the Seed gets a Let's Encrypt certificate. With off it uses a self-signed certificate.

The Seed generates the password itself.

2. Get your login details

The installation is done after 1 to 3 minutes. Then connect to the Seed via SSH:

bash
cat /root/ready.txt
cat /root/uptime-kuma-credentials.txt

ready.txt names the address of Uptime Kuma, the credentials file holds username and password. If you find /root/failed.txt there instead, it gives the reason. The initial setup is already done, so nobody else can create an admin account at the address.

3. Set up your own domain

The address appears in notifications and on your status pages, so a domain of your own pays off from the start. Once its A record points to the Seed, switch over via SSH:

bash
seed-tls domain status.your-company.com

Uptime Kuma gets a Let's Encrypt certificate, and the previous hostname redirects to the domain.

Continue with Create your first monitors.

Path B: Installation with Docker Compose

This path suits you if you run Uptime Kuma on an existing Seed or want to set every option yourself.

1. Install Docker

bash
curl -fsSL https://get.docker.com | sh

2. Create the directories

bash
mkdir -p /opt/uptime-kuma/data /opt/uptime-kuma/caddy && cd /opt/uptime-kuma
chown 1000:1000 data

Uptime Kuma does not run as root in the container but as user 1000. That is why this user owns the data directory.

3. Create the Caddyfile

Caddy accepts the HTTPS connections, gets a Let's Encrypt certificate automatically and passes the requests on to Uptime Kuma. Create the file caddy/Caddyfile:

text
status.your-company.com {
    reverse_proxy uptime-kuma:3001
}

4. Create compose.yaml

yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.12-rootless
    restart: always
    environment:
      TZ: Europe/Berlin
      UPTIME_KUMA_DB_TYPE: sqlite
    volumes:
      - ./data:/app/data

  caddy:
    image: caddy:2-alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy:/etc/caddy:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - uptime-kuma

volumes:
  caddy_data:
  caddy_config:
  • Uptime Kuma is only reachable through Caddy, and port 3001 stays closed to the outside.
  • UPTIME_KUMA_DB_TYPE: sqlite selects the built-in database and skips the database choice on first access.
  • ./data holds the database and uploaded files such as status page logos.

5. Start and create the admin account

bash
docker compose up -d

After about a minute Uptime Kuma is reachable. Then open https://status.your-company.com right away and create the admin account. Until you do, anyone who knows the address can claim this account.

6. Adjust the settings

  • Settings > Reverse Proxy: set Trust Proxy to Yes. Otherwise Uptime Kuma sees Caddy's IP address instead of the real ones.
  • Settings > General: enter your address as Primary Base URL, for example https://status.your-company.com. Uptime Kuma links to it in notifications.

The one-click app sets both for you.

Create your first monitors

Click Add New Monitor and choose the Monitor Type. Three are enough to get started:

  • HTTP(s): checks whether a URL answers. In the Advanced section, turn on Certificate Expiry Notification and Uptime Kuma warns you in time about an expiring TLS certificate.
  • HTTP(s) - Keyword: also checks that a certain text appears on the page. This also catches a web server that only serves an error page.
  • TCP Port: checks whether a service accepts connections, such as a mail server or a database.

By default Uptime Kuma checks every 60 seconds. Retries sets how many failures in a row trigger an alert. One or two retries avoid false alarms from short network hiccups.

Monitor cron jobs and backups with push

With a Push monitor, Uptime Kuma does not ask, your script reports in. Create a monitor of type Push, copy the URL it shows and call it at the end of your script:

bash
curl -fsS -m 10 "https://status.your-company.com/api/push/AbCdEf123?status=up&msg=OK"

If the script does not run or stops early, the report does not arrive and Uptime Kuma raises an alert. Set the interval a little longer than the time between two runs, about 25 hours for a daily backup.

Set up notifications

Open Settings > Notifications and click Set Up Notification. Choose the service, for example Email (SMTP) or Telegram, and check the setup with Test. Two options save work:

  • Default enabled attaches the notification to every new monitor.
  • Apply on all existing monitors adds it to all monitors you already have.

For important services, set up two channels, such as email and a messenger. If one fails, the alert still reaches you.

Publish a status page

A status page shows your customers whether your services are running, without them having to ask your support team.

  1. Open Status Pages and click New Status Page.
  2. Enter a name and a slug, for example customers. The page is then available at /status/customers.
  3. Use Add Group to create groups such as "Website" or "API" and assign monitors to them.
  4. Click Save.

The status page is public. It shows only the monitors you assign to it, under their friendly name, but no URLs or hostnames.

To show the status page directly on your domain, choose it as Entry Page under Settings > General. The dashboard stays available at /dashboard.

On path B, the status page can also get its own domain, such as status.your-company.com next to uptime.your-company.com for the dashboard. Add a second block with that domain and reverse_proxy uptime-kuma:3001 to caddy/Caddyfile, reload Caddy with docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile and enter the domain under Domain Names on the status page.

Secure access

The dashboard shows which systems you run and where they can be reached. So set up two-factor sign-in with Set Up 2FA under Settings > Security. Change Password is in the same place, for example if you share the account with others.

Set up backups

All monitors, notifications, status pages and the history live in /opt/uptime-kuma/data/kuma.db. sqlite3 creates a consistent backup while it runs:

bash
apt install -y sqlite3
mkdir -p /opt/backups
sqlite3 /opt/uptime-kuma/data/kuma.db ".backup '/opt/backups/kuma-$(date +%Y%m%d).db'"

For a daily backup at 03:00, add the command with crontab -e. In cron, every % must be written as \%:

text
0 3 * * * sqlite3 /opt/uptime-kuma/data/kuma.db ".backup '/opt/backups/kuma-$(date +\%Y\%m\%d).db'"

A backup on the same Seed does not help if the Seed fails. So copy the files to another system regularly, or add dataforest cloud's offsite backups.

Update Uptime Kuma

Before an update, read the release notes and take a snapshot of the Seed. Then set the new version, on path B in the image in compose.yaml, with the one-click app under KUMA_IMAGE in /opt/uptime-kuma/.env, and run:

bash
cd /opt/uptime-kuma
docker compose pull
docker compose up -d

Your data is kept. You find the installed version under Settings > About.

Troubleshooting

No HTTPS certificate: Use dig +short status.your-company.com to check that the A record points to the Seed. Details are in docker compose logs caddy on path B and seed-tls status with the one-click app.

The dashboard keeps reconnecting: Uptime Kuma needs a WebSocket connection. If another proxy or a firewall sits in front of Caddy, it must let WebSocket connections through.

Forgot your password:

bash
cd /opt/uptime-kuma
docker compose exec uptime-kuma npm run reset-password

False alarms: Raise Retries and check whether a firewall or bot protection blocks requests from the Seed.

Summary

Uptime Kuma now runs on a Seed of its own, separate from the systems it monitors. It checks your services around the clock, reports outages and shows your customers on a status page what is going on. For insight into CPU, memory and disk usage, a Checkmk monitoring server completes the picture.

Install in one click

The Seed runs the installation itself on its first boot.

Ready to get started?

Create your first Seed and start deploying in minutes.

Back to overview