EnglishTiếng Việt
Sign in Install free
DocsUptime Kuma
Docs / Uptime Kuma

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.

Updated Oct 9, 2026 · 7 min read

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.

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.
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.
← Metabase Gitea →