Uptime Kuma: Open-source monitoring with Docker support

• Author
• Recent Posts

Brandon Lee

Brandon Lee has been in the IT industry 15+ years and focuses on networking and virtualization. He contributes to the community through various blog posts and technical documentation primarily at Virtualizationhowto.com.

Latest posts by Brandon Lee (see all)

• What’s your ENow AppGov Score? Free Microsoft Entra ID app security assessment - Thu, Nov 30 2023
• Docker logs tail: Troubleshoot Docker containers with real-time logging - Wed, Sep 13 2023
• dsregcmd: Troubleshoot and manage Azure Active Directory (Microsoft Entra ID) joined devices - Thu, Aug 31 2023

What is Uptime Kuma?

Uptime Kuma is an open-source project developed and maintained by a community of contributors on GitHub. The project was started by Muhammad Mustadi, a software engineer from Indonesia, who created the initial version of Uptime Kuma in 2019.

Since then, Uptime Kuma has gained in popularity among developers and system administrators as a reliable and easy-to-use monitoring tool for websites, APIs, and services. The project is licensed under the MIT License, which means that anyone can use, modify, and distribute it for free.

The Uptime Kuma community is very active and welcomes contributions from developers around the world. If you are interested in contributing to the project or have any questions, you can visit the Uptime Kuma GitHub repository or join the Uptime Kuma Discord channel.

Uptime Kuma can monitor various applications, databases, and services, including the following:

• HTTP(s), TCP Port, Ping, , gRPC(s), DNS, Docker Container, Push, Steam Game Server, GameDig, MQTT, Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, MongoDB, RADIUS, and RedisOn top of the multiple services it can monitor, Uptime Kuma provides many other great features, including fancy, reactive, and highly responsive UI/UX and modern notifications. It also features a 20-second monitoring interval, custom status pages, map status pages to specific domains, ping chart, certificate info, and proxy support. It can even do 2FA for secure logins.

Uptime Kuma dashboard

Docker container installation and update

Aside from the excellent features of the open-source solution, it is also easy to install and can run as a Docker container; it takes only a few seconds to get up and running with Uptime Kuma. The Dockerized application also makes updating Uptime Kuma easy. Once you have your data configured as a persistent mount on your Docker host or a persistent volume claim in your Kubernetes cluster, you can simply pull the new version of the container to update the application.

Installing Uptime Kuma

There are a couple of ways to install Uptime Kuma. You can use a simple Docker run command, or you can use Docker Compose code to install the Uptime Kuma container in your Docker environment.

Docker run

To pull the Uptime Kuma Docker container, you can use the simple run command below to get up and running with Uptime Kuma quickly.

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1

In the above Docker run command, the restart policy is set to always, and the external port 3001 is translated to the internal port 3001 of the container. We also configure a persistent volume mount for the container using the "-v" switch. Finally, we name the Docker container and specify the image to pull.

Docker compose

You can also use Docker compose to pull down and configure Uptime Kuma as part of your Docker environment. You can use the following Docker compose code to install and configure Uptime Kuma in Docker:

uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: kuma
    volumes:
      - ~/homelabservices/uptime-kuma-data:/app/data
    restart: always
    networks:
      mynetwork

Pulling Uptime Kuma with Docker compose

First login and adding monitors

It is an easy process to set up your admin user and then create your first uptime monitors. Below is the screen you will see when you first log in to your Uptime Kuma environment. It will prompt you to set the language, name the admin, and confirm your password.

First login with Uptime Kuma and creating an admin

Once you have created the login and accessed the Uptime Kuma console, click the Add New Monitor button in the upper left-hand corner.

Adding a new Uptime Monitor in Uptime Kuma

This will launch the Add New Monitor dialog box. Configure the required parameters for the new monitor, including the Monitor Type, Friendly Name, and Hostname. It also includes options for retries and other metrics related to notifications.

Configuring the new Uptime Monitor in Uptime Kuma

You can also configure Upside Down Mode, which allows you to monitor whether a service is reachable. It can flag the monitor as DOWN.

Configuring upside down monitoring

You can configure the notification you want to use with the new monitor. In addition, a handy setting allows you to set the notification as the default enabled, so you can create a notification profile for the first monitor and use this for all other monitors configured.

Configuring notifications for Uptime Kuma monitoring

Building Status Pages

Uptime Kuma has a great built-in feature called Status Pages. The Status Pages allow you to create the type of page you have seen from major cloud services that display the health of their services. Essentially, you can create an easy-to-read status page displaying the health of custom-monitored services and present these pages to end users.

Adding a new status page

Configure a name and slug for the new status page on the Add New Status Page screen. Click Next.

Name the status page and create a page slug

You can create new groups, allowing you to add configured service groups. However, you can also add any single uptime monitors you have configured. For example, below, we are adding the monitor TestUptime1.

Adding services to the Uptime Kuma Status Page

The Status Page is highly customizable. You can add custom CSS, change the log, and add description and footer text.

Save the Uptime Kuma Status Page

After saving the new Status Page, users can navigate to the slug URL configured for the Status Page and view the status of monitors configured with Uptime Kuma.

Viewing the Status Page

Wrapping up

Uptime Kuma is a great free and open-source solution for monitoring the core functionality of servers, applications, and other resources. It provides a great-looking tool to present uptime information to end users in the form of Status Pages, providing the look and feel of the cloud service status pages that users are accustomed to seeing. In addition, it offers modern notification services that can be configured for your monitors, allowing you to take advantage of platforms such as Telegram, Slack, and others. While it does not contain the depth of monitoring that a commercial monitoring solution provides, it is a powerful tool that monitors the uptime of business-critical services.