---
title: "Monitoring with Uptime Kuma 🐻"
categories:
  - homelab
tags:
  - monitoring
  - "uptime kuma"
  - nginx
  - "oracle cloud"
---

## 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](https://uptimerobot.com/) or [Upptime](https://upptime.js.org/), but with a need for budget conscious flexibility it was time to explore some new options.

[Check out the result here!](https://status.rusz.dev)

### Uptime Kuma

After some consideration I settled on [Uptime Kuma](https://uptime.kuma.pet/), 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.

![A screen capture of Uptime Kuma's dashboard page](/assets/posts/2025-03-17-kuma/dashboard.png)

### 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](https://www.oracle.com/cloud/free/). 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](https://ubuntu.com/download/alternative-downloads) 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.

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

Next, I installed [Nginx](nginxhttps://nginx.org), [Certbot](https://certbot.eff.org/), and [Docker](https://docker.com) using their [installation instructions](https://docs.docker.com/engine/install/ubuntu/), and enabled the Nginx service.

```bash
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.

```json
{
  "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`.

```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.

```yml
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.

```bash
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](https://github.com/louislam/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.

```nginx
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.

```bash
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.

```bash
sudo certbot --nginx
```

### Uptime Kuma Configuration

Excellent documentation for configuring your monitors and status pages can be found in the [Uptime Kuma repository](https://github.com/louislam/uptime-kuma). The wiki also contains all the steps I followed to create this guide.

![A screenshot of my Uptime Kuma status page.](/assets/posts/2025-03-17-kuma/status.png)
