Monitor websites for free with Uptime Kuma

The steps below follow the README and wiki. Where a default value is quoted, it comes from the source code of the current release, 2.5.5 (16 September 2026), because the wiki doesn't list them.

#Before you start: where to run it

A monitor on the same machine as the thing it watches dies with it. If Uptime Kuma lives on your home Pi and the power goes, nobody gets told. For watching public websites, a small VPS or a different location is the sturdier choice. For watching your homelab from inside, the Pi is fine. Best VPS for self-hosting has options.

#Prerequisites

• A Linux machine with Docker and Compose. For a 64-bit Raspberry Pi, see step 1 of the Vaultwarden on a Raspberry Pi guide.
• Local storage for the data folder. The README says network file systems such as NFS are not supported. The install wiki explains that the data folder needs POSIX file locks "to avoid SQLite database corruption."

#Step 1: install with Docker Compose

These are the README's commands, unchanged:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

The file it downloads is short:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

Expected result: "Uptime Kuma is now running on all network interfaces (e.g. http://localhost:3001 or http://your-ip:3001)."

If you'll put a reverse proxy in front (step 7), the README suggests binding to localhost instead. Change the port line to "127.0.0.1:3001:3001".

#Step 2: first run

Open http://your-ip:3001. Version 2 first asks "Which database would you like to use?" The options are:

• SQLite, "a simple database file, recommended for small-scale deployments". Pick this unless you have a reason not to.
• Embedded MariaDB, built into the full Docker image.
• External MariaDB, where you supply the connection details.

Read one warning from the v1-to-v2 migration guide before choosing MariaDB: moving an existing SQLite database to MariaDB isn't officially supported, so choose once. Then Create your admin account. Uptime Kuma also supports 2FA (Set Up 2FA in the 2FA settings). Turn it on if the dashboard will be reachable from the internet.

#Step 3: add your first website monitor

Select Add New Monitor and fill in:

1. Monitor Type: HTTP(s).
2. Friendly Name: anything you'll recognise in an alert.
3. URL: the full address, for example https://example.com.
4. Heartbeat Interval: defaults to 60 seconds. The README lists 20-second intervals as the fastest option.
5. Retries: defaults to 0. The label's help text says this is the "maximum retries before the service is marked as down and a notification is sent". At 0, a single failed check pages you. Setting 1 or 2 filters out one-off blips, at the cost of a slightly slower alert.
6. Heartbeat Retry Interval: defaults to 60 seconds, and only applies while retrying.
7. Accepted Status Codes: 200-299 by default.

Save. Expected result: the monitor appears in the list and starts collecting heartbeats, with response times charted as they arrive.

#Watching for content, not just a 200

A site can return 200 OK and still be broken: a blank page, a "database error" template, a parked domain. Use the HTTP(s) - Keyword monitor type and enter a word that only appears when the page is healthy, such as your footer text. There's also HTTP(s) - Json Query for APIs. Both are in the README's list of monitor types, alongside TCP, ping, DNS record, push, Docker container and others.

#Certificate expiry

HTTPS monitors can warn you before a TLS certificate expires. On each monitor, tick Certificate Expiry Notification. It's off by default in the 2.5.5 source. The label's help text says the lead times are set in Settings. In 2.5.5 the default warning days are 7, 14 and 21.

(Some third-party guides quote other defaults, such as 14 and 7 days or 30 days. The values above come from the 2.5.5 source.)

#Step 4: set up notifications

In a monitor's edit screen, or in Settings, choose Set Up Notification and pick a service. The notification-methods wiki page points to the full list of native providers, plus Apprise for even more. Fill in the service's details (a bot token and chat ID for Telegram, SMTP settings for email, a webhook URL for Discord or Slack), then:

• Press Test, and don't move on until the test message actually arrives.
• Tick Default enabled if new monitors should use this channel automatically.
• Tick Apply on all existing monitors to attach it to the ones you already have.

Don't skip the last one. The app's own text is blunt: "Notifications must be assigned to a monitor to function."

#Step 5: publish a status page (optional)

Open Status Pages → New Status Page, give it a name and a Slug, and add the monitors you want to show. The Status Page wiki page lists what to expect:

• It's meant for the public, and it "will cache results for 5 minutes", so it lags the dashboard.
• You can run several status pages, and serve each on its own domain name. Point an A or CNAME record at the server, add the domain in the status page's settings, and pass the Host or X-Forwarded-Host header if a proxy is in front.

#Step 6: schedule maintenance windows

Before planned downtime, use Maintenance → Schedule Maintenance. The wiki says this temporarily disables notifications for the affected monitors, and shows your message on the selected status pages. Your phone stays quiet during the migration you already knew about.

#Step 7: put it behind HTTPS

If the dashboard or a status page will be public, the wiki recommends HTTPS. Uptime Kuma is "based on WebSocket," so a reverse proxy must pass the Upgrade and Connection headers. The wiki's non-Docker Caddy example needs no extra header lines:

subdomain.domain.com {
    reverse_proxy 127.0.0.1:3001
}

If Uptime Kuma is only reachable through the proxy, go to Settings → Reverse Proxy → HTTP Headers and set Trust Proxy to Yes, so logs show real client IPs (wiki).

cd "<YOUR docker-compose.yml DIRECTORY>"
docker compose pull
docker compose up -d --force-recreate

#What to do next

• Point it at the services from the other guides: your Vaultwarden server, Immich, your Next.js app on Coolify, or a DNS monitor on your Pi-hole or AdGuard Home.
• Coming from a hosted service? See the UptimeRobot alternatives.
• For image tags, MariaDB and Docker-container monitoring, read the Uptime Kuma profile. It explains why mounting the Docker socket hands the container control of the host.