Setting up Uptime Kuma - Self Hosted Monitoring tool

If you're looking for a simple and effective way to monitor your systems, you might want to check out Uptime Kuma. Uptime Kuma is a free and open-source self-hosted monitoring tool that allows you to monitor the uptime and performance of your websites, servers, and services. It pairs naturally with the rest of a self-hosted stack: if you set the box up with the first 24 hours on a new VPS, this is the obvious next step, and if you expose the dashboard through a reverse proxy then hardening nginx covers the parts that matter. For a lighter-weight way to publish a service without opening ports at all, see Cloudflare Tunnel with Docker.

Choosing the Deployment Type/Location

There are two main options:

• cloud-based deployments
• home lab deployments

Cloud-based deployment

This option is ideal for those who want a hassle-free and scalable solution. You can take advantage of the reliability, security, and performance of cloud providers. You don't have to worry about maintaining your own hardware or network infrastructure, and you can easily scale up or down your resources as needed. However, this option also comes with some drawbacks, such as higher costs, less control, and potential privacy issues. Here are some cloud providers you can choose from. You can use the links below to get free trials from any of the cloud providers.

• Vultr - Get 100 USD in credits to try out in 30 days. Vultr also offers Windows Server VPSs at a lower cost and has tons of other operating systems to choose from as compared to Linode and Digital Ocean
• Digital Ocean - Get 200 USD in credits to try out in 60 days!
• Linode - Get 100 USD in credits to try out in 60 days!
• Microsoft Azure
• AWS
• Google Cloud Platform

Home lab deployment

This option is suitable for those who enjoy tinkering with their own hardware and software. By deploying Uptime Kuma in your home lab, you can have full control over your monitoring environment. You can customize your settings, tweak your configurations, and experiment with different features. You also have more privacy and security, as your data is stored locally on your own devices. However, this option also has some challenges, such as lower reliability, higher maintenance, and limited scalability and complexity especially if you want to expose the services externally.

Setting Up Uptime Kuma

Setting up an account in the cloud

To get started, you'll need to create an account on the cloud provider of your choice, account If you don't have one already. You can sign up for a free trial on Vultr, Digital Ocean, Linode or the big three ( AWS, Azure or GCP). The point is to have a provider that will give you a server with root level access. So whatever you choose does not matter that much unless you are interested in VPS providers that boast of privacy and anonymity.

Deploying uptime Kuma using Docker

The following steps assume you already have an account setup on the cloud and have a VPS running. The steps apply for both cloud deployments on a VPs and home lab deployments with a few differences which will be highlighted in the instructions.

You'll need Docker and Docker Compose set up on your server. Docker is a software that allows you to run applications in isolated containers, while Docker Compose is a tool that allows you to define and run multiple docker containers using a YAML file. Docker can be run anywhere, including on servers provisioned on a different cloud platform, regardless of the distribution of Linux. We will however install Docker and Docker Compose on Ubuntu 22.04 LTS, but you can follow similar steps for other operating systems. Uptime Kuma allows you to deploy and run it without using Docker Compose, as described in the documentation, bit we will be using docker compose in our case.

Installing Docker and Docker Compose

To install Docker on Ubuntu 22.04 LTS, follow these steps:

• Update your package index by running this command in your terminal:

sudo apt update 

• Install some dependencies by running this command:

sudo apt install ca-certificates curl gnupg lsb-release 

Now add Docker's official repository. That step matters: apt install docker-compose gives you Compose v1, a Python tool that reached end of life in July 2023 and is no longer maintained. The current version is the Compose v2 plugin, invoked as docker compose (with a space, not a hyphen), and it comes from Docker's own repo rather than your distribution's.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
 https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
 | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify that Docker is installed and running:

sudo docker run hello-world

You should see a message that says "Hello from Docker!". Then confirm the Compose plugin is present. Note the space in the command:

docker compose version

If you are not running Ubuntu, substitute your distribution in the repository setup above. The official instructions cover the alternatives.

Here are the official installation instructions for your operating system:

• Debian/Ubuntu: https://docs.docker.com/engine/install/debian/ and https://docs.docker.com/compose/install/
• CentOS/RHEL: https://docs.docker.com/engine/install/centos/ and https://docs.docker.com/compose/install/
• Raspberry Pi: https://phoenixnap.com/kb/docker-on-raspberry-pi

Configuring Uptime Kuma with Docker Compose

Now that you have Docker and Docker Compose installed, you can configure Uptime Kuma using a Docker Compose file. A Docker Compose file is a YAML file that defines the services, networks, and volumes that make up your application. In this case, we'll use a simple Docker Compose file that creates a service for Uptime Kuma. Uptime Kuma stores its data in SQLite, bundled inside the container, so there is no separate database service to run and nothing extra to back up beyond the container's data volume. If you have seen Mongo mentioned in older guides, that information is out of date.
To configure Uptime Kuma with Docker Compose, follow these steps:

• Create a directory for your project by running this command:

mkdir uptime-kuma && cd uptime-kuma 

• Create a file named docker-compose.yml. Use whatever text editor you fancy. I will be using nano:

nano docker-compose.yml 

• Paste the following content into the file. This is adapted from the official compose.yaml in the uptime-kuma repository, with a few changes.

# Simple compose.yaml
# You can change your port or volume location

services:
 uptime-kuma:
  image: louislam/uptime-kuma:2
  container_name: uptime-kuma
  volumes:
   - uptime-kuma-data:/app/data
  ports:
   - "3001:3001" # <Host Port>:<Container Port>
  restart: always

volumes:
 uptime-kuma-data:

This file tells Docker Compose to pull the Uptime Kuma 2.x image from Docker Hub, name the container as uptime-kuma, restart it automatically if it crashes, expose port 3001 to the host, and mount the data directory to the container.

The image tag is worth understanding. That :2 is deliberate. Uptime Kuma 2.0 shipped in October 2025, and the 1.x line stopped receiving releases in December 2024. The :1 tag still resolves, so a guide telling you to use it will appear to work, but it pulls software that has been frozen for around two years and is not getting fixes. Older versions of this post recommended :1 on the assumption that it always tracked the newest release. That stopped being true when v2 came out. Use :2 for the current stable line, :latest if you want the newest release, or louislam/uptime-kuma:2-rootless for the rootless variant, which has been published since 2.5.0.

Note also that the version: key that older Compose files carried is obsolete. Compose v2 ignores it and prints a warning, so it is left out above.

Create the data directory defined in the compose file:

  mkdir uptime-kuma-data

You can modify the file according to your needs, such as changing the port number, the image tag, or the volume path. For example, you can the following under services to prevent the application processes inside the container from gaining new privileges during execution.

  security_opt:
   - no-new-privileges:true

You can check out complete docker and docker compose lessons for the following books:

• Docker in Action (Amazon Affiliate Link)
• Learning Docker (Amazon Affiliate Link)

Save and exit the file, then start Uptime Kuma:

docker compose up -d

It will take a few seconds for the container to start. Check its status:

docker compose ps

You should see a container named uptime-kuma with a state of Up. To follow the logs:

docker compose logs -f

To stop it:

docker compose down

Upgrading later is a pull and a recreate, which keeps your data volume intact:

docker compose pull
docker compose up -d

Deploying Uptime Kuma on Linode

If you want to make the process easier and convenient, you can deploy Uptime Kuma on Linode using the marketplace (Linode is now branded Akamai Cloud Computing, though the Linode name and console URLs still appear throughout their documentation). The marketplace contains images with the software pre-installed.

From the Akamai (Linode) console, the Marketplace deployment is a short click-through:

1. Signup or Log in to your Linode account and click on the "Create" button at the top right corner and select "Marketplace" from the menu. You can also select "Marketplace" directly from your left menu.
2. Search for "Uptime Kuma" in the search bar and click on it.
3. Once selected, you will need to supply an email address that will be used to get an SSL certificate from Let's Encrypt SSL certificate. While optional, it is also recommended to create a limited sudo user and disable root access over SSH for security purposes.
4. Choose a password for your user. Preferably, you need to add some additional configurations, such as SSH keys, backups, tags, for best security practices. SSH passwords are prone to brute force attacks.
5. You can configure the domain settings as well using the Linode API key. This is an optional step and so we can skip it. You can find full details on how to configure this in the full guide
6. Choose a region where you want to deploy Uptime Kuma. Ideally, you should choose a region that is close to your location to reduce the latency.
7. Choose a plan that suits your needs and budget. For Uptime Kuma, you don't need much of a server at all. The Nanode 1 GB plan is around $5/month and is more than sufficient for monitoring dozens of endpoints, so start there and only scale up if you are tracking hundreds. The current shared CPU plans are listed below.

The prices below are the published shared CPU list prices for Akamai's North America regions. Prices vary by region, so treat them as a guide rather than a quote.

8. You will be required to provide a password for the root user, even though it is disabled. You will also select the SSH key you will be using or can create one, using the guide provided by Linode.
9. Complete the creation of the linode.

It will take a few minutes for Linode to provision your server and install Uptime Kuma on it and you'll see a green checkmark next to your server name when the process is complete. Once complete, you can access your linode using the IP address on https or via the  Compute Instance's rDNS domain (such as 192-0-2-1.ip.linodeusercontent.com). Here is the guide on how to get the rDNS of your VPS on Linode. If you set up a custom domain during deployment, you can reach Uptime Kuma at https://DOMAIN/, where DOMAIN is the domain you supplied.

Because the marketplace image provisions its own reverse proxy and certificate, this route gets you a working HTTPS setup without configuring nginx or Certbot yourself. That is the main reason to prefer it over the Docker route, and also the reason it is less instructive: you learn less about what is actually running.

Deploying Uptime Kuma using Caprover

You can also deploy Uptime Kuma as a one click app via an app/database deployment & web server manager like Caprover. Deployment is simple once CapRover has been installed. Here is a full guide on how to set up CapRover. If that guide does not load for you, it has not been restored yet; the CapRover deployment works the same way, and the official CapRover documentation covers the installation.

1. Once installed, navigate to the apps, and then select One Click-Apps/Database
2. Search for Uptime Kuma among the many applications and select it
3. Give it a name that will help you recognize it among the different apps that will be hosted on your Caprover manager. Note that the name you give it will be part of the domain name you will use to access the application. This is the domain that you set up initially during the CapRover setup. Follow the guide here.
4. For the version number, use 2 for the current stable line, or a specific version number if you prefer to pin one. Do not use 1. That tag is frozen at the 1.x series and no longer tracks the newest release, so it installs software that stopped receiving fixes.

CapRover's caprover CLI does not create one-click apps. Its commands are limited to serversetup, login, deploy, list and logout, so the app is created from the dashboard as described here.

5. Navigate to the app from the dashboard once it has been installed and make a few changes. First, enable HTTPS, and then force all HTTP traffic to be redirected to HTTPS. Also make sure you enable WebSocket support. Otherwise, Uptime Kuma will not work. Note that to access the dashboard, you will not need to append the port number as it was the case in the previous deployment methods.

Those three toggles live in the app's HTTP Settings. Here is what each one does and why it matters:

Wait for a few minutes before trying to access the dashboard. If you get a 404 error, it means the app is still being configured in the backend. You can watch the build from the app's Deployments tab, which shows the build log for the current release; the 404 clears once the build finishes and the container is healthy.

Deploying Uptime Kuma using Other methods

Uptime Kuma can also be deployed using other methods other than docker and on the cloud as described above. For example, you can deploy Uptime Kuma using Node JS and PM2 on any server, including windows hosts.

Although not fully tested, Uptime Kuma can also be deployed using OpenShift 4 and Kubernetes Helm 3 Chart. You can also automate the deployments via Ansible. Feel free to check out the official deployment guide for the other supported methods of deploying Uptime Kuma.

If you run Uptime Kuma in a home lab and want to reach it from outside, do not simply forward the port. Put it behind a reverse proxy with TLS, and enable WebSocket support, as described below.

In order to expose Uptime Kuma to the web securely, it is recommended to proxy it behind a traditional webserver such as nginx or Apache. Unlike other web apps, Uptime Kuma is based on WebSocket. You need two more headers  "Upgrade" and "Connection" in order to accept WebSocket on a reverse proxy. You can check out the full guide on how to configure reverse proxies using different services in the official guide of how to configure reverse proxies for Uptime Kuma.

Securing Your Uptime Kuma Instance

A monitoring dashboard is a tempting target. It knows the shape of your infrastructure, it usually sits internet-facing, and by design it holds notification credentials that can post to your Slack, Discord or Telegram. A few things are worth doing before you leave it running.

• Do not expose port 3001 directly. Put it behind a reverse proxy with HTTPS, and make sure WebSocket support is enabled, because Uptime Kuma depends on it. The reverse proxy guide above covers this.
• Enable two-factor authentication (2FA). Uptime Kuma 2.x supports it, and it is the single highest-value setting on this list.
• Keep the container current. The 1.x line was frozen in December 2024, and a moderate server-side template injection (SSTI) issue was fixed in the 2.2.x releases. Running :1 or an old pinned version means missing that class of fix, which is the practical argument for following the :2 advice earlier rather than copying an older guide.
• Use no-new-privileges, as shown in the compose file above, so processes inside the container cannot gain extra privileges.
• Back up the data volume. Everything lives in that SQLite file: monitors, history, credentials. Losing it means rebuilding the whole dashboard by hand. A periodic copy of the uptime-kuma-data volume is enough.

Accessing Uptime Kuma

Now that you have Uptime Kuma up and running, you can start exploring its monitoring capabilities. To access Uptime Kuma's web interface, open your browser and go to http://[IP]:3001 if you're using your home lab, or http://your-VPS-ip:3001 if you're using a VPS on the cloud. If you setup Uptime Kuma using Caprover, make sure to access the dashboard via the URL that appears on the dashboard. You should see a welcome screen that asks you to create an admin account. Enter your desired username and password, and click on "Create Account". You'll be taken to Uptime Kuma's dashboard, where you can add and manage your monitors.

Exploring Uptime Kuma's Monitoring Capabilities

Uptime Kuma supports various types of monitors that allow you to check the availability and performance of your websites, servers, and services. A monitor is a service that checks the status and performance of a website, server, or service at regular intervals.
Uptime Kuma supports several types of monitors: website monitor, HTTP monitor with keywords, DNS monitor, ICMP ping monitor, TCP port monitor and many more. Each monitor type serves different purposes and offers valuable insights into the health of your systems.
Let us explore some of the monitor types that Uptime Kuma offers:

Adding a Website Monitor

A website monitor is a simple monitor that checks if a website is up or down by sending a HTTP(s) request and expecting a response. To add a website monitor, click on the "Add Monitor" button on the dashboard, and select "HTTP(s)" as the monitor type.

You'll need to enter the URL of the website that you want to monitor, and optionally change the name, interval, timeout, and notification settings of the monitor. You can also enable advanced options such as HTTP method, headers, body, ignore TLS/SSL error, and follow redirect. The HTTP(s) monitor also checks for expiration dates of SSL certificates.

The fields that matter on the HTTP(s) form:

After saving the monitor, Uptime Kuma will start checking your website every few minutes (depending on your interval setting) and display the status on the dashboard. You can also set up Uptime Kuma to send notifications if your website goes down or up. We will cover that below.

HTTP Monitoring with Keywords

HTTP monitoring with keywords is a more advanced monitor that checks if a website contains a specific keyword or phrase in its response body. This is useful for verifying that your website is not only up, but also functioning properly.

To add an HTTP monitor with keywords, follow the same steps as adding a website monitor, but enable the "HTTP(s) Keyword" option under monitor type . You'll need to enter the keyword or phrase that you expect to find in your website's response body.

The keyword monitor is the HTTP(s) form with a few extra fields: the Keyword itself, an Invert Keyword toggle for treating the keyword's absence as the healthy state, and a case-sensitivity option. The keyword check runs only when the HTTP request succeeds; if the request itself fails, the monitor is down regardless of the keyword.

For example, if you want to monitor a blog post that contains the word "Uptime Kuma", you can enter "Uptime Kuma" as the keyword. Uptime Kuma will then check if your website's response body contains that word, and alert you if it doesn't.

DNS Monitoring

DNS monitoring can be useful, especially when making sure that custom DNS servers are working properly as expected.

To add a DNS monitor, follow the same steps as adding a website monitor, but select the "DNS" option under monitor type . You'll need to enter a hostname that you will want to resolve and the DNS server you want to monitor. this will vary depending on your scenario and can be either an internal or an external DNS server.

The DNS monitor can also be used for other DNS records. Check the resource record type drop down for more options:

ICMP Ping Monitoring

ICMP ping monitoring is a monitor that checks if a server or device responds to an ICMP ping request. This is useful for testing the basic connectivity and latency of your systems.

Of course Uptime Kuma can be used to monitor other services beyond HTTP, DNS and ICMP. Be sure to check out the other services to find one that can suit your needs.

Setting Up Notifications

One of the critical components is notifications, since you don't want to sit there the whole day looking at dashboards. Uptime Kuma by default has integrations with quite a number of notification providers, including social sites like slack and discord. Uptime Kuma also supports Apprise which supports up to 78+ notification services. You can check out the full list of supported providers on GitHub.

To get notified when services go down:

1. Go to "Profile" > "Settings", then open the "Notifications" tab.
2. Click "Setup Notification".
3. Select notification service (Slack, Discord, Telegram etc).
4. Configure the webhook or credentials and the other options the chosen service needs. Slack, for example, needs an incoming-webhook URL:

5. Check "Enable for all monitors" to apply alerts globally.

Test by bringing a monitor into a warning/critical state. The notification service should receive an alert.

Accessing Status Pages

Uptime Kuma includes a customizable status page to monitor service status at a glance:

1. Go to "Status pages" and click "Add new status page"
2. Add desired monitors/groups and customize layout
3. Publish page
4. Access public status page URL

This provides a dashboard overview that can be embedded on websites, dashboards, TVs and more. A useful pattern is to run Uptime Kuma alongside the services it watches, which is how it tends to end up on the same host as something like a self-hosted Vaultwarden instance.

And that covers the basic setup and configuration of Uptime Kuma! Let me know if you have any other questions.