Skip to content

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 ​

SettingValue
HostOperations · Proxmox VM 100
Host IP10.120.40.100
Domainup.home.rwk.me
Dashboardhttps://up.home.rwk.me
Direct accesshttp://10.120.40.100:3001
Compose directory/docker/uptime-kuma
Application state/docker/uptime-kuma/data
DatabaseEmbedded 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:

ConfigurationThis homelabOn another homelab
Host address10.120.40.100A stable address assigned to your Docker host
Dashboard domainup.home.rwk.meA hostname under a domain you control
Reverse proxy10.120.40.101Your proxy's address
Project directory/docker/uptime-kumaA local directory writable by your deployment account
TimezoneAmerica/ChicagoYour 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-kuma

Keep 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-stopped

The 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/Chicago

Change 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-kuma

The 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:

SettingValue
Domainup.home.rwk.me
Forward schemehttp
Forward host/IP10.120.40.100
Forward port3001
WebSocket supportEnabled
SSL certificateLet's Encrypt *.home.rwk.me
Force SSLEnabled
HTTP/2Enabled
Block exploitsEnabled

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 ​

  1. Select Add New Monitor in the dashboard.
  2. Choose HTTP(s) for a web application and enter a descriptive name.
  3. 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.
  4. 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.
  5. 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.
  6. 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 ps

Monitoring 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-kuma

Check 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-kuma

Repeat 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.