Configuration¶

Most of Uptime Kuma is configured in its web dashboard: monitors, notifications, status pages and settings. This page covers the files on the instance behind it, and how to change them safely.

Where things live¶

Path	What it is
`/var/lib/uptime-kuma/`	Data directory, including the SQLite database `kuma.db`
`/etc/uptime-kuma/admin.password`	The first-boot admin password (root only, mode 0600)
`/etc/uptime-kuma/tls/cert.pem`	This instance's self-signed certificate
`/etc/uptime-kuma/tls/key.pem`	Its private key (root only, mode 0600)
`/etc/nginx/sites-available/uptime-kuma.conf`	The HTTPS proxy on port 8443
`/etc/systemd/system/uptime-kuma.service`	The service unit, including host, port and data directory
`/opt/uptime-kuma/`	The application
`/opt/sushi/node/`	The pinned Node.js runtime

Monitors and notifications¶

Add and edit monitors in the dashboard. This image supports HTTP, TCP, DNS and ping checks. Browser monitors are not available, because Chromium is not installed.

Webhook notifications to an address you choose work out of the box. Apprise is not installed, so notification types that depend on it do not work.

Monitors you add make their own outbound connections from the instance. Make sure the instance can reach your targets, for example through its VPC routes and security group egress rules.

Status pages¶

Create status pages in the dashboard. They are served through the same loopback HTTPS proxy as the dashboard, so they are private to the instance until you choose to publish them.

Service settings¶

The Uptime Kuma service is set in /etc/systemd/system/uptime-kuma.service:

Environment=UPTIME_KUMA_HOST=127.0.0.1
Environment=UPTIME_KUMA_PORT=3001
Environment=DATA_DIR=/var/lib/uptime-kuma/
Environment=UPTIME_KUMA_DB_TYPE=sqlite

Keep Uptime Kuma itself on 127.0.0.1. nginx terminates HTTPS in front of it.

Change the HTTPS proxy¶

The proxy listens on 127.0.0.1:8443 and [::1]:8443 and forwards to http://127.0.0.1:3001. After you edit /etc/nginx/sites-available/uptime-kuma.conf, check and apply it:

sudo nginx -t
sudo systemctl reload nginx

Publishing the dashboard or a status page

Making the proxy reachable from other hosts is a change you make on purpose: change the listen lines to a private address, allow only your own network in the security group, and use a certificate your users trust. Do not turn off Uptime Kuma's authentication.

Change the admin password¶

Change the password in the dashboard settings. The file /etc/uptime-kuma/admin.password is used only once, to create the account, and is not updated when you change the password, so it then holds the old value. Keep it private either way.

The walkthrough checks the defaults

demo.sh and the self-test it runs check the image's default settings. After you change the configuration, they can report a failure even when your setup works. Run them on a fresh instance, before you make changes.

Next: Operations.