Uptime Kuma

Overview

Uptime Kuma is a self-hosted, MIT-licensed uptime monitoring tool: outside-in HTTP(s), TCP, DNS and ping checks against your apps and third-party dependencies, alerts through 90+ notification providers, and public status pages. This template deploys a single Uptime Kuma instance with its SQLite database on a persistent volume, serving the dashboard, monitoring engine and status pages on port 3001. Uptime Kuma has no way to preset an admin credential. The admin account belongs to whoever first opens the setup wizard, so the dashboard ships closed to the internet and you claim the account over a tunnel before publishing anything (see First Run).

This template does not create a GVC. It deploys into an existing GVC that you already have.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-uptime-kuma`	Dashboard, monitoring engine and status pages on port `3001` (stateful, 1 replica)	—
Volume Set	`RELEASE_NAME-uptime-kuma-data`	10 GiB `ext4` volume at `/app/data` holding the SQLite database, uploads and generated keys; a final snapshot is kept for 7 days on delete	—
Identity	`RELEASE_NAME-uptime-kuma-identity`	Identity bound to the workload, with no grants	—

The chart creates no secrets and no policies.

Prerequisites

None for a default install.

Installation

Install the template into an existing GVC. No --set values are required:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/uptime-kuma \
  --version 1.2.0 --gvc GVC_NAME

To install using another method, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image

image: louislam/uptime-kuma:2.4.0

Resources and Storage

resources:
  maxCpu: 500m
  maxMemory: 512Mi
  minCpu: 125m
  minMemory: 256Mi

volumeset:
  capacity: 10 # GiB (minimum 10) — SQLite database, uploads, and generated keys

resources.maxCpu / resources.maxMemory — the CPU and memory limit for the Uptime Kuma container.
resources.minCpu / resources.minMemory — the CPU and memory reservation.
volumeset.capacity — initial volume size in GiB. Values below 10 are refused at render.

Access

publicAccess:
  # Uptime Kuma has no configurable credential: the admin account is claimed by
  # whoever first reaches the setup wizard. Create it over `cpln port-forward`,
  # THEN set this true. See Connecting in the README.
  enabled: false # dashboard + public status pages on the canonical *.cpln.app HTTPS endpoint

internalAccess: # internal firewall scope (in-GVC callers, e.g. status-page consumers)
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

publicAccess.enabled — when true, the workload’s external inbound firewall opens to 0.0.0.0/0 and the dashboard and status pages are served on the canonical *.cpln.app HTTPS endpoint. The dashboard is then protected by Uptime Kuma’s own login; status pages are public by design. Turn it on only after the admin account exists.
internalAccess.type — which workloads inside Control Plane may reach Uptime Kuma.
internalAccess.workloads — list of workload links, used only when type is workload-list.

Type	Description
`none`	No internal access allowed
`same-gvc`	Allow access from all workloads in the same GVC (default)
`same-org`	Allow access from all workloads in the same organization
`workload-list`	Allow access only from the workloads listed in `internalAccess.workloads`

An access change takes up to a few minutes to take effect. Re-check before concluding the setting did nothing. The database type is fixed to SQLite and the workload is fixed at one replica; neither is a value.

Connecting

What	Address	Notes
Dashboard, private (default)	`cpln port-forward RELEASE_NAME-uptime-kuma 3001:3001 --gvc GVC_NAME`, then `http://localhost:3001`	Works while the workload is closed to the internet. Use it to complete First Run.
Dashboard, public	`https://CANONICAL_ENDPOINT`	Only when `publicAccess.enabled` is `true`. Read it from `status.canonicalEndpoint` in `cpln workload get RELEASE_NAME-uptime-kuma --gvc GVC_NAME -o yaml`.
Status pages	`https://CANONICAL_ENDPOINT/status/` followed by the status page slug	Public, no login required. Only when `publicAccess.enabled` is `true`.
From other workloads	`http://RELEASE_NAME-uptime-kuma.GVC_NAME.cpln.local:3001`	Subject to `internalAccess.type`.
Login	The admin account you create in the setup wizard	There is no credential secret; see First Run.

Verify the server is answering through the tunnel:

cpln port-forward RELEASE_NAME-uptime-kuma 3001:3001 --gvc GVC_NAME

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/

A 302 means Uptime Kuma is serving and redirecting to its setup or login page; the bundled health check treats exactly this response as healthy.

First Run

Claim the admin account over a tunnel before anything is published. The chart preselects SQLite, so the setup wizard asks only for an admin username and password.

Install with public access off

Keep the shipped publicAccess.enabled: false. Wait for the workload to report ready:

cpln workload get-deployments RELEASE_NAME-uptime-kuma --gvc GVC_NAME -o yaml

Tunnel to the private dashboard

cpln port-forward RELEASE_NAME-uptime-kuma 3001:3001 --gvc GVC_NAME

Create the admin account

Open http://localhost:3001. You are redirected to the setup wizard; choose an admin username and a strong password. Once one account exists, the wizard is permanently disabled.

Publish it only if you need to

Public status pages and outside access to the dashboard need publicAccess.enabled: true. Run a Helm upgrade with it on, then allow a few minutes for the firewall change to take effect before testing the canonical endpoint:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/uptime-kuma \
  --version 1.2.0 --gvc GVC_NAME \
  --set publicAccess.enabled=true

Monitors and Status Pages

Everything Uptime Kuma monitors is configured in the app UI after login, not as deploy-time values:

Monitors — HTTP(s), TCP port, DNS and ping checks. Outbound traffic is open, so the workload can reach public targets as well as workloads in the same GVC by their internal hostnames, such as WORKLOAD_NAME.GVC_NAME.cpln.local.
Notifications — 90+ providers, including Slack, email and webhooks, configured globally or per monitor.
Status pages — published under /status/ on the same endpoint and readable without login.

The dashboard receives live updates over a WebSocket connection to the same address; status pages are plain HTTP.

Operations

Backing Up

There is no scheduled-backup feature, and the volume set takes no scheduled snapshots; the only automatic snapshot is the final one taken when the volume set is deleted, kept for 7 days. Take a manual snapshot of the data volume before a risky change:

cpln volumeset snapshot create RELEASE_NAME-uptime-kuma-data --gvc GVC_NAME --snapshot-name NAME

cpln volumeset snapshot get RELEASE_NAME-uptime-kuma-data --gvc GVC_NAME

Restoring a Backup

Restoring the data volume from a volume set snapshot has not been verified on this template, and there is no documented restore procedure for it. Treat snapshots as a safety net rather than a tested recovery path.

Resetting the Admin Password

Uptime Kuma ships an upstream password-reset tool that prompts for the new password. Open an interactive shell in the container:

cpln workload connect RELEASE_NAME-uptime-kuma --gvc GVC_NAME

Then, from the app directory, run npm run reset-password and enter the new password twice. The tool also signs out every existing session. This path follows upstream’s documentation and has not been verified on this template.

Upgrading From 1.0.0

Version 1.1.0 renamed the resource limit keys so it is unambiguous which number is the limit:

1.0.0	1.1.0 and later
`resources.cpu`	`resources.maxCpu`
`resources.memory`	`resources.maxMemory`

Rename those two keys in your values before upgrading. An upgrade that still carries the old names is refused at render, and the running release is left untouched:

Error: execution error at (uptime-kuma/templates/workload.yaml:1:4): uptime-kuma: resources.cpu was RENAMED to resources.maxCpu. A block exposing both a reservation and a limit names the limit maxCpu/maxMemory, so the bare name is no longer read and would be silently ignored. Rename it in your values.

resources.memory produces the same message under its own name.

Upgrading From 1.1.0 or Earlier

Version 1.2.0 changed the default of publicAccess.enabled from true to false. If your install relied on the old default and you upgrade without setting it, the dashboard and status pages are closed to the internet. To keep them public, set it explicitly:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/uptime-kuma \
  --version 1.2.0 --gvc GVC_NAME \
  --set publicAccess.enabled=true

Your monitors, status pages and admin account live on the volume set and are unaffected by the upgrade.

Scaling and Availability

This template is single-instance. Upstream Uptime Kuma supports no clustering, and the workload is pinned to exactly one replica with no value to change it. A restart means a brief gap in monitoring; monitors resume on their own when the workload is back, and all data survives on the volume set.

Troubleshooting

The canonical endpoint does not respond

Symptom: The *.cpln.app endpoint refuses requests, while the dashboard works through cpln port-forward.Cause: publicAccess.enabled is false (the default since 1.2.0), so the external inbound firewall is closed.Fix: Complete First Run first, then run a Helm upgrade with --set publicAccess.enabled=true and allow a few minutes for the change to take effect.

The setup wizard is gone and you never created an account

Symptom: Opening the dashboard on a fresh install shows a login page instead of the setup wizard.Cause: Someone else reached the wizard first and claimed the admin account. This can only happen while the dashboard is reachable by others.Fix: Uninstall and reinstall to start a fresh instance (this deletes the volume set), and complete First Run over the tunnel before publishing again.

The dashboard loads but stays blank or never updates

Symptom: The page shell loads, but monitors never appear or never refresh. Status pages still work.Cause: The dashboard depends on a WebSocket connection to the same address; status pages do not.Fix: Reach the dashboard directly on the canonical endpoint rather than through an intermediary that does not pass WebSocket upgrades.

Upgrade refused with resources.cpu was RENAMED

Symptom: cpln helm upgrade fails with uptime-kuma: resources.cpu was RENAMED to resources.maxCpu (or the same message for resources.memory).Cause: Your values still use the 1.0.0 key names.Fix: Rename resources.cpu to resources.maxCpu and resources.memory to resources.maxMemory, then upgrade again. See Upgrading From 1.0.0.

An access change appears to do nothing

Symptom: You changed publicAccess.enabled or internalAccess.type and access still behaves as before.Cause: Firewall changes take up to a few minutes to take effect.Fix: Wait a few minutes and test again before concluding the setting is wrong.

Important Notes

Create the admin account over the tunnel before enabling public access — until an account exists, anyone who can reach the dashboard can claim it.
Upgrading from 1.1.0 or earlier closes public access unless you set publicAccess.enabled: true — see Upgrading From 1.1.0 or Earlier.
Single instance only — there is no failover; a restart is a brief monitoring gap.
All data lives on the volume set. cpln helm uninstall deletes it, and a reinstall starts a fresh instance with a new setup wizard; the final snapshot is kept for 7 days.
There are no cloud backups in this template — take a manual volume set snapshot before risky changes.

External References

Uptime Kuma on GitHub

Upstream source repository

Uptime Kuma Wiki

Official documentation wiki

Reset Password via CLI

Upstream password-reset procedure

Environment Variables

Environment variables reference

Uptime Kuma Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image

Resources and Storage

Access

Connecting

First Run

Monitors and Status Pages

Operations

Backing Up

Restoring a Backup

Resetting the Admin Password

Upgrading From 1.0.0

Upgrading From 1.1.0 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References

Uptime Kuma on GitHub

Uptime Kuma Wiki

Reset Password via CLI

Environment Variables

Uptime Kuma Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image

​Resources and Storage

​Access

​Connecting

​First Run

​Monitors and Status Pages

​Operations

​Backing Up

​Restoring a Backup

​Resetting the Admin Password

​Upgrading From 1.0.0

​Upgrading From 1.1.0 or Earlier

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Uptime Kuma on GitHub

Uptime Kuma Wiki

Reset Password via CLI

Environment Variables

Uptime Kuma Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image

Resources and Storage

Access

Connecting

First Run

Monitors and Status Pages

Operations

Backing Up

Restoring a Backup

Resetting the Admin Password

Upgrading From 1.0.0

Upgrading From 1.1.0 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References