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_USERNAMEsets the username of the admin account, the default isadmin.LETSENCRYPTis set toon, so the Seed gets a Let's Encrypt certificate. Withoffit 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:
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:
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
curl -fsSL https://get.docker.com | sh
2. Create the directories
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:
status.your-company.com {
reverse_proxy uptime-kuma:3001
}
4. Create compose.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: sqliteselects the built-in database and skips the database choice on first access../dataholds the database and uploaded files such as status page logos.
5. Start and create the admin account
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:
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.
- Open Status Pages and click New Status Page.
- Enter a name and a slug, for example
customers. The page is then available at/status/customers. - Use Add Group to create groups such as "Website" or "API" and assign monitors to them.
- 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:
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 \%:
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:
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:
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.
