Uptime Kuma: self-hosted monitoring tool (2024)

Introduction
Dashboard
Step 1 — Create the environment
Step 2 — Configuration
Step 3 — Setup server monitoring
Step 4 — Setup website (indoor) monitoring
Step 5 — Setup website (outdoor) monitoring
Step 6 — Test
Step 7 — Enable 2FA
Step 8 (bonus) — Set up notification
Conclusion

In this article, I’ll show you how I set up the Uptime Kuma tool to monitor my infrastructure. As you’ll see, it’s a very easy-to-use tool, with a very user-friendly interface.

Important: When configuring this monitoring tool for websites, hosts, or services, it’s crucial to avoid placing it on the same machine as the monitored entities. If the monitoring tool or its host machine goes down, it won’t be able to trigger alerts for potential issues with your sites, services, etc. Therefore, it is essential to ensure that your services or websites are hosted on a separate machine for reliable alerting.

With this tutorial you should be able to have dashboard like this:

Create a directory called uptime-kuma-data

mkdir uptime-kuma-data

Go to the folder and create the docker-compose.yml for the container:

version: '3.3'
services:
 uptime-kuma:
 image: louislam/uptime-kuma:latest
 container_name: uptime-kuma-medium
 volumes:
 - ./uptime-kuma-data:/app/data
 ports:
 - 3001:3001
 restart: always

If you prefer, you can find it on the github of Uptime Kuma:
https://github.com/louislam/uptime-kuma

Finally, run it

docker-compose up -d

To configure the tool, open your browser and go to the following url: http://<your-machine-ip>:3001

Choose the language and create an account and password for the tool

This is what the home page looks like:

To add a new check, you can press +Add New Monitor

Chose Ping from the General Monitor Type list

Then configue a Friendly Name for the host you want to monitor, a Hostname, the Heartbeat Interval of the check and the maximum number of Retries before the service is marked as down

In the Tags part, press +Add

And create a new tag called Server (you can also choose a color!)

Finally, press save and the check will begin

To be able to see if my website has a problem outside or if it’s a problem with my reverse proxy, I’m going to create two checks, one indoor with the local address of my website and another outdoor with the URL from which the site can be reached outside my network.

Press +Add New Monitor and this time choose TCP Port for Monitor Type

Configue a Friendly Name for the website you want to monitor, a Hostname, the Heartbeat Interval of the check and the maximum number of Retries before the service is marked as down

Finally, add a new tag called Service and pick a color

Perfect, the check is now running!

Again, press +Add New Monitor but this time choose HTTP(s) for Monitor Type

As for the others, choose a Friendly Name and this time enter the URL of the website, not the hostname

In the Advanced part, under Accepted Status Codes I’ve added status 300–399 in addition to status 200–299, because Grafana makes a lot of redirects so it’s normal to have a status code between 300 and 399 for this website (of course it depends on the website you want to monitor)

If you’re interested in Grafana, I’ve written another article about it, this time for monitoring Nginx logs

let’s get back to the subject, go to the Tags part and select the previously created tag service and press Add

Basic Auth configuration

If, like me, your website has a basic auth in front of it, you can configure the check so that it can log in and check if the website is running correctly or not

To do that, go to the Authentication part and select HTTP Basic Auth

Then enter the username and the password to access the website or the token if you have configured one

Press Save at the bottom of the page and the check is done

On the check page we have just created, you will find the following information, including one indicating the number of days remaining before the site’s SSL certificate expires.

Alright, now we have our 3 checks working perfectly!

To see how the dashboard reacts, I’m going to stop my Grafana

$ docker-compose down
Stopping grafana-loki_promtail_1 ... done
Stopping grafana-loki_grafana_1 ... done
Stopping grafana-loki_loki_1 ... done
Removing grafana-loki_promtail_1 ... done
Removing grafana-loki_grafana_1 ... done
Removing grafana-loki_loki_1 ... done
Removing network grafana-loki_loki

See? My Grafana’s check status now shows DOWN

You can also see the error by looking at the bottom of the check page

Here a 502 error → for backend error (which is normal because I stop the service)

To activate double authentication, click on your initial to the right of the Dashboard button, a drop-down menu will appear then go to Settings

Go to the Security part and press 2FA Settings

From here, you can configure your 2FA application by scanning the QR that appear.

Set up Uptime Kuma to work with ntfy. Find out how in this article below:

You can now monitor your hosts or website over time. I’ve really only covered the basics in this tutorial, as a fuller explanation would have been far too long for here. Take your time to explore this tool for yourself, as it hides many surprises I haven’t covered yet.

If you have any questions about this project, please leave a comment below this post, and I’ll try to answer them as soon as possible :)