Awesome Website Monitoring With Uptime Kuma
Check your site with this intuitive, lightweight program
In this article, I want to share my experience setting up monitoring for my websites. While other monitoring stacks like using prometheus, node-exporter, and graphana in combination with alerting provide a ton of cool features, I want to present a lightweight and easy stack. The core component of this stack is a project called uptime-kuma. It’s written in node.js and vue and comes with a really beautiful UI. The main arguments that convinced me to run uptime-kuma are:
- Super easy setup and configuration
- Awesome UI
- Simple integration of telegram notifications
- A neat set of configurations for checking websites
So let’s get started with deploying uptime-kuma. I love to use traefik as a reverse proxy deployed using docker-compose. This easy one-host setup allows you to issue LetsEncrypt certificates for domains automatically.
So, here is all that you need for the setup: A host with a public IP address, a domain under which your monitoring should be accessible, and an A record that points the domain to the respective host. On the host, you need to install docker and docker-compose. There are several guides on installing both tools for different OSes, for example, docker and docker-compose. That’s it.
Traefik Docker-Compose Deployment
For traefik, there are tons of different compose files only, so you can choose whatever you prefer. If you just want to follow this guide, let me show you mine. I like to put the docker-compose deployments under /usr/docker. So for traefik, we have the following files under /usr/docker/traefik. First, the following content needs to be put into docker-compose.yml:
The compose file contains one service and one network. The service is the traefik container with some command line flags. Mainly, you just need to change your email. If you want to avoid running into rate limits of LetsEncrypt while testing with your setup, you can change the acme resolver to staging (see the comment in the gist). You can request as many certs as you like without rate limiting but will get certificates that are not automatically trusted by browsers.
So it’s not for production use. The traefik service forwards the ports 80 and 443 for HTTPS traffic and 127.0.0.1:8080 for the dashboard, which is only accessible from localhost. Furthermore, there is one external docker network called reverseproxy. We will attach all containers for which traefik will serve as reverse proxy to this network. The second file we need to put in this folder is traefik.toml:
This config sets the entry points for HTTP and HTTPS traffic and the logging. That’s it for traefik.
You can now run the following commands in the /usr/docker/traefik folder:
- docker network create -d bridge reverseproxy
- touch access.log
- docker-compose up -d
Uptime-Kuma Docker-Compose Deployment
For uptime-kuma, the authors provide a docker-compose file that works out of the box. To run it behind traefik with LetsEncrypt certificates, we just need to change it to the following /usr/docker/uptime-kuma/docker-compose.yml file:
We need to configure some traefik labels to let traefik obtain the correct certificates for the domain. Furthermore, the uptime-kuma container needs to be added to the reverse-proxy network so that traefik can forward incoming traffic to it. Finally, just run the following command in your uptime-kuma folder to start the container: docker-compose up -d
Configuring Uptime-Kuma
The first time you access your uptime-kuma instance, you must configure a secure admin password. Once you’re done, you can start adding endpoints. The UI looks like this. You can define particular behaviour on how and how often uptime-kuma should check your website, for example, HTTP return codes, certificate validation, etc. It’s great.
Once you’ve added your first endpoints, I recommend configuring telegram notifications. With this, you will be notified whenever one or more endpoints are not working as expected. It’s quite easy to set up telegram notifications. You need to create a group, a bot, and configure the Chat ID of the group and the bot token in uptime-kuma.
So, let’s do it step by step. To create a bot, you need to write the Botfather. Go to telegram (or web telegram), open a chat to Botfather (follow the link in the doc), then write /newbot as a command to the bot. You need to give it a name and a username following the requirements. You can see your token, which is the first part of the configuration you need for uptime-kuma.
Now, create a new telegram group and add the bot to it. You can now get the chat id by following the instructions here. Basically, you need to write a message in the group chat, make a get request with whatever tool you like to https://api.telegram.org/bot<YourBOTToken>/getUpdates, and then look for the chat field. Sometimes this number is negative. Don’t worry, that’s fine.
With the chatId, you can complete the configuration. You may test the telegram notifications with the button in the settings dialog.
Summary
This article shows you how to install uptime-kuma in combination with the traefik reverse proxy and how to configure telegram notifications. In my opinion, it’s a great tool for monitoring websites with many useful settings. I can definitely recommend using it if you only need to ensure that your websites are running properly.
Please feel free to share any feedback. I’d be glad to add it to this article.
