Monitoring, checked 2026-09-07
Uptime Kuma: Docker configuration reference
Self-hosted uptime monitor with a websocket dashboard, SQLite or MariaDB storage and around 100 notification providers.
At a glance
- Image:
docker.io/louislam/uptime-kuma - Tags:
2,2.5.3,2-slim,2-rootless,2.5.3-slim-rootless - Licence: MIT
- Source: https://github.com/louislam/uptime-kuma
- Docs: https://github.com/louislam/uptime-kuma/wiki
Ports
| Port | What listens | Source |
|---|---|---|
3001 | HTTP listener for the dashboard and the socket.io connection the UI runs on. Route the proxy here. | source for port 3001 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
UPTIME_KUMA_PORT | No | Port the server binds. Resolution order in config.js is the CLI flag, then this, then PORT, then 3001. | 3001 | source for UPTIME_KUMA_PORT |
UPTIME_KUMA_HOST | No | Address the server binds. Falls back to HOST, except on FreeBSD where HOST is ignored. | 0.0.0.0 | source for UPTIME_KUMA_HOST |
UPTIME_KUMA_WS_ORIGIN_CHECK | No | Websocket origin policy. Defaults to cors-like. Setting it to bypass disables the check and logs a warning. | cors-like | source for UPTIME_KUMA_WS_ORIGIN_CHECK |
UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN | No | Drops the SAMEORIGIN frame restriction so the dashboard can be embedded in another page. | 1 | source for UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN |
UPTIME_KUMA_SSL_KEY | No | Serves TLS from the container itself. Not needed when a reverse proxy already terminates TLS. | /app/data/ssl/key.pem | source for UPTIME_KUMA_SSL_KEY |
UPTIME_KUMA_CLOUDFLARED_TOKEN | No | Starts the bundled cloudflared tunnel with this token instead of exposing the port. | eyJhIjoi... | source for UPTIME_KUMA_CLOUDFLARED_TOKEN |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/app/data | Database, uploaded icons and TLS material. Lose this and every monitor, notification and history is gone. | source for /app/data |
Behind a reverse proxy
- Route the domain to container port 3001, and pass websocket upgrades: the dashboard is socket.io and shows no data without them. source for this reverse-proxy note
- The server checks the websocket origin by default. A proxy that rewrites Origin needs UPTIME_KUMA_WS_ORIGIN_CHECK considered before reaching for bypass. source for this reverse-proxy note
- Terminate TLS at the proxy and leave the SSL variables unset. Setting both ends is the usual cause of a redirect loop. source for this reverse-proxy note
- Embedding the status page in another site needs UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN, not a proxy header change. source for this reverse-proxy note
What it needs alongside it
| Dependency | Why | Source |
|---|---|---|
| None for the default install | Storage is SQLite inside the data volume. MariaDB is optional and chosen during first-run setup on the 2.x line. | source for None for the default install |
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
2.5.3 | 2026-08-22 | No | Corrects a wrong version number shipped in 2.5.1. Read the 2.5.1 notes for what actually changed. | source for release 2.5.3 |
2.5.2 | 2026-08-22 | No | Fixes a broken non-Docker installation introduced in 2.5.1. | source for release 2.5.2 |
2.5.1 | 2026-08-22 | No | Adds SMS Gateway, ClickUp and TurboSMTP notification providers. | source for release 2.5.1 |
2.5.0 | 2026-08-01 | No | Adds the next-rootless image tag and allows check intervals longer than the previous 24 day ceiling. | source for release 2.5.0 |
2.4.0 | 2026-05-31 | No | Adds incidents to the RSS feed and several notification providers. | source for release 2.4.0 |
2.3.2 | 2026-05-03 | No | Reverts SQLite from multiple connections back to a single connection by default. | source for release 2.3.2 |
If it is not coming up
- WebSocket connection to 'wss://<your-domain>:6001/app/...' failed (UI shows "WARNING: Cannot connect to real-time service")
- Coolify volume data lost after redeploy / a new empty volume is created every deploy
- 502 Bad Gateway (Traefik) — build succeeds and container runs, but your-domain.com returns 502 Bad Gateway
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.