> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uptime Kuma

> Deploy Uptime Kuma on Control Plane using the Template Catalog. Self-hosted uptime monitoring with HTTP, TCP, DNS, and ping checks, alerts through 90+ notification providers, and public status pages. Covers first-visit admin setup, access modes, and admin password recovery.

## Overview

Uptime Kuma is a self-hosted uptime monitoring tool (MIT-licensed) — 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 stateful workload with its SQLite database on a persistent volume, served on the canonical `*.cpln.app` endpoint. The admin account is created by the **first visitor** to the URL — complete the [first-visit setup](#first-visit-setup) immediately after installing.

### Architecture

* **Uptime Kuma** — A single-replica stateful workload serving the dashboard, monitoring engine, and status pages on port `3001` (HTTP + WebSocket).
* **SQLite on a persistent volume** — All state (monitors, users, notification settings, heartbeat history) lives in a SQLite database on the workload's volume set; there is no database dependency.

### What Gets Created

* **Stateful Uptime Kuma Workload** — A single replica serving the dashboard, monitoring engine, and status pages on port `3001`.
* **Volume Set** — A 10 GiB persistent volume mounted at `/app/data` holding the SQLite database, uploads, and generated keys. A final snapshot is kept for 7 days on delete.
* **Identity** — The workload identity, with no grants — this template creates no secrets and no policies.

<Note>
  This template does not create a GVC. You must deploy it into an existing GVC.
</Note>

## Prerequisites

None — a default install needs no secrets, cloud accounts, or external resources. Install the template using your preferred method:

<CardGroup cols={2}>
  <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
    Browse, install, and manage templates visually
  </Card>

  <Card title="CLI" href="/template-catalog/install-manage/cli" icon="terminal">
    Manage templates from your terminal
  </Card>

  <Card title="Terraform" href="/template-catalog/install-manage/terraform" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M77.941 44.5v36.836L46.324 62.918V26.082zm0 0" fill="#5c4ee5"/><path d="M81.41 81.336l31.633-18.418V26.082L81.41 44.5zm0 0" fill="#4040b2"/><path d="M11.242 42.36L42.86 60.776V23.941L11.242 5.523zm0 0M77.941 85.375L46.324 66.957v36.82l31.617 18.418zm0 0" fill="#5c4ee5"/></g></svg>}>
    Declare templates in your Terraform configurations
  </Card>

  <Card
    title="Pulumi"
    href="/template-catalog/install-manage/pulumi"
    icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" id="Pulumi-Icon--Streamline-Svg-Logos" height="24" width="24">
    <desc>
        Pulumi Icon Streamline Icon: https://streamlinehq.com
    </desc>
    <path fill="#f26e7e" d="M4.683025 13.3318c0.869125 -0.5018 0.870575 -2.1264 0.003225 -3.62865s-2.27504 -2.313275 -3.1441725 -1.811475C0.672945 8.3935 0.6715 10.0181 1.53885 11.52035c0.86735 1.502275 2.27505 2.313275 3.144175 1.81145Zm0.0052 3.2167c0.86735 1.502275 0.865925 3.126875 -0.003225 3.628675 -0.86915 0.5018 -2.2768275 -0.309225 -3.144175 -1.81145 -0.8673525 -1.50225 -0.8659075 -3.126875 0.003225 -3.628675 0.8691325 -0.5018 2.276825 0.309225 3.144175 1.81145Zm5.922875 3.4243c0.86735 1.50225 0.8659 3.126775 -0.003225 3.62875 -0.869125 0.501775 -2.27685 -0.309325 -3.1442 -1.81155 -0.867325 -1.50225 -0.865875 -3.12685 0.00325 -3.628675 0.869125 -0.5018 2.276825 0.309225 3.144175 1.811475Zm-0.001925 -6.845275c0.86735 1.50225 0.8659 3.12685 -0.003225 3.628675 -0.869125 0.5018 -2.276825 -0.309225 -3.144175 -1.811475 -0.86735 -1.50225 -0.8659 -3.12685 0.003225 -3.62865 0.869125 -0.501825 2.276825 0.3092 3.144175 1.81145Z" stroke-width="0.25"></path>
    <path fill="#8a3391" d="M22.45775 11.524125c0.86725 -1.502225 0.865925 -3.12685 -0.003225 -3.62865 -0.869125 -0.501825 -2.276825 0.3092 -3.144175 1.811475 -0.86735 1.50225 -0.8659 3.126825 0.003225 3.62865 0.869125 0.501825 2.276825 -0.3092 3.144175 -1.811475Zm0.000175 3.2151c0.869075 0.5018 0.870625 2.1264 0.003225 3.62865 -0.86735 1.50225 -2.27505 2.313275 -3.144175 1.81145 -0.869125 -0.5018 -0.870575 -2.126425 -0.003225 -3.62865 0.86735 -1.50225 2.27505 -2.313275 3.144175 -1.81145ZM16.536225 18.157875c0.86915 0.501825 0.8706 2.126425 0.00325 3.628675 -0.86735 1.502125 -2.275075 2.313225 -3.1442 1.81145 -0.869125 -0.50175 -0.870575 -2.126425 -0.003225 -3.62865 0.867375 -1.502275 2.27505 -2.3133 3.144175 -1.811475Zm-0.003325 -6.843775c0.869125 0.5018 0.870575 2.126425 0.003225 3.628675s-2.27505 2.313275 -3.1442 1.811475c-0.869125 -0.501825 -0.870575 -2.126425 -0.003225 -3.628675 0.86735 -1.502275 2.27505 -2.313275 3.1442 -1.811475Z" stroke-width="0.25"></path>
    <path fill="#f7bf2a" d="M15.138225 2.06721c0 1.003615 -1.40625 1.817215 -3.14095 1.817215 -1.7347 0 -3.14095 -0.8136 -3.14095 -1.817215C8.856325 1.06359 10.262575 0.25 11.997275 0.25c1.7347 0 3.14095 0.81359 3.14095 1.81721ZM9.2166 5.482375c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172s1.40625 -1.817225 3.14095 -1.817225c1.7347 0 3.14095 0.8136 3.14095 1.817225Zm8.71005 1.8172c1.7347 0 3.14095 -0.813575 3.14095 -1.8172s-1.40625 -1.817225 -3.14095 -1.817225c-1.7347 0 -3.14095 0.8136 -3.14095 1.817225s1.40625 1.8172 3.14095 1.8172Zm-2.788425 1.605625c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172 0 -1.0036 1.40625 -1.8172 3.14095 -1.8172 1.7347 0 3.14095 0.8136 3.14095 1.8172Z" stroke-width="0.25"></path>
    </svg>}
  >
    Declare templates in your Pulumi programs
  </Card>
</CardGroup>

## First-Visit Setup

Uptime Kuma has no way to preset admin credentials — the admin account is created through a setup wizard by the **first person to open the URL**. The template preselects SQLite, so the wizard asks only for the admin username and password.

<Warning>
  Open the dashboard and create the admin account **immediately after install**. Until you complete the setup wizard, anyone who can reach the endpoint can claim the instance by creating the admin account. Once one account exists, the wizard is permanently disabled.
</Warning>

<Steps>
  <Step title="Wait for the workload to become ready">
    A fresh install is typically ready within a minute. Find the canonical endpoint under `status.canonicalEndpoint` of the `{release}-uptime-kuma` workload.
  </Step>

  <Step title="Open the endpoint and create the admin account">
    Visit `https://<canonical>.cpln.app` — you are redirected to the setup wizard. Choose an admin username and a strong password.
  </Step>
</Steps>

## Configuration

The default `values.yaml` for this template:

```yaml theme={null}
image: louislam/uptime-kuma:2.4.0

resources:
  cpu: 500m
  memory: 512Mi
  minCpu: 125m
  minMemory: 256Mi

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

publicAccess:
  enabled: true # 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, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME
```

### Uptime Kuma Instance

* `image` — The Uptime Kuma container image.
* `resources` — CPU and memory for the Uptime Kuma container.
* `volumeset.capacity` — Volume size in GiB (minimum 10) for the SQLite database, uploads, and generated keys.

### Access

* `publicAccess.enabled` — Serve the dashboard and status pages on the canonical `*.cpln.app` HTTPS endpoint (default). The dashboard is gated by Uptime Kuma's own login; status pages are public by design. Set to `false` for an internal-only instance (external requests are blocked at the edge; in-GVC callers still reach it per `internalAccess`).
* `internalAccess.type` — Internal firewall scope of the Uptime Kuma workload:

| Type            | Description                                                            |
| --------------- | ---------------------------------------------------------------------- |
| `none`          | No internal access.                                                    |
| `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 workloads listed in `internalAccess.workloads`. |

## Connecting

| What                  | Value                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------- |
| Dashboard (public)    | `https://<canonical>.cpln.app` — `status.canonicalEndpoint` of `{release}-uptime-kuma` |
| Status pages (public) | `https://<canonical>.cpln.app/status/{slug}` — no login required                       |
| Internal (same GVC)   | `http://{release}-uptime-kuma.{gvc}.cpln.local:3001`                                   |
| Login                 | The admin account you create in the [first-visit setup](#first-visit-setup)            |

### Monitors, Notifications, and Status Pages

Everything Uptime Kuma monitors is configured in the app UI after login — none of it is deploy-time configuration:

* **Monitors** — HTTP(s), TCP port, DNS, and ICMP ping checks all work out of the box; the workload has unrestricted outbound access, so it can reach any public target as well as in-GVC workloads by their internal hostnames.
* **Notifications** — 90+ providers (Slack, email, webhooks, PagerDuty, and more), configured per monitor or globally in the UI. Webhook targets inside the GVC work using internal `*.cpln.local` hostnames.
* **Status pages** — Published at `/status/{slug}` on the same endpoint, publicly reachable without login.

The dashboard's live updates arrive over a WebSocket (socket.io) connection to the same endpoint, which works through the canonical endpoint without any extra configuration; status pages are plain HTTP.

## Resetting the Admin Password

If you lose the admin password, run upstream's documented recovery command inside the container:

```bash theme={null}
cpln workload exec {release}-uptime-kuma --gvc {gvc} --container uptime-kuma -- npm run reset-password
```

## Important Notes

* **Complete the first-visit setup immediately after install** — until an admin account exists, anyone who can reach the endpoint can create it; once one account exists the wizard is permanently disabled. See [First-Visit Setup](#first-visit-setup).
* **Single instance only** — upstream supports exactly one instance (no clustering), so the workload is pinned to 1 replica and there is no replicas knob. A restart means a brief monitoring gap; monitors resume automatically on boot, and all data survives on the volume set.
* **No cloud backups in this template** — durability is the persistent volume plus a 7-day final snapshot on uninstall. Uninstalling and reinstalling starts a fresh instance.
* **Do not switch the database to MariaDB in place** — upstream does not support migrating an existing SQLite instance; a MariaDB-backed deployment must be a fresh install.
* **Forgot the admin password?** Reset it from inside the container — see [Resetting the Admin Password](#resetting-the-admin-password).

## External References

<CardGroup cols={2}>
  <Card title="Uptime Kuma on GitHub" icon="github" href="https://github.com/louislam/uptime-kuma">
    Upstream source repository
  </Card>

  <Card title="Uptime Kuma Wiki" icon="book" href="https://github.com/louislam/uptime-kuma/wiki">
    Official documentation wiki
  </Card>

  <Card title="Environment Variables" icon="gear" href="https://github.com/louislam/uptime-kuma/wiki/Environment-Variables">
    Environment variables reference
  </Card>

  <Card title="Docker Tags" icon="docker" href="https://github.com/louislam/uptime-kuma/wiki/Docker-Tags">
    Image tags and variants reference
  </Card>

  <Card title="Uptime Kuma Template" icon="github" href="https://github.com/controlplane-com/templates/tree/main/uptime-kuma">
    View the source files, default values, and chart definition
  </Card>
</CardGroup>