How to Set Up An Uptime Monitoring Tool in Linux with Uptime Kuma

Uptime Kuma is a simple yet powerful uptime monitoring tool. It allows you to keep track of every service that you are hosting either on a local network or to the wider internet.

This article will show you how to install and deploy Uptime Kuma on a local network using Ubuntu and Docker. We will also show you how to customize the Uptime Kuma instance to send status notifications to Telegram.

Why Use Uptime Kuma?

Uptime Kuma can track and ping web servers as well as check the health of your Docker containers. This makes Uptime Kuma the ideal all-in-one web portal for all of your network services.

One of the biggest advantages of Uptime Kuma is that comes with a robust notification system by default. This means that you can set your uptime monitor to automatically send a message through a variety of channels whenever it finds an anomaly.

Installing Uptime Kuma

Obtaining Docker and Docker Compose

First, fetch the GPG signing key for the Docker and Docker Compose repositories:

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

Create a new repository file for Docker under “/etc/apt/sources.list.d/”

sudo nano /etc/apt/sources.list.d/docker.list

Paste the following line of code inside your new repository file:

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable

Update and upgrade the package repository for your Ubuntu system:

sudo apt update && sudo apt upgrade

Install the Docker and Docker Compose package along with their dependencies:

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

Ensure that your currently running user has the right privileges to run Docker and Docker Compose:

sudo usermod -aG docker ramces

Obtaining and Building Uptime Kuma

Create a new directory for your Uptime Kuma Docker container. This will contain the recipe file for your instance:

mkdir uptime-kuma && cd ./uptime-kuma

Once inside, create a new “docker-compose.yml” using your favorite text editor:

nano ./docker-compose.yml

Paste the following block of code inside your new Compose file:

---
version: "3.8"
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - uptime-kuma:/app/data
    ports:
      - 3001:3001
    restart: always
volumes:
  uptime-kuma: null

Build the Docker containers for your new Uptime Kuma instance:

sudo docker compose up -d

Creating a Reverse Proxy for Uptime Kuma using Nginx

We will create a reverse proxy in Nginx so you can access Uptime Kuma on a publicly accessible URL.

Create a new Nginx site configuration file using your favorite text editor:

sudo nano /etc/nginx/sites-available/uptimekuma

Write the following block of code inside your new site configuration file:

server {
 
        server_name uptime.myvpsserver.top;
 
        location / {
                proxy_pass http://127.0.0.1:3001;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header Host $host;
        }
}

Link your site configuration file from Nginx’s “sites-available” folder to its “sites-enabled” directory:

sudo ln -s /etc/nginx/sites-available/uptimekuma /etc/nginx/sites-enabled

Restart your Nginx server daemon to apply your new settings:

sudo systemctl restart nginx

Installing the SSL Certificate

To start, you need to make sure that your system has the core snap package up and running:

sudo snap install core

Install the snap for the Electronic Frontier Foundation’s certbot. This is a small tool that can automatically request and maintain your reverse proxy’s SSL certificate:

sudo snap install certbot --classic

Test whether certbot is properly working by signing up your new certbot installation to the EFF:

sudo certbot register --agree-tos -m ramces@email.invalid

Request a new SSL certificate for your new reverse proxy:

sudo certbot --nginx -d uptime.myvpsserver.top

Configuring Uptime Kuma and Adding Monitors

Check whether your Uptime Kuma installation is running properly on its reverse proxy by navigating to its address in a web browser.

Fill in the form with the details you want for your new administrator account, then click “Create” to continue to your instance.

Click the “Add New Monitor” button on the page’s upper left corner.

This will open up a new subwindow on the current page where you can specify the type of service that you want to monitor. For example, changing the “Monitor Type” value from “HTTP(S)” to “TCP Port” will create a monitor that will check whether a particular port in the machine is currently open.

Fill in the details of the machine that you want to monitor.

Scroll down to the bottom of the page, then click “Save” to start your new monitor.

Setting Up External Notifications for Uptime Kuma

Go to the main page of your Uptime Kuma instance and click the user icon on the page’s upper right corner.

Click the “Settings” option on the page’s drop-down menu.

Select the “Notifications” category on the page’s new subwindow.

Creating a Telegram Notifications Service

Click the “Setup Notification” button. By default, this will bring up a small window where you can link and create a notification bot using your Telegram account.

Provide a name for your new notification alert, then click the BotFather link under the “Bot Token” textbox.

Click the “Send Message” button on the BotFather’s Telegram page.

Note: The “Send Message” button is a Telegram-specific link that will only work if Telegram is running on your machine. Learn how to install Telegram on your Linux machine.

This will open up a new chat window where you can use the BotFather to create your notification bot. Write “/newbot” on the prompt, then press Enter.

Provide a name for the bot that you are linking to your Uptime Kuma instance.

Write an appropriate username for your new notification bot. Note that for this, the BotFather will not accept any special character aside from underscore (_).

Click the text that the BotFather highlighted to copy it to your clipboard.

Test whether your new bot is properly working by looking up its username and starting a conversation with it.

Go back to your Uptime Kuma instance, then paste the private bot token inside the “Bot Token” textbox.

Click the “Auto Get” button under the “Chat ID” textbox.

Scroll down to the bottom of the Uptime Kuma window, then click “Test” to check whether Uptime Kuma can communicate with your new bot.

Click “Save” to commit your changes to Uptime Kuma.

Hosting a simple service status daemon over Docker is just the tip of the iceberg when it comes to deploying containerized web services. Learn how you can host your own cloud office with ownCloud as well as run your own Pastebin with Stikked.

Image credit: Boitulmelo via Unsplash (Background) Github (Logo). All alterations and screenshots by Ramces Red.

Ramces Red - Staff Writer

Ramces is a technology writer that lived with computers all his life. A prolific reader and a student of Anthropology, he is an eccentric character that writes articles about Linux and anything *nix.