Uptime Kuma setup with Docker, HTTP checks, and a status page
Deploy Uptime Kuma v2 on Docker, configure HTTP checks and notifications, publish a status page, and back up the SQLite volume before upgrading.
An order API can pass Uptime Kuma's check inside a VPC while customers still hit a broken public gateway. The internal result is useful. It tells you which path worked. Before setting up the monitor, decide which failure it needs to catch and where the request should originate.
Uptime Kuma is a self-hosted uptime monitor. It runs scheduled checks, sends notifications and can publish selected results on a status page. This guide sets up a single Kuma v2 instance in Docker and walks through an HTTP check from that instance's network.
Keep the data on a local volume
Use a Docker host that supports the v2 image. With the default SQLite backend, /app/data needs a filesystem that supports POSIX file locking. Use a local volume or directory. Some NFS setups have locking problems that can corrupt the database. Uptime Kuma installation guide
docker run -d --restart=unless-stopped \
-p 127.0.0.1:3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:2
The volume keeps the data when you replace the container. The restart policy can bring the container back after an exit while Docker and the host are running. The example binds port 3001 to loopback. On Docker Engine versions earlier than 28.0.0, other hosts on the same Layer 2 network can still reach a port published to loopback. Open http://127.0.0.1:3001 on the Docker host and create the administrator account. From another machine, use an SSH tunnel for setup. If you later publish an HTTPS endpoint, configure the reverse proxy to pass WebSocket upgrades. Docker port publishing · Kuma reverse proxy setup
Check what a caller needs from the endpoint
Suppose a read-only checkout readiness endpoint should return HTTP 200 and the marker checkout-ready. Use HTTP(s) - Keyword if you need both conditions. A plain HTTP monitor checks the accepted status code after a successful request. The keyword monitor also looks for a substring in the response. Choose a marker absent from proxy error pages and keep it stable across releases.
| Monitor | What a successful check establishes |
|---|---|
| HTTP(s) / HTTP(s) - Keyword | The request met the configured status condition. With Keyword, it also passed the content check. |
| TCP Port | A connection to the port succeeded. A database login or query needs a separate check. |
| Ping | The target responded to ICMP from this network. An ICMP filter can cause a failed check. |
| DNS | The configured resolver answered for the requested record type. |
| Docker Container | The configured Docker host reported the container's state. Kuma also considers a health check when the container exposes one. |
Docker Container monitoring requires access to a configured Docker endpoint. Access to the daemon can grant extensive control over the host, so keep it separate from the HTTP setup and restrict it deliberately. Kuma v2.5.9 monitor implementation · Docker daemon access
Exercise the failure and the recovery
Start with the heartbeat interval, request timeout, retry count and retry interval. More retries let a brief failure clear before an alert, at the cost of later detection. When retries are configured for an ordinary HTTP check, failed attempts can show as Pending before Kuma records Down.
Set up a notification channel, send its test message, and enable it on the monitor. Then use a test endpoint to produce a failing status or omit the required keyword until Kuma reaches Down. Restore the normal response and verify that both the failure and recovery arrive at the intended destination. This checks the monitor-to-notification path in addition to the channel itself.
Publish only the monitors readers need
Create a status page and add the checks that represent the services you want people to see. Give the checks names that make sense outside the operations team. Open the page in a signed-out browser and inspect the groups, recent history and incident text before sharing it. A status page hosted by the same Kuma instance shares that instance's availability.
If customers enter through a public gateway, keep the internal Kuma check and add an independent HTTP check on the public path. With Guance HTTP synthetic testing, choose a public testing node and configure the same expected status and response marker. If the public check fails while the internal one passes, compare their DNS, TLS and gateway paths before assigning the cause. Separately connected application logs and traces can help locate where a failing request stopped. Kuma v2 also has a distinct Globalping monitor type for supported external probes. Ordinary HTTP and TCP checks in this setup originate from Kuma itself.
For private services, run Kuma where the target is reachable. To detect loss of Kuma itself, use a reachable HTTPS endpoint or independent heartbeat from another host, with a notification path that remains available if Kuma goes down. A TCP check on the port alone confirms only a connection. What uptime monitoring measures
Back up the volume before upgrading
For the local SQLite setup above, stop the writer and archive the entire data directory. This briefly interrupts checks and any status pages the instance serves. Run the commands from a directory where the backup file can be created.
docker stop uptime-kuma &&
docker run --rm \
-v uptime-kuma:/data:ro -v "$PWD:/backup" \
busybox:1 tar -czf /backup/kuma-backup.tar.gz -C /data . &&
tar -tzf kuma-backup.tar.gz &&
docker start uptime-kuma
If the archive or verification step fails, run docker start uptime-kuma to restore monitoring, then redo the backup before upgrading. Keep a copy of the verified archive outside the Docker host. With an external database, back up that database separately. For a v1-to-v2 upgrade, start with the official migration guide. Keep v1 stopped after making the backup, replace the old container with v2 using the existing volume, and follow the migration logs. Only one instance should write to the SQLite volume. To roll back, restore the pre-upgrade archive to a separate volume and start the previous version with it. The upstream guide advises against using the rootless image for the initial v1-to-v2 migration. Official v1-to-v2 migration guide
Contact us
Join the community
to join the community
Try Guance
Start online and pay only for what you use.
Get startedChoose a Guance plan
