Uptime Kuma self-hosted: a monitor that keeps watching when your server goes down

Why can't it just run on my web server?

Because when that server crashes, loses its network or runs out of disk, Uptime Kuma goes down with it, and nobody sends you the message. You find out from a customer instead.

A monitor earns its keep by being somewhere else. It should have its own power, its own address and its own way onto the internet, so it sees your site the way a visitor does. Think of it as a smoke alarm: you want it on a different circuit from the thing that might catch fire.

The good news is that it is a light job. Uptime Kuma is a single program that spends most of its time waiting for replies, so a small virtual server is plenty, as long as that server is not the one being watched.

What you need before you start

• A Linux machine with Docker. It is the first install the project's README shows, and the simplest. Without Docker you would need Node.js 20.4 or newer, Git and pm2.
• A host name of your own, such as status.yourdomain.com. Uptime Kuma will not run under a folder like /monitor, so it gets its own subdomain.
• A local disk for its data. The project says network shares such as NFS are not supported, because its SQLite database needs proper file locking to stay healthy.
• Somewhere to send alerts: a Telegram bot, a Discord or Slack webhook, or an email account that can relay mail.

How much memory? The project does not publish a number, so we will not invent one. It depends on how many things you check and how often. Start small, look at memory use after a week of real checks, and move up if it needs more.

A small server that fits the job

Our Cloud VPS is made for exactly this kind of job, and its page even names it: a monitoring probe watching your services from New York. It is a virtual machine on one of our servers, shared with other customers, with its own system, root access, one IPv4 address and an IPv6 /96.

• Docker is one click away. Choose the Docker app when you order and Docker and Docker Compose are installed on first start, at no extra cost.
• It is ready quickly. The machine is built on its own once your first payment clears, usually within a couple of minutes, and we email you when it is.
• Your email alerts go out. Ports 465 and 587, the ones mail services use, work from day one. Only port 25 starts closed.
• Running out of traffic does not switch it off. Only what the machine sends counts. On a monthly or yearly size, if you ever use the month's allowance, it keeps running and sends more slowly until the next month. Elastic machines pay for sent traffic per GB instead.
• A console in your browser for the day SSH will not answer, plus restart and reinstall buttons in your dashboard.

Up and running in one sitting

1. Pick the Docker app on the order page, add your SSH key, and log in as root.
2. Start Uptime Kuma with the command below. It keeps its data in a Docker volume called uptime-kuma and starts again by itself after a reboot.
3. Create a DNS A record for status.yourdomain.com pointing at the server's IPv4 address.
4. Set up your admin account while nobody else can reach the page. On your own computer, run ssh -N -L 8080:127.0.0.1:3001 root@your-server and leave it open, then visit http://localhost:8080 in your browser and choose your username and password.
5. Install Caddy and give it the two-line site file below. Caddy fetches and renews the HTTPS certificate by itself.
6. Open https://status.yourdomain.com, sign in with that account, and add your first monitor.

docker run -d --restart=unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

status.yourdomain.com {
    reverse_proxy 127.0.0.1:3001
}

The 127.0.0.1: in front of the port is deliberate. Docker publishes container ports around the ufw firewall, so a firewall rule will not hide port 3001 from the internet. Binding it to the machine itself means only Caddy can reach it, and everyone else has to come in over HTTPS.

Using nginx instead? Turn on WebSockets

If you already use nginx or Apache, that works too, with one catch. Uptime Kuma's dashboard is live: it keeps a WebSocket connection open to the server. Your proxy has to pass along the Upgrade and Connection headers and speak HTTP/1.1 to it, or the page opens and then sits there empty. The project's wiki has ready-made nginx and Apache examples, and Nginx Proxy Manager has a WebSockets Support switch to tick.

Once everyone reaches Uptime Kuma only through your proxy, go to Settings, Reverse Proxy and set Trust Proxy to Yes, so the logs record your visitors' real addresses.

Getting alerts you will actually notice

Uptime Kuma can check a web page, look for a word on it, query a JSON answer, knock on a TCP port, ping a host, resolve a DNS record, or wait for a push from a script that should report in. It can alert you through more than 90 services, including Telegram, Discord, Slack, Pushover, Gotify and email.

1. Set up one notification channel first and press its Test button.
2. Add your monitors and attach that channel to each.
3. Give important checks a retry or two. Since version 2, new monitors start with zero retries, so a single hiccup would wake you.
4. If you want customers to see the status too, publish a status page. It updates every 5 minutes, so keep watching the dashboard yourself.

Keeping it healthy

• Backups: everything lives in the data folder, and copying it is the only backup method version 2 supports. Stop the container, copy the volume, start it again.
• Updates: pull the new image, remove the old container and start a new one on the same volume, exactly as the project's update page shows.
• Forgot the admin password? Open a shell in the container and run npm run reset-password.
• Watching something reachable only over IPv6? Docker does not enable IPv6 by default; the project's troubleshooting page shows how to switch it on for the container's network.

When you need more than one watcher

The Cloud VPS lives in New York. If the servers you are watching are also with us in New York, for example one of our dedicated servers, the monitor and the site share a city and a network. That is still far better than sharing a machine, but for something that earns money, add a second watcher with another provider in another region, and let either one alert you.

Uptime Kuma answers "is it up, and how fast did it reply?". It does not chart memory or disk use; that is a job for a separate metrics tool. For the machines doing the real work, pick from our five data center cities in the United States and Europe.

Questions people ask

Which port does Uptime Kuma use?

Port 3001. If you put it behind a proxy, publish it as 127.0.0.1:3001 so only the proxy can reach it, and send visitors to port 443 over HTTPS. You can change the port with the UPTIME_KUMA_PORT setting if 3001 is taken.

Is a small VPS really enough?

For most people, yes. Uptime Kuma is one lightweight program that mostly waits for replies. The project gives no official memory figure, so check its use after a week, and ask us to move you to a bigger size if it needs one. Sizes only go up, so starting small is the safe choice.

Can I just use Docker Compose instead of docker run?

Yes. The project publishes a compose.yaml with the same image, a ./data folder and port 3001. Save it, change the port line to 127.0.0.1:3001:3001 if you use a proxy, then start it with docker compose up -d.

My dashboard opens but stays empty. What is wrong?

Almost always the proxy. Uptime Kuma needs WebSockets, so nginx or Apache must forward the Upgrade and Connection headers. In Nginx Proxy Manager, tick WebSockets Support.

Will email alerts work from the Cloud VPS?

Yes, through a mail service on port 587 or 465, which are open from day one. Port 25 is closed on new machines, which only matters if you want to deliver mail directly without a provider.

Can Uptime Kuma run on a network drive?

No. The project says NFS is not supported, because its database can be corrupted without proper file locking. Keep the data folder on the server's own disk.