Monitoring with Uptime Kuma 🐻

Tools and Hosting

My homelab is quickly expanding in size, and with the expansion comes a need to monitor the services I provide. In the past I have used tools like UptimeRobot or Upptime, but with a need for budget conscious flexibility it was time to explore some new options.

Check out the result here!

Uptime Kuma

After some consideration I settled on Uptime Kuma, an easy to deploy open source status monitoring solution. Uptime Kuma has all the features that I’ll need for my setup, including status pages, custom notifications, and a strong community following. Those aspects made it a clear choice for me.

Oracle Cloud

Now that I had my monitoring tool selected I required a reliable place to host it. Hosting this tool internally didn’t make much sense. If my homelab internet connection failed at any point, so would my monitoring. I needed to find an affordable cloud based solution.

Enter Oracle Cloud Free Tier. I discovered this option during my recent Matrix homeserver project. As long as you play by Oracle’s rules and stay within their usage limits, they promise their service will be free forever.

I only required a Standard.E2.1.Micro with the minimum sized boot volume. Staying within the set limits was easy, even with my other projects running.

Setup and Deployment

Initial Server Setup

I configured my instance with the Canonical Ubuntu 24.04 Minimal image, saved my SSH keys, and give it some time to spin up.

Once that was complete, I connected to the server with SSH and performed some basic housekeeping.

Updates and Tools

To prepare the fresh instance, I updated its packages and installed some tools I knew that I would need. I also cleared Oracle’s restrictive default IP tables.

sudo apt purge netfilter-persistent iptables-persistent
sudo apt update && sudo apt upgrade -y
sudo reboot now

Next, I installed Nginx, Certbot, and Docker using their installation instructions, and enabled the Nginx service.

sudo dnf install nginx python3-certbot-nginx -y
sudo systemctl enable nginx

Lastly, I needed to open inbound ports 80 and 443 on my virtual subnet so Certbot and Nginx can make Uptime Kumo externally available.

DNS

Now that my instance has a public IP address, it is time to prepare my DNS settings. I created two records pointing toward the instance. One for the Kuma dashboard and one for the subdomain of my status page.

Type	Name	Data	TTL
A	kuma	129.80.234.9	600
CNAME	status	kuma.rusz.dev.	600

Since my website is hosted on GitHub Page, I also needed to add a .well-known/kuma/server, so the SSL certificates I generate later would be accepted.

{
  "m.server": "kuma.rusz.dev:443"
}

If you build your site with Jekyll, be sure to include the .well-known by adding the following to your _conf.yml.

include: [".well-known"]

Uptime Kuma with Docker Compose

The Uptime Kuma team provides Docker images of their releases, making it easy to deploy with Docker Compose.

I created a new directory for Kuma, then created my comopse.yml within. There are several Docker tags available, but I used 1. The shorthand for the latest stable release.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - ./uptime-kuma-data:/app/data
    ports:
      - 3001:3001
    restart: unless-stopped

Lastly, I started the service.

docker comopse up -d

Reverse Proxy with Nginx

Despite the Ubuntu typical pattern of using sites-availible and sites-enabled, I prefer to place my Nginx configuration files directly in /etc/nginx/conf.d/. This helps me avoid any confusion as I frequently work with Rocky Linux and other RHEL-like Nginx solutions.

I used the suggested Nginx configuration from the Uptime Kuma Wiki with one modification. Since I knew I would be adding a subdomain for my main status page, I added it as a server location now. If I had only been planning to use slug based status pages, I would only need to add kuma.rusz.dev as a server.

server {
  server_name kuma.rusz.dev;

  location / {
    proxy_set_header   X-Real-IP $remote_addr;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header   Host $host;
    proxy_pass         http://localhost:3001/;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection "upgrade";
  }

}


server {
  server_name status.rusz.dev;

  location / {
    proxy_set_header   X-Real-IP $remote_addr;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header   Host $host;
    proxy_pass         http://localhost:3001/;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection "upgrade";
  }

}

To apply the configuration I restarted the Nginx service.

sudo systemctl restart nginx

SSL Certificates with Certbot

To finish up my deployment, I used Certbot to generate Let’s Encrypt SSL certificates for my two new subdomains.

sudo certbot --nginx

Uptime Kuma Configuration

Excellent documentation for configuring your monitors and status pages can be found in the Uptime Kuma repository. The wiki also contains all the steps I followed to create this guide.