Uptime Kuma

Know when your services need your attention.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Uptime Kuma

Editable Compose files in your own directory.

Open Uptime Kuma and create its initial administrator.
Create monitors and notification destinations in Uptime Kuma.

selfhost app --directory ./uptime-kuma init uptime-kuma

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./uptime-kuma start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd uptime-kuma
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Uptime Kuma, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "uptime-kuma",
  "name": "Uptime Kuma",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Actions for a linked container

Data usage

Show the size of this service's stored application data.

selfhost existing action EXISTING_ID data-usage

Before configuring integrations

Health checks run the bundled application checker; SQLite connection mode and a mounted CA bundle can be configured.
Monitor provisioning and administrator setup use Socket.IO, which this profile does not automate.
Back up the complete data directory after a clean stop for a consistent manual snapshot.

Uptime Kuma integrations

Compose service: uptime-kuma. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (3)

Time zone timezone: string
Single SQLite connection sqlite-single-connection: Keep true unless investigating contention with an app-supported configuration. stringChoices: true, false
Additional CA bundle extra-ca: Absolute container path to a separately mounted PEM certificate bundle. TLS verification remains enabled. string

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./uptime-kuma config uptime-kuma
selfhost app --directory ./uptime-kuma plan uptime-kuma changes.json
selfhost app --directory ./uptime-kuma apply uptime-kuma changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Data usage

Show the size of this service's stored application data.

selfhost app --directory ./uptime-kuma action uptime-kuma data-usage

Check application health · schedulable

Run the bundled local application health check.

selfhost app --directory ./uptime-kuma action uptime-kuma health

A workspace can schedule this workflow while Selfhost runs. A standalone user can invoke it through an external scheduler. Scheduling guide.

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

uptime-kuma: louislam/uptime-kuma:2.5.5

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Uptime Kuma documentation