Appearance
Uptime Kuma
Prepare the Docker host using the Operations VM setup guide before configuring this service.
Uptime Kuma monitors service availability from the operations VM. It checks network endpoints rather than reading Docker state through the Docker socket. Nginx Proxy Manager provides HTTPS access to the dashboard.
For AI-assisted setup, SSH access, and private recovery procedures, see Uptime Kuma · Internal Operations.
Deployment and access
| Setting | Value |
|---|---|
| Host | Operations · Proxmox VM 100 |
| Host IP | 10.120.40.100 |
| Domain | up.home.rwk.me |
| Dashboard | https://up.home.rwk.me |
| Direct access | http://10.120.40.100:3001 |
| Compose directory | /docker/uptime-kuma |
| Application state | /docker/uptime-kuma/data |
| Database | Embedded MariaDB |
These are homelab access addresses; listing them here does not make the dashboard internet-accessible. Reachability depends on the client's network access.
Setup
Prepare the host
Use a Linux host with Docker Engine and the Docker Compose plugin installed. On this homelab, that is the operations VM. Use an account with permission to manage Docker and the project directory.
Before starting, choose:
| Configuration | This homelab | On another homelab |
|---|---|---|
| Host address | 10.120.40.100 | A stable address assigned to your Docker host |
| Dashboard domain | up.home.rwk.me | A hostname under a domain you control |
| Reverse proxy | 10.120.40.101 | Your proxy's address |
| Project directory | /docker/uptime-kuma | A local directory writable by your deployment account |
| Timezone | America/Chicago | Your IANA timezone |
Use your chosen values throughout the commands and proxy configuration. Allow the proxy to reach the host on TCP 3001, and allow Kuma to reach the services it will monitor. The Docker host's DNS must resolve those service names too.
Create the project directory on the VM's local Linux filesystem:
sh
mkdir -p /docker/uptime-kuma/data
cd /docker/uptime-kumaKeep application state, including the embedded database, on local storage rather than an SMB or NFS mount. This service has no NAS dependency.
Configure Docker Compose
Create compose.yaml in the project directory with this configuration:
yaml
services:
uptime-kuma:
image: louislam/uptime-kuma:2.5.8
container_name: uptime-kuma
environment:
TZ: ${TZ}
UPTIME_KUMA_ENABLE_EMBEDDED_MARIADB: "1"
volumes:
- ./data:/app/data
ports:
- "${SERVER_IP}:3001:3001"
security_opt:
- no-new-privileges:true
restart: unless-stoppedThe homelab repository retains the actual deployment file; this example explains how to configure the service independently. Pin a reviewed release rather than using latest, and check the release's upgrade instructions before changing it.
Create a .env file beside compose.yaml:
dotenv
SERVER_IP=10.120.40.100
TZ=America/ChicagoChange SERVER_IP to an address assigned to your Docker host and TZ to your timezone. The host binding publishes TCP 3001 on that address; the container still listens on port 3001. If you choose a different host port, change the left-hand port in Compose and use that port in the proxy and checks below.
The ./data:/app/data binding preserves accounts, monitors, notification settings, history, and database files when the container is replaced. UPTIME_KUMA_ENABLE_EMBEDDED_MARIADB enables the bundled database; no separate database container or database port is required. The restart policy starts Kuma again after a host reboot unless you explicitly stopped it.
Restrict the environment file and start the service:
sh
chmod 600 .env
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kumaThe port binds to the operations host's address. The container has no Docker socket, host root filesystem, extra Linux capabilities, or privileged mode.
Verify the backend
Check the container's health and confirm the direct endpoint responds before configuring the proxy:
sh
docker inspect --format '{{json .State.Health}}' uptime-kuma
curl --fail --silent --show-error --output /dev/null \
http://10.120.40.100:3001/Configure DNS and HTTPS
Make up.home.rwk.me resolve to the Nginx Proxy Manager address, 10.120.40.101, for the clients using the service. Configure a proxy host with these settings:
| Setting | Value |
|---|---|
| Domain | up.home.rwk.me |
| Forward scheme | http |
| Forward host/IP | 10.120.40.100 |
| Forward port | 3001 |
| WebSocket support | Enabled |
| SSL certificate | Let's Encrypt *.home.rwk.me |
| Force SSL | Enabled |
| HTTP/2 | Enabled |
| Block exploits | Enabled |
On this homelab, select the existing wildcard certificate. On another homelab, obtain a certificate covering your chosen dashboard name using your proxy's certificate setup, then enable HTTPS redirection. Store any DNS-provider credentials in your secret manager.
Use a dedicated hostname for Kuma rather than a subdirectory such as /uptime-kuma. WebSocket forwarding is required for the dashboard's live connection; see the upstream reverse proxy guide.
Complete first-run setup
For a fresh installation, open the HTTPS dashboard and create the administrator account. The Compose configuration enables embedded MariaDB. Save administrator credentials in 1Password.
An existing installation should retain its account, configuration, and monitoring history through the persistent data directory.
Add a monitor
- Select Add New Monitor in the dashboard.
- Choose HTTP(s) for a web application and enter a descriptive name.
- Enter the URL you want to test. A proxied HTTPS URL checks DNS, TLS, the proxy, and the application together. A direct backend URL isolates application reachability.
- Start with a 60-second heartbeat interval and two retries if brief failures should be retried before declaring the service down. These are starting values; tune them to the service's importance and expected behavior.
- Keep TLS verification enabled for HTTPS. Use a URL with a known successful response; for an authenticated application, prefer its health endpoint or deliberately configure the expected authentication response.
- Save and wait for checks to populate. Confirm that the result matches the application's actual state.
Use a TCP-port monitor to check whether a particular service port accepts connections, or a DNS monitor to test name resolution. These answer different questions: an open TCP port does not prove the application works. Monitor checks run from Kuma's container, so localhost refers to that container, not the host or another service.
Configure notifications
Open Settings → Notifications, add your notification provider, and enter its required delivery settings and credentials. Send a test notification, then enable that notification on each intended monitor. If offered, setting a default makes it easier to attach notifications to new monitors; check existing monitors separately.
For SMTP, use your provider's server, port, encryption mode, and supported authentication method. Keep tokens and app passwords in your secret manager. Confirm the Docker host can reach the delivery endpoint.
For an end-to-end test, create a temporary monitor against a controlled unavailable test endpoint and confirm a down notification arrives. Change that test monitor to a known working endpoint and confirm recovery. Remove it when finished. Avoid interrupting a real service merely to test alerts.
Organize the dashboard
Group related monitors and use clear names so an alert identifies the affected service. Keep the administrative dashboard authenticated. Publishing a status page is optional; select only the monitors and labels you intend to share rather than exposing your full internal inventory.
Restart without rebooting the host
Run on the operations VM:
sh
cd /docker/uptime-kuma
docker compose ps
docker compose restart uptime-kuma
docker compose psMonitoring is briefly interrupted. Wait for a healthy container, then verify both access URLs using the checks below. Restarting does not apply changes to Compose configuration; use a reviewed deployment for those changes.
Maintenance checks
Run on the operations VM:
sh
cd /docker/uptime-kuma
docker compose ps
docker compose logs --tail=100 uptime-kuma
docker inspect --format '{{json .State.Health}}' uptime-kumaCheck the direct backend and the complete HTTPS path separately:
sh
curl --fail --silent --show-error --output /dev/null \
http://10.120.40.100:3001/
curl --fail --silent --show-error --output /dev/null \
https://up.home.rwk.me/If direct access works but HTTPS fails, check DNS, the proxy route, and the certificate. Open the dashboard to verify live updates over WebSockets, inspect a representative monitor, and confirm notification delivery. A healthy Kuma container does not establish that every monitored service is healthy. Keep log output private because it may contain monitored addresses or notification details.
Backups and updates
Take a consistent backup of application state before replacing the container. Stop the application while archiving its data, or use a coordinated VM backup procedure. Keep a recovery copy off the host and test a restore.
On this homelab, Dependabot and the operations deployment runner manage reviewed image updates. The internal guide documents that automation. On another homelab, use the manual process below or equivalent backup-aware automation.
For a manual update, first update the image pin in compose.yaml to the reviewed version and take the backup, then run:
sh
cd /docker/uptime-kuma
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kumaRepeat the maintenance checks after replacement. Database migrations can make an image downgrade unsafe; inspect the matching backup and application version before rollback.
Upstream references
Deployment sources
This page is the human-readable setup and configuration guide. You can follow it without access to the private repository or internal documentation.
The homelab's deployed source files remain in its private repository: Compose definition and environment template. The internal companion documents how AI operators provision, update, and recover this specific deployment.