Skip to content
Get packs

Guide · Open source

How to use Uptime Kuma: install, monitor and get alerts

Updated · written with AI from the project's own documentation and checked against our catalogue data

Uptime Kuma is a self-hosted monitoring tool. You run it on your own server or computer, it regularly checks your websites and services, and it shows their status in a web dashboard. This guide walks through installing it with Docker Compose, what you can monitor, and how notifications and status pages fit in. By the end you will know how to get it running and what to set up next.

Uptime Kumalouislam/uptime-kuma · ★ 93.2k · MIT

Quick start

  1. 1Install Docker. Install Docker on the machine that will run Uptime Kuma. The recommended install depends on it.
  2. 2Create a folder. Run mkdir uptime-kuma and cd into it so the compose file has a home.
  3. 3Download the compose file. Use curl to fetch compose.yaml from the official repository.
  4. 4Start the container. Run docker compose up -d, then open http://localhost:3001 in your browser.
  5. 5Add your first monitor. Create a monitor for a website or service, choosing a check type such as HTTP(s), TCP or Ping.
  6. 6Set up a notification. Connect a channel such as Telegram, Discord, Slack or email and attach it to your monitors.

What you need before you install Uptime Kuma

The recommended install uses Docker. The README lists Docker as the prerequisite for the Docker Compose setup, so install Docker on the machine that will run Uptime Kuma first.

Uptime Kuma is built around self-hosting, so you need a machine you can keep running. The README lists major Linux distributions such as Debian, Ubuntu, Fedora and ArchLinux, and Windows 10 (x64) or Windows Server 2012 R2 (x64) or higher as supported platforms for the non-Docker install. It lists FreeBSD, OpenBSD, NetBSD, Replit and Heroku as unsupported.

  • Docker, for the recommended install
  • A machine you can run and maintain yourself
  • Do not store data on NFS: the README says NFS file systems are not supported, so map to a local directory or volume

Install Uptime Kuma with Docker Compose

Run these commands in a terminal. They create a folder, download the compose file from the project repository, and start Uptime Kuma in the background.

When it is running, open http://localhost:3001 in a browser, or http://your-ip:3001 from another device on your network. The README says Uptime Kuma listens on all network interfaces.

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

Install with a single Docker command instead

If you prefer not to use Compose, the README gives a plain docker run command. It maps port 3001, stores data in a volume named uptime-kuma, and restarts the container automatically.

To limit access to the local machine only, bind the port to localhost as shown in the README's second example. Replace the ... with the rest of the command above.

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

Run Uptime Kuma without Docker

The non-Docker route requires Node.js version 20.4 or higher and Git. The README recommends running the server with pm2, a process manager that keeps it in the background. Install pm2 and its log rotation module, then start the server.

The README's "Option 1" simply runs the server in the foreground, which is useful for testing. For day-to-day use, the recommended option is pm2. Use pm2 monit to see console output, and pm2 startup followed by pm2 save to start it automatically.

  • Requires Node.js 20.4 or higher and Git
  • Use pm2 to run it in the background
  • For reverse proxy setups, read the project wiki's install guide, which the README links to
git clone https://github.com/louislam/uptime-kuma.git cd uptime-kuma npm run setup # Option 1. Try it node server/server.js # (Recommended) Option 2. Run in the background using PM2 npm install pm2 -g && pm2 install pm2-logrotate pm2 start server/server.js --name uptime-kuma

What you can monitor

Uptime Kuma can check many kinds of targets. The README's feature list includes HTTP(s), TCP, HTTP(s) Keyword, HTTP(s) JSON Query, WebSocket, Ping, DNS Record, Push, Steam Game Server and Docker Containers. Checks run on intervals; the README lists 20-second intervals as a feature.

Other features listed in the README include certificate info, a ping chart, proxy support and 2FA support. Multiple status pages are supported, and each status page can be mapped to a specific domain.

  • HTTP(s), keyword and JSON query checks for websites and APIs
  • TCP and ping checks for servers and ports
  • DNS record checks
  • Push monitors for jobs that report in
  • Docker container checks
  • Steam game server checks

Set up notifications and status pages

When a monitor fails, Uptime Kuma can send a notification. The README names Telegram, Discord, Gotify, Slack, Pushover and email (SMTP), and says there are more than 90 notification services in total. Configure a notification in the settings, then attach it to the monitors you want alerts for.

Status pages show your users the current state of your services. The README says you can create multiple status pages and map them to specific domains.

  • Pick a notification channel such as Telegram, Discord, Slack or SMTP email
  • Create one status page per audience or product
  • Map a status page to a domain if you want users to reach it directly

What people use it for

  • Watching your own websites and sending a Telegram or Discord alert when they go down
  • Monitoring home lab services and checking that a server port or DNS record still responds
  • Running a public status page for a small team's users
  • Checking that a scheduled job has run by using a Push monitor
  • Watching Docker containers on the host

Frequently asked questions

Is Uptime Kuma free?

Uptime Kuma is released under the MIT licence, according to the project's listing. You run it on your own server, so you control the hosting and its costs.

What do I need to run Uptime Kuma?

The recommended install needs Docker. The non-Docker install needs Node.js 20.4 or higher and Git, and the README lists supported Linux distributions and Windows versions.

How do I install Uptime Kuma with Docker?

Create a folder, download compose.yaml from the project repository with curl, and run docker compose up -d. Then open port 3001 in a browser.

Can I run Uptime Kuma on FreeBSD or Heroku?

No. The README lists FreeBSD, OpenBSD, NetBSD, Replit and Heroku as unsupported platforms.

Does Uptime Kuma support NFS storage?

No. The README says NFS is not supported, so map the data to a local directory or Docker volume instead.

How does Uptime Kuma compare to Uptime Robot or Gatus?

Uptime Robot is a hosted service, while Uptime Kuma is self-hosted, so you run and maintain it yourself. Gatus, Statping-ng and Healthchecks.io are other self-hosted options you may want to compare.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Uptime Kuma suits people who already run Docker or a server, want to monitor their own sites and services without a paid hosted tool, or need a simple status page for a small team. If you do not want to maintain your own server, or you need enterprise-scale monitoring, which the README does not describe, consider a hosted service or another tool.

Install options & downloads