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:
- A stopped VM or LXC.
- A network problem.
- A Proxmox firewall rule.
- A stopped Docker container.
- An unhealthy application.
- A database problem.
- Pi-hole DNS.
- Traefik routing.
- An expired or invalid certificate.
- Authentik proxy authentication.
- The WireGuard tunnel.
- The public VPS.
Service Information
| Setting | Value |
|---|---|
| Service name | Uptime Kuma |
| Private IP address | 192.168.2.115 |
| Backend port | TCP 3001 |
| Public hostname | status.bytek.ca |
| Deployment directory | /opt/uptime-kuma |
| Container name | uptime-kuma |
| Persistent data | /app/data inside the container |
| Database | Embedded MariaDB |
| Container DNS | 192.168.2.65 |
| Public routing | Traefik |
| Target authentication | Authentik Proxy Provider |
| Required Authentik group | bytek-admin |
| Backup coverage | Proxmox scheduled backup |
| Proxmox VM ID | Confirm current VM ID |
Dashboard:
Architecture Role
Uptime Kuma monitors both private backends and routed application hostnames.
A routed monitor follows this path:
- Uptime Kuma resolves the application hostname through Pi-hole.
- Pi-hole returns Traefik’s private IP address,
192.168.2.182. - Uptime Kuma connects to Traefik.
- Traefik selects the application router.
- Traefik forwards the request to the private backend.
- Uptime Kuma records the response status and latency.
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:
- The guest is running.
- The virtual network interface is active.
- The network path permits ICMP.
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:
- The guest is reachable.
- The application port is open.
- The application or web service responds.
A direct backend monitor bypasses:
- Pi-hole hostname resolution.
- Traefik routing.
- Public certificates.
- The VPS.
- WireGuard public ingress.
Routed Application Monitor
A routed monitor uses the normal HTTPS application hostname.
A successful routed monitor proves:
- Pi-hole resolves the hostname.
- Traefik is reachable.
- The router is loaded.
- The certificate is valid.
- The backend is reachable.
- The application responds.
Failure Interpretation
| VM Monitor | Backend Monitor | Routed Monitor | Likely Failure |
|---|---|---|---|
| Down | Down | Down | VM, LXC, Proxmox, or network failure |
| Up | Down | Down | Docker, application, database, or backend firewall failure |
| Up | Up | Down | Pi-hole, Traefik, TLS, router, or Authentik failure |
| Up | Up | Up | Service is operating normally |
| Up | Down | Up | Monitor target or direct-backend firewall configuration may be incorrect |
| Down | Up | Up | ICMP is blocked, but the application is available |
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:
- Monitors.
- Monitor history.
- Notifications.
- Status pages.
- Maintenance windows.
- Application settings.
- User configuration.
- Embedded database files.
- Uploaded status-page assets.
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:
healthy
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:
192.168.2.65appears in the DNS list.
Test an internal hostname from inside the container using:
sudo docker exec uptime-kuma getent hosts portal.bytek.ca
Expected result:
portal.bytek.caresolves to192.168.2.182.
Test another internal hostname using:
sudo docker exec uptime-kuma getent hosts projects.bytek.ca
Expected result:
projects.bytek.caresolves to192.168.2.182.
DNS Failure After a Power Interruption
Docker DNS previously failed after an electrical outage.
Symptoms included:
- Monitors failing after services had restarted.
- Internal hostnames not resolving inside containers.
- Application hosts resolving correctly while container resolution failed.
- OIDC or certificate operations reporting unreachable endpoints.
Recommended recovery sequence:
- Confirm Pi-hole is running.
- Confirm Pi-hole owns
192.168.2.65. - Confirm the Uptime Kuma VM resolves internal hostnames.
- Confirm the Uptime Kuma container resolves internal hostnames.
- Verify the container’s explicit DNS configuration.
- Restart the Uptime Kuma container.
- Recreate the container if Docker-level DNS configuration changed.
- Confirm the monitors recover.
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:
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:
- WHC public DNS.
- Public VPS.
- WireGuard.
- Home WireGuard gateway.
- Traefik.
- Authentik embedded outpost when enabled.
- Uptime Kuma at
192.168.2.115:3001.
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:
- The administrator opens
status.bytek.ca. - Traefik forwards the request to the Authentik embedded outpost.
- Authentik checks the existing authentication session.
- Authentik requests credentials and MFA if required.
- Authentik evaluates the application bindings.
- Authentik proxies the request to Uptime Kuma.
- Uptime Kuma displays the dashboard.
Authentik Application
| Setting | Value |
|---|---|
| Application name | Uptime Kuma |
| Application slug | uptime-kuma |
| Provider type | Proxy Provider |
| Provider mode | Proxy |
| External host | https://status.bytek.ca |
| Internal host | http://192.168.2.115:3001 |
| Required group | bytek-admin |
| Required policy | Allow bytek.ca users |
| Policy engine | ALL |
| Outpost | Authentik Embedded Outpost |
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:
192.168.2.115- TCP port 3001
The Uptime Kuma VM firewall must allow:
- Source
192.168.2.162 - Destination TCP port 3001
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:
- Create the Authentik application and Proxy Provider.
- Assign the application to the embedded outpost.
- Allow Authentik to reach TCP port 3001.
- Route
status.bytek.cathrough the outpost. - Test Authentik authentication.
- Confirm the Uptime Kuma local login still appears behind Authentik.
- Test with the
bytek-adminaccount. - Test denial with a non-administrator account.
- Confirm public status pages still work if required.
- Disable Uptime Kuma local authentication.
- Enable Trust Proxy.
- Restrict direct TCP 3001 access.
- Test recovery.
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:
- Record the Uptime Kuma administrator password.
- Confirm Proxmox backup coverage.
- Create a Proxmox snapshot if desired.
- Confirm direct private access.
- Confirm Authentik access.
- Confirm a non-admin user is denied.
- Confirm public status pages.
- Document the recovery process.
After disabling local authentication:
- Enable Trust Proxy.
- Restrict direct TCP 3001 access to the Authentik VM.
- Remove unnecessary direct Traefik-to-Kuma access if Traefik now routes to the outpost.
- Retain the original administrator password for recovery.
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:
| Source | Purpose |
|---|---|
192.168.2.162 |
Authentik embedded outpost |
| Administrative workstation during testing | Temporary recovery access |
| Approved monitoring source | Only if required |
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:
- Published status pages.
- Status-page API requests.
- Static assets.
- Uploaded status-page files.
- Badge endpoints.
- Push-monitor endpoints.
- Public icons.
Unauthenticated-path exclusions must be as narrow as practical.
Do not exclude the entire Uptime Kuma API.
After configuring exclusions:
- Open a public status page in a private browser.
- Confirm no Authentik login is required.
- Open the dashboard.
- Confirm Authentik login is required.
- Test a push monitor.
- Test a status badge if used.
- Review Authentik and Traefik logs.
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:
- Confirm the push path is excluded.
- Confirm Traefik routes the request correctly.
- Confirm the unique token is unchanged.
- Review the Uptime Kuma monitor history.
- Review Traefik access logs.
- Review Authentik outpost logs.
Monitor Naming Standard
Use consistent names so the dashboard is easy to scan.
Recommended patterns include:
Service VMService Backend DirectService Through TraefikService ExternalService CertificateService DNS
Examples:
Nextcloud VMNextcloud AIO ApacheNextcloud Through TraefikVikunja VMVikunja Backend DirectVikunja Through TraefikBookStack VMBookStack Backend DirectBookStack Through Traefik
Core Infrastructure Monitors
Recommended core monitors include:
| Monitor | Suggested Type | Target |
|---|---|---|
| Proxmox VE | HTTPS or TCP | 192.168.2.254:8006 |
| Pi-hole VM or LXC | Ping | 192.168.2.65 |
| Pi-hole DNS TCP | TCP | 192.168.2.65:53 |
| Pi-hole DNS UDP | UDP or DNS | 192.168.2.65:53 |
| WireGuard gateway | Ping | 192.168.2.64 |
| Public VPS | Ping or TCP | 38.29.213.101 |
| Public VPS HTTPS | TCP | 38.29.213.101:443 |
| Traefik VM | Ping | 192.168.2.182 |
| Traefik HTTPS | TCP | 192.168.2.182:443 |
| Authentik direct | HTTP | Direct readiness endpoint |
| Authentik routed | HTTPS | Routed readiness endpoint |
Nextcloud Monitors
| Monitor | Type | Target |
|---|---|---|
| Nextcloud VM | Ping | 192.168.2.100 |
| Nextcloud AIO Apache | TCP | 192.168.2.100:11000 |
| Nextcloud Through Traefik | HTTPS | https://cloud.bytek.ca/status.php |
Expected routed status:
- HTTP 200.
Vikunja Monitors
| Monitor | Type | Target |
|---|---|---|
| Vikunja VM | Ping | 192.168.2.121 |
| Vikunja Backend Direct | HTTP | http://192.168.2.121:3456/health |
| Vikunja Through Traefik | HTTPS | https://projects.bytek.ca/health |
Expected health status:
- HTTP 200.
The Vikunja VM firewall must allow Uptime Kuma at 192.168.2.115 to reach TCP port 3456.
BookStack Monitors
| Monitor | Type | Target |
|---|---|---|
| BookStack VM | Ping | Confirm BookStack IP |
| BookStack Backend Direct | HTTP | BookStack IP on port 6875 |
| BookStack Through Traefik | HTTPS | https://docs.bytek.ca/login |
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
| Monitor | Type | Target |
|---|---|---|
| Authentik VM | Ping | 192.168.2.162 |
| Authentik Direct Readiness | HTTP | http://192.168.2.162:9000/-/health/ready/ |
| Authentik Routed Readiness | HTTPS | https://portal.bytek.ca/-/health/ready/ |
| Authentik Certificate | Certificate | portal.bytek.ca |
| Authentik Outpost | HTTP | Outpost ping endpoint |
Expected results:
- Direct readiness returns HTTP 200.
- Routed readiness returns HTTP 200.
- Outpost ping returns HTTP 204.
Traefik Monitors
| Monitor | Type | Target |
|---|---|---|
| Traefik VM | Ping | 192.168.2.182 |
| Traefik HTTPS | TCP | 192.168.2.182:443 |
| Traefik Dashboard | HTTPS | https://proxy.bytek.ca/ |
| Traefik Certificate | Certificate | proxy.bytek.ca |
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:
portal.bytek.cacloud.bytek.caprojects.bytek.cadocs.bytek.castatus.bytek.caproxy.bytek.ca
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:
- Email.
- Microsoft Teams webhook.
- Discord webhook.
- Matrix.
- Telegram.
- Other supported notification services.
Notification credentials must remain outside BookStack.
BookStack should document:
- Notification channel name.
- Intended recipients.
- Severity policy.
- Test date.
- Secret-storage location.
Notification Policy
Recommended notification behavior:
Critical Infrastructure
Immediate notification for:
- Proxmox.
- Pi-hole DNS.
- WireGuard.
- Traefik.
- Authentik.
- Public VPS.
Applications
Notify after enough failed checks to avoid alerts from brief application restarts.
Maintenance
Create maintenance windows before:
- Proxmox reboots.
- Application upgrades.
- Docker stack recreation.
- Firewall maintenance.
- Planned internet outages.
- Storage maintenance.
This prevents expected maintenance from generating unnecessary alerts.
Monitor Timing
Monitor intervals should balance timely detection with unnecessary load.
Suggested principles:
- Critical service checks may run more frequently.
- Application backends can use moderate intervals.
- Certificate checks need less frequent execution.
- Avoid aggressively monitoring database internals without a clear operational need.
- Use retries before marking services down.
- Configure heartbeat intervals based on expected update frequency.
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:
- Private IP addresses.
- Proxmox details.
- Pi-hole details.
- Authentik backend details.
- Internal database status.
- Hypervisor storage status.
- Internal firewall information.
A private administrative status page may include more detail behind Authentik.
Maintenance Windows
Use maintenance windows for planned outages.
Common maintenance events include:
- Proxmox host reboot.
- Electrical maintenance.
- Docker upgrades.
- Authentik upgrades.
- Nextcloud AIO upgrades.
- Traefik configuration changes.
- Storage work.
- Firewall work.
- Backup restoration testing.
Record:
- Reason for maintenance.
- Affected monitors.
- Date and time.
- Expected service impact.
- Actual result.
Firewall Requirements
Uptime Kuma requires outbound access to monitored services.
Application firewalls may require narrow inbound rules from:
192.168.2.115
Known direct-monitor requirements include:
| Destination | Port |
|---|---|
| Pi-hole | TCP and UDP 53 |
| Proxmox VE | TCP 8006 |
| Traefik | TCP 443 |
| Authentik | TCP 9000 |
| Nextcloud | TCP 11000 |
| Vikunja | TCP 3456 |
| BookStack | TCP 6875 |
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:
- Database startup failures.
- Monitor connection failures.
- DNS errors.
- Certificate errors.
- Notification failures.
- Proxy-header errors.
- Authentication errors.
- File-permission problems.
- Persistent-volume errors.
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:
- Pi-hole split DNS.
- Traefik router.
- Certificate.
- Authentik proxy.
- Hostname mismatch.
VM Ping Fails but HTTP Works
Likely cause:
- ICMP blocked by Proxmox or guest firewall.
The VM is likely available.
Kuma Dashboard Works by IP but Not by Hostname
Check:
- Pi-hole.
- Traefik.
- Certificate.
- Authentik provider.
- Browser DNS over HTTPS.
Authentik Login Works but Kuma Is Unreachable
Check:
- Internal host in the Authentik Proxy Provider.
- Authentik VM firewall access to TCP 3001.
- Uptime Kuma container.
- Embedded outpost assignment.
- Host-header forwarding.
Public Status Page Requires Login
Check:
- Authentik unauthenticated-path patterns.
- Status-page slug.
- Static asset exclusions.
- Status API exclusions.
- Traefik routing.
Push Monitor Stops Working
Check:
- Push path exclusion.
- Push token.
- Traefik access logs.
- Authentik outpost logs.
- Monitor heartbeat interval.
Power-Failure Recovery
After a power interruption:
- Confirm Proxmox.
- Confirm Pi-hole.
- Confirm the WireGuard gateway.
- Confirm Authentik.
- Confirm Traefik.
- Confirm the Uptime Kuma VM owns
192.168.2.115. - Confirm Docker.
- Confirm the container.
- Confirm container DNS.
- Confirm embedded MariaDB health.
- Confirm direct dashboard access.
- Confirm the routed dashboard.
- Confirm monitors recover.
- Restart or recreate the container only if DNS remains broken.
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:
- Persistent
/app/data. - Docker Compose file.
- Environment file, if used.
- Any custom certificates.
- Notification configuration.
- Status-page assets.
- Monitor history.
- Embedded database.
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:
- Confirm the VM is running.
- Confirm
192.168.2.115. - Confirm Docker.
- Confirm the persistent-data mount.
- Confirm the container.
- Review logs.
- Confirm embedded database health.
- Test direct TCP port 3001.
- Test Pi-hole DNS.
- Test the Traefik route.
- Test the Authentik proxy.
If the VM must be restored:
- Restore the latest backup under a temporary VM ID.
- Disconnect the restored VM network adapter.
- Verify Docker and persistent data.
- Verify monitor configuration.
- Shut down the failed production VM.
- Assign the expected network identity.
- Start the restored VM.
- Confirm
192.168.2.115. - Confirm the dashboard.
- Confirm notifications and monitors.
- Reconnect the Authentik route.
Authentik Recovery
If the Authentik proxy prevents access:
- Restore the known-good direct Traefik route.
- Temporarily permit the administrative workstation to reach TCP 3001.
- Access Uptime Kuma using the private IP.
- Re-enable Uptime Kuma local authentication.
- Repair the Authentik Proxy Provider.
- Test Authentik with a private browser.
- Confirm
bytek-adminaccess. - Confirm a normal user is denied.
- Disable local authentication again only after validation.
- Restrict TCP 3001 again.
Record the original administrator password securely even after local authentication is disabled.
Security Checklist
- Uptime Kuma is not directly exposed publicly on TCP 3001.
- Dashboard access requires
bytek-admin. - Authentik policy engine uses
ALL. - Direct backend access is restricted after local authentication is disabled.
- Trust Proxy is enabled when required.
- Public status-page exclusions are narrow.
- Push URLs are treated as secrets.
- Notification credentials are protected.
- Container DNS is
192.168.2.65. - Persistent data is backed up.
- Local recovery credentials are stored securely.
- Proxmox backup includes the Uptime Kuma VM.
- Public status pages do not reveal sensitive infrastructure details.
Validation Checklist
- Uptime Kuma VM owns
192.168.2.115. - Docker is active.
- Uptime Kuma container is running.
- Container health is
healthy. - Embedded MariaDB is available.
- Persistent data is mounted.
- Container DNS uses Pi-hole.
- Internal Bytek names resolve.
- Direct TCP 3001 responds.
- Routed dashboard responds.
- Authentik Proxy Provider works.
bytek-adminis allowed.- Normal users are denied.
- Public status pages work as intended.
- Push monitors work.
- Notifications are tested.
- Certificate monitoring works.
- Proxmox backup includes the VM.
- Recovery access has been tested.
Document Control
- Owner: Bryan Gagne-Plante
- Private address:
192.168.2.115 - Backend port: TCP 3001
- Public hostname:
status.bytek.ca - Deployment directory:
/opt/uptime-kuma - Database: Embedded MariaDB
- Container DNS:
192.168.2.65 - Authentication: Authentik Proxy Provider
- Required group:
bytek-admin - Proxmox VM ID: Confirm current VM ID
- Last verified: YYYY-MM-DD
- Last notification test: YYYY-MM-DD
- Last Authentik proxy test: YYYY-MM-DD
- Last public status-page test: YYYY-MM-DD
- Last restore test: YYYY-MM-DD
- Known limitation: Monitoring, status history, and alerting depend on one Uptime Kuma VM
No comments to display
No comments to display