EvoxtGuidesHow to Set Up Uptime Monitoring with a Self-Hosted Tool (Uptime Kuma)

How to Set Up Uptime Monitoring with a Self-Hosted Tool (Uptime Kuma)

This guide shows you how to set up uptime monitoring with Uptime Kuma, a free, open-source, self-hosted monitoring tool that tracks whether your websites, servers, and services are online. It's a popular alternative to paid SaaS monitors like UptimeRobot or Pingdom, since you control the data, the check intervals, and there are no monitor limits tied to a subscription tier.

What Is Uptime Kuma and Why Self-Host Monitoring

Uptime Kuma is an open-source monitoring tool that checks whether your services are reachable, then alerts you when something goes down. It supports HTTP(s), TCP ports, ping, DNS, and several other check types, with a clean web dashboard for managing everything.

Self-hosting it instead of using a paid service has a few clear advantages:

No cost beyond the VPS you're already running
No limits on how many monitors or notification channels you can set up
Full control over check frequency, data retention, and access
You can run it privately or expose a public status page, your choice

Prerequisites

A VPS running Ubuntu, Debian, or a similar Linux distro
Root or sudo access
Docker installed (covered in Step 1 if you don't have it yet)

Step 1 — Install Docker

If Docker is already installed on your VPS, skip to Step 2. Otherwise, install it with the official convenience script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Verify the installation:

docker --version

Step 2 — Set Up Docker Compose

Create a directory and download the official compose file:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

This pulls the compose file directly from the official repository and starts Uptime Kuma with a Docker-managed named volume for persistent data.

Step 3 — Run the Container

With Compose set up, run the container:

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

This maps port 3001 on the VPS to the container and stores all monitoring data in a named volume calleduptime-kuma, managed by Docker, so it survives container restarts or updates.

Step 4 — Access the Dashboard

Open a browser and visit:

http://your-vps-ip:3001

On first visit, you'll be asked to choose a database: embedded MariaDB, an external MariaDB/MySQL server, or SQLite. For most single-server VPS setups, SQLite is the simplest choice since it requires no separate database server. Embedded MariaDB is bundled into the full Docker image if you prefer a more robust database without managing an external one. External MariaDB/MySQL is best if you already run a database server or want to separate the database from the monitoring container.

After choosing a database, you'll be asked to create an admin username and password. This account is what you'll use to log in and manage monitors going forward.

Step 5 — Add Your First Monitor

From the dashboard, click Add New Monitor and choose a monitor type:

HTTP(s): checks if a website or API endpoint responds
TCP Port: checks if a specific port is open (useful for databases, SSH, custom services)
Ping: checks if a host responds to ICMP ping

Set the check interval (default is 60 seconds), give the monitor a friendly name, and save. Uptime Kuma will immediately start checking and logging the status.

Step 6 — Set Up Notifications

Uptime Kuma supports many notification channels, including Telegram, Discord, Slack, Email, and generic webhooks. To set one up:

Go to Settings > Notifications
Click Setup Notification
Choose your channel (for example, Telegram) and enter the required credentials (bot token, chat ID, etc.)
Save, then attach the notification to any monitor so it triggers on downtime

Step 7 — Set Up a Status Page (Optional)

Uptime Kuma includes a built-in public status page feature, useful if you want to share service status with clients or users without giving them dashboard access.

Go to Status Pages from the dashboard, create a new page, add the monitors you want visible, and publish. The page is accessible at a URL served directly by your Uptime Kuma instance.

Step 8 — Secure the Dashboard

By default, the dashboard is reachable on port 3001 over plain HTTP, which isn't ideal for production use. Two recommended steps:

Put Uptime Kuma behind a reverse proxy (like Nginx) with SSL via Let's Encrypt, so it's accessible over HTTPS on a proper domain instead of a raw IP and port
Restrict direct access to port 3001 at the firewall level, so it's only reachable through the reverse proxy

Common Issues and Troubleshooting

Dashboard not accessible on port 3001

Check that your VPS firewall (UFW, iptables, or your provider's network firewall) allows inbound traffic on port 3001, or on port 443 if you've set up a reverse proxy.

Monitoring data resets after container restart

This usually means the volume wasn't mounted correctly. Confirm the -v uptime-kuma:/app/data flag was included in the docker run command, and check it with docker volume ls to confirm the volume exists.

Notifications not sending

Double-check the credentials entered for the notification channel (bot token, webhook URL, etc.), and confirm the notification is actually attached to the monitor, not just saved in settings.

FAQ

Is Uptime Kuma free?

Yes, it's fully open-source and free to self-host, with no monitor limits or paid tiers.

Can it monitor multiple servers from one instance?

Yes, a single Uptime Kuma instance can monitor any number of external hosts, websites, or services, not just the VPS it's installed on.

How is this different from UptimeRobot or Pingdom?

Those are paid SaaS monitoring tools with free tiers that cap the number of monitors and check frequency. Uptime Kuma runs on your own VPS, so there are no such limits, at the cost of having to maintain the server yourself.

Conclusion

Uptime Kuma is one of the easiest ways to get reliable, self-hosted uptime monitoring running on a VPS, especially with Docker handling most of the setup complexity. Once it's running, adding monitors and notification channels takes just a few clicks. If you're looking for a VPS to run monitoring tools like this on, Evoxt's plans are well suited for lightweight self-hosted services.

Quick Setup: All Commands

For those who just want the commands, here's the full setup in sequence:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
mkdir uptime-kuma
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

Then visit http://your-vps-ip:3001 to finish setup in the dashboard.