Uptime Kuma

Purpose

Uptime Kuma provides availability monitoring for the Bytek homelab.

Uptime Kuma monitors services at multiple layers so an outage can be isolated quickly.

Monitoring can determine whether a failure is caused by:

Service Information

Dashboard:

Open Uptime Kuma

Architecture Role

Uptime Kuma monitors both private backends and routed application hostnames.

A routed monitor follows this path:

A direct backend monitor bypasses Traefik and connects directly to the application VM.

Using both monitor types helps distinguish infrastructure failures from reverse-proxy failures.

Monitoring Layers

Each important service should have up to three monitoring layers.

VM or LXC Monitor

A ping monitor verifies that the guest is reachable on the network.

A successful ping proves:

A successful ping does not prove that the application is healthy.

Direct Backend Monitor

A direct backend monitor connects to the private application address and port.

A successful backend monitor proves:

A direct backend monitor bypasses:

Routed Application Monitor

A routed monitor uses the normal HTTPS application hostname.

A successful routed monitor proves:

Failure Interpretation

A failed ping monitor does not always mean the VM is down. The guest or Proxmox firewall may block ICMP while allowing application traffic.

Docker Deployment

The Uptime Kuma deployment is managed using Docker Compose.

Deployment directory:

/opt/uptime-kuma

Before running Compose commands, move into the deployment directory using:

cd /opt/uptime-kuma

Check container state using:

sudo docker compose ps

View recent logs using:

sudo docker compose logs --tail 100 uptime-kuma

Follow logs live using:

sudo docker compose logs -f uptime-kuma

Validate the Compose configuration using:

sudo docker compose config --quiet

Apply normal configuration changes using:

sudo docker compose up -d

Recreate the container after changing Docker-level settings such as DNS, volumes, environment variables, or networking using:

sudo docker compose up -d --force-recreate uptime-kuma

Persistent Data

Uptime Kuma stores its application data under /app/data inside the container.

The persistent host mapping should be confirmed from the current Compose file.

The persistent data includes information such as:

The persistent-data directory must remain mounted across container recreation.

Never remove the persistent volume while troubleshooting a container-startup problem.

Database

The current Uptime Kuma deployment uses embedded MariaDB.

Database health is reported by the container health check.

The container should not be considered fully healthy until the database is available.

Check container health using:

sudo docker inspect --format='{{.State.Health.Status}}' uptime-kuma

Expected result:

If the result is starting, allow the health check to continue while reviewing logs.

If the result is unhealthy, inspect the Uptime Kuma logs before restarting or recreating the container.

Docker DNS

The Uptime Kuma container explicitly uses Pi-hole at 192.168.2.65.

This allows Uptime Kuma to resolve internal split-DNS records.

Verify container DNS using:

sudo docker inspect --format='DNS={{json .HostConfig.Dns}}' uptime-kuma

Expected result:

Test an internal hostname from inside the container using:

sudo docker exec uptime-kuma getent hosts portal.bytek.ca

Expected result:

Test another internal hostname using:

sudo docker exec uptime-kuma getent hosts projects.bytek.ca

Expected result:

DNS Failure After a Power Interruption

Docker DNS previously failed after an electrical outage.

Symptoms included:

Recommended recovery sequence:

Do not rebuild Uptime Kuma or delete persistent data because of a DNS-only failure.

Public Dashboard Routing

The Uptime Kuma dashboard is available at:

Open Uptime Kuma

Internal clients resolve status.bytek.ca to Traefik at 192.168.2.182.

External clients resolve status.bytek.ca to the public VPS at 38.29.213.101.

The public path includes:

Authentication Design

Uptime Kuma does not use the same native OIDC design as Nextcloud, Vikunja, BookStack, and Proxmox.

The target design uses an Authentik Proxy Provider.

The expected authentication flow is:

Authentik Application

Only users who satisfy both the group and policy requirements should reach the dashboard.

Embedded Outpost Connectivity

The embedded outpost runs through the Authentik service at 192.168.2.162.

Authentik must be able to reach Uptime Kuma at:

The Uptime Kuma VM firewall must allow:

Test from the Authentik VM using:

curl -I http://192.168.2.115:3001/

A healthy Uptime Kuma response may redirect to /dashboard.

Authentication Migration Safety

Do not disable Uptime Kuma’s local authentication before the Authentik proxy works.

Use this migration order:

During the intermediate state, both Authentik and Uptime Kuma authentication may appear.

That is intentional until the Authentik path is validated.

Disabling Local Authentication

Only disable local Uptime Kuma authentication after Authentik is proven reliable.

Before disabling local authentication:

After disabling local authentication:

Direct Backend Security

When Uptime Kuma local authentication is disabled, direct access to 192.168.2.115:3001 must be restricted.

Otherwise, a LAN client could bypass Authentik and reach an unauthenticated dashboard.

The final firewall should permit TCP port 3001 only from approved sources such as:

Remove temporary direct access after validation.

Public Status Pages

Some Uptime Kuma status pages may be intended for unauthenticated public viewing.

Authentik Proxy Provider exclusions may be required for:

Unauthenticated-path exclusions must be as narrow as practical.

Do not exclude the entire Uptime Kuma API.

After configuring exclusions:

Push Monitors

Push monitors rely on a unique URL that an external process calls to report success.

If Uptime Kuma sits behind Authentik, the push path must remain reachable without an interactive login.

Protect push-monitor URLs as secrets.

Do not publish push URLs in BookStack.

If a push monitor stops updating after enabling Authentik:

Monitor Naming Standard

Use consistent names so the dashboard is easy to scan.

Recommended patterns include:

Examples:

Core Infrastructure Monitors

Recommended core monitors include:

Nextcloud Monitors

Expected routed status:

Vikunja Monitors

Expected health status:

The Vikunja VM firewall must allow Uptime Kuma at 192.168.2.115 to reach TCP port 3456.

BookStack Monitors

Use accepted status codes from 200 through 399 if the application redirects to authentication.

The BookStack VM firewall must allow Uptime Kuma at 192.168.2.115 to reach TCP port 6875.

Authentik Monitors

Expected results:

Traefik Monitors

The dashboard monitor must account for Authentik and Basic Auth redirects if those protections are enabled.

Do not store Basic Auth credentials in BookStack.

Proxmox Monitor Considerations

Proxmox may return a response that is valid but not HTTP 200 for some request methods.

Avoid relying on an unsupported HTTP HEAD request.

A TCP monitor on port 8006 can verify listener availability.

An HTTPS monitor can verify the login page if configured with an appropriate method and accepted status range.

Proxmox remains private and should be monitored using its private address.

Certificate Monitoring

Important public hostnames should have certificate-expiry monitoring.

Recommended hostnames include:

Certificate monitoring should alert before expiration.

A valid application response does not guarantee that certificate renewal automation remains healthy.

Notification Channels

Uptime Kuma can notify administrators when a monitor changes state.

The configured notification methods should be recorded after verification.

Potential channels may include:

Notification credentials must remain outside BookStack.

BookStack should document:

Notification Policy

Recommended notification behavior:

Critical Infrastructure

Immediate notification for:

Applications

Notify after enough failed checks to avoid alerts from brief application restarts.

Maintenance

Create maintenance windows before:

This prevents expected maintenance from generating unnecessary alerts.

Monitor Timing

Monitor intervals should balance timely detection with unnecessary load.

Suggested principles:

These values should be tuned after observing false positives and actual recovery behavior.

Status Pages

Status pages provide a consolidated view of selected monitors.

A public status page should include only services appropriate for public disclosure.

Avoid publishing:

A private administrative status page may include more detail behind Authentik.

Maintenance Windows

Use maintenance windows for planned outages.

Common maintenance events include:

Record:

Firewall Requirements

Uptime Kuma requires outbound access to monitored services.

Application firewalls may require narrow inbound rules from:

Known direct-monitor requirements include:

ICMP must be allowed if ping monitors are used.

A failed ping monitor with a healthy HTTP monitor normally indicates blocked ICMP rather than a service outage.

Health Validation

Check the VM address using:

ip -br -4 addr

Check the container state using:

sudo docker compose ps

Check container health using:

sudo docker inspect --format='{{.State.Health.Status}}' uptime-kuma

Confirm direct access using:

curl -I http://192.168.2.115:3001/

Confirm DNS inside the container using:

sudo docker exec uptime-kuma getent hosts portal.bytek.ca

Confirm the public route using:

curl -I https://status.bytek.ca/

Interpret redirects according to the currently enabled authentication layers.

Logging

Review Uptime Kuma logs using:

sudo docker compose logs --tail 100 uptime-kuma

Follow logs live using:

sudo docker compose logs -f uptime-kuma

Review logs for:

Do not paste access tokens, notification secrets, cookies, or push-monitor URLs into BookStack.

Common Failure Scenarios

Many Hostname Monitors Fail Simultaneously

Likely causes:

Check direct IP monitors before assuming every application failed.

Direct Backends Work but Routed Monitors Fail

Likely causes:

VM Ping Fails but HTTP Works

Likely cause:

The VM is likely available.

Kuma Dashboard Works by IP but Not by Hostname

Check:

Authentik Login Works but Kuma Is Unreachable

Check:

Public Status Page Requires Login

Check:

Push Monitor Stops Working

Check:

Power-Failure Recovery

After a power interruption:

Uptime Kuma should start after the core DNS, identity, and routing services when practical.

Backup

The Uptime Kuma VM is included in the Proxmox scheduled backup job.

Protect:

A stopped Proxmox backup provides the strongest whole-VM consistency for a baseline.

Snapshot-mode backup may be used for routine operation where downtime is undesirable.

Recovery Procedure

If Uptime Kuma is corrupted or unavailable:

If the VM must be restored:

Authentik Recovery

If the Authentik proxy prevents access:

Record the original administrator password securely even after local authentication is disabled.

Security Checklist

Validation Checklist

Document Control