# Uptime Kuma

> Install Uptime Kuma from the App Store, create the admin account behind the setup lock, add monitors, alerts and status pages, and back up and update it.

Source: https://zopanel.net/docs/app-uptime-kuma  
Updated: 2026-10-09

Uptime Kuma is a self-hosted monitoring tool: it checks your websites, APIs and servers every minute, alerts you on Telegram, email and many other channels when one goes down, and publishes status pages for your customers. Choose it when you want to hear about downtime before your users do. This page covers installing it from the **App Store**, the first-time setup, what it can monitor from a ZoPanel container, backups and updates.

## Requirements

| Item | Value |
| --- | --- |
| Image | `louislam/uptime-kuma:1` |
| Memory limit | 512 MB, 1 CPU |
| Free disk to install | About 1.7 GB on the Docker disk the first time (the image plus 1 GB kept free for the server) |
| Docker | Installed on the server (**App Store → Install Docker**) |
| Domain | A domain or subdomain whose A record points to the server, for example `status.example.com` |

**Tip:** a monitor that runs on the same server as the sites it watches goes down with them and cannot alert you. For production monitoring, install Uptime Kuma on a **different server** from the one it watches, ideally with another provider.

## Install Uptime Kuma

### As an administrator

1. Open **App Store**. If you see **Docker is required**, click **Install Docker** first.
2. On the **Uptime Kuma** card, click **Install**.
3. Fill in the dialog:

   | Field | What to enter |
   | --- | --- |
   | **Domain** | The domain the app answers on, without `http://`. A new website is created for it. |
   | **Owner** | The hosting account the app belongs to. Its package limits apply to the container. |
   | **Free SSL (Let's Encrypt)** | Leave on. The certificate is issued at the end of the install if the domain points to the server. |

4. Click **Install** and follow the task log until `Uptime Kuma is available at http://<domain>`.
5. If the log says `SSL could not be issued yet`, point the domain to the server and click **Issue certificate** on the website's **SSL** tab.

Uptime Kuma has no extra install fields and ZoPanel sets no variables for it. The nginx proxy in front of it passes WebSocket connections, which Uptime Kuma's interface needs.

### As a customer

Customers install from **App Store** in their own panel when the package allows it. Uptime Kuma needs 512 MB of the package's **RAM (MB)** and one slot of **Packages → Docker apps**. See [Packages and limits](/docs/packages-limits).

## First-time setup

A new install is behind a **setup lock**: the first visitor creates Uptime Kuma's only admin account, so ZoPanel shows everyone else "This app is being set up" until you finish.

1. Open the website and go to the **Docker** tab. Wait until the status is `running`.
2. In the **Setup lock is on** card, click **Open the app (only for me)**.
3. On **Create your admin account**, choose the language, enter a **Username**, a **Password** and **Repeat Password**, then click **Create**.
4. Back on the **Docker** tab, click **Setup finished — open to everyone**. Status pages are now public; the dashboard still needs your login.

## Add monitors, alerts and status pages

### Notifications first

1. Open **Settings → Notifications → Setup Notification**.
2. Choose a **Notification Type**, for example **Telegram** (bot token and chat ID) or **Email (SMTP)**.
3. For email, a mailbox created in the panel works: host = your mail server name, port `587` (security **None / STARTTLS**) or `465` (**SSL/TLS**), the full address and its password.
4. Tick **Default enabled** to attach it to new monitors, click **Test**, then **Save**.

### A monitor

1. Click **Add New Monitor**.
2. Choose the **Monitor Type**. For websites use **HTTP(s)** (or **HTTP(s) - Keyword** to check that a word appears on the page).
3. Enter a **Friendly Name** and the **URL**, for example `https://www.example.com`.
4. Keep **Heartbeat Interval** at 60 seconds or adjust it, and set **Retries** to 1–2 to avoid alerts on a single slow response.
5. Tick the notifications to use, then **Save**.

Uptime Kuma also warns before SSL certificates expire (**Certificate Expiry Notification** under the HTTP(s) monitor's advanced settings).

### A status page

1. Open **Status Pages → New Status Page**, enter a name and a slug, and click **Next**.
2. Add groups and monitors, a description and a logo, then **Save**.
3. Share `https://status.example.com/status/<slug>`.

## Essential settings

- **Settings → Security:** turn on **Two Factor Authentication** for the admin account.
- **Settings → Reverse Proxy → Trust Proxy:** set to **Yes**. Uptime Kuma is reachable only through ZoPanel's nginx, so this makes logs show the visitor's real IP.
- **Settings → General:** set the display and server time zone so incident times match yours.
- **Settings → Monitor History:** shorten how long heartbeats are kept if the database grows large.

## What it can monitor

Uptime Kuma checks run from inside a container behind ZoPanel's container firewall:

| Target | Works? |
| --- | --- |
| Websites and APIs on the internet (HTTP(s), keyword, DNS, TCP to public addresses) | Yes |
| Websites on this server through their public domain (80/443) | Yes |
| Mail ports of this server (25, 465, 587) as **TCP Port** monitors | Yes |
| Other ports of this server: SSH (22), MariaDB (3306), PostgreSQL, Redis, the panel | **No**: they always show as down |
| Ping to this server's own IP | **No** |
| Private networks (10.x, 172.16–31.x, 192.168.x, 100.64.x), loopback | **No** |
| **Docker Container** monitors | **No**: the container has no access to the Docker socket |

Ping monitors to public addresses normally work. The container runs without the `NET_RAW` capability; if a Ping monitor reports a permission error, use an **HTTP(s)** or **TCP Port** monitor instead.

To watch a database or SSH on this server, monitor it from an Uptime Kuma on another server (and allow that server's IP in the firewall or the database's **Remote access**), or expose a small health-check page on a website and monitor that over HTTPS.

## Where data lives and backups

The app's data is in `/var/lib/zopanel-apps/<instance>/`, where `<instance>` is the domain with dots replaced by hyphens (`status.example.com` → `status-example-com`). The container is `zp-app-<instance>`.

| Path on the server | Content |
| --- | --- |
| `/var/lib/zopanel-apps/<instance>/data/` | Uptime Kuma's `/app/data`: the SQLite database `kuma.db` (monitors, notifications, status pages, history, users) and uploaded images |

**What ZoPanel backs up and what it does not:** the **Backups** card on the website's **Docker** tab backs up the app's whole folder. Account backups and incremental backups cover website folders, databases and mailboxes of the account. **They do not include `/var/lib/zopanel-apps`**, so your monitors and history are only in the app's own backups. The configuration backup (`.zpb`) holds the panel's record of the app, not its data.

To back up Uptime Kuma, click **Back up now** on the **Backups** card. Administrators can also set a **Schedule** (**Off**, **Every day** or **Every week**; off by default) and how many copies to **Keep** (1–60, default 7), then click **Save**. Each backup archives `/var/lib/zopanel-apps/<instance>/` into `/var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz`, a folder only root can read that does not count toward the account's disk quota. The container is paused (not stopped) for the few seconds of the copy, so the SQLite file is consistent. Older copies beyond **Keep** are removed, and a failed scheduled backup sends administrators the **Backup failed** alert.

To restore, an administrator clicks **Restore** next to a backup. Uptime Kuma is stopped and its data replaced with the archive; the current data is kept aside until the restored app starts, and put back if it does not. Changes made since the backup are lost. Each backup also has a delete button (administrators only), and deleting the app together with its files deletes its backups too. Customers can click **Back up now** and see the list; the schedule and restores are done by the provider.

The archives stay on the same server. Copy important ones off it (for example with `scp` or `rclone` from `/var/backups/zopanel-apps/<instance>/`) and store them encrypted, since they contain your notification credentials. To restore on another server, install Uptime Kuma on the same domain there, copy the archive into `/var/backups/zopanel-apps/<instance>/` on the new server and click **Restore** on its **Backups** card.

## Update Uptime Kuma

1. Take a backup (**Back up now** on the **Backups** card).
2. On the **Docker** tab, click **Update to latest** (administrators only; customers ask their provider).
3. The task pulls the catalog image and recreates the container. Monitors and history are kept. Checks pause for the few seconds of the restart.

The catalog tag `1` follows Uptime Kuma's 1.x line, so **Update to latest** brings the newest 1.x release. It does not move you to a new major version.

## Troubleshooting

| Symptom or message | What to do |
| --- | --- |
| Visitors see "This app is being set up" | Click **Setup finished — open to everyone** on the **Docker** tab. |
| The dashboard keeps showing a connection or reconnecting message | The interface uses WebSocket. Reload the page; if you put a CDN or another proxy in front of the domain, make sure it passes WebSocket. |
| A monitor for this server's SSH, MariaDB or Redis is always down | Expected: containers cannot reach those ports. See [What it can monitor](#what-it-can-monitor). |
| A monitor for a private IP times out | Private networks are blocked for containers. Monitor the public address instead. |
| Email alerts do not arrive | Check host, port and security in the notification, click **Test** and look at **Application output** on the **Docker** tab. |
| `Uptime Kuma needs 512 MB of memory; your plan has … MB and your apps use … MB` | Raise the package's **RAM (MB)** or remove another app. |
| `not enough disk space: this app needs about 1.7 GB free and the server has … GB; free some space first` | Free disk space, then install again. |
| Forgot the admin password | As root, open a shell in the container with `docker exec -it zp-app-<instance> bash`, run `npm run reset-password` and follow the prompts. |

## Related

- [App Store and S3 storage](/docs/apps)
- [What each app does](/docs/app-catalog)
- [Packages and limits](/docs/packages-limits)
- [Email](/docs/email)
- [Uptime Kuma wiki](https://github.com/louislam/uptime-kuma/wiki) and [project site](https://uptime.kuma.pet)