Monitor your Entire Home Lab with Uptime Kuma

  • Post author:WunderTech
  • Post published:May 15, 2024
  • Post last modified:May 15, 2024
  • Post category:Docker
  • Reading time:7 mins read

Share what you're reading!

Uptime Kuma is something that I configured a long time ago, but never really configured until this past weekend. I sat down, added all of my important servers, services, networking equipment, security cameras, and basically anything that I actually want to stay online, then configured notifications, and now I have a functional monitoring service running inside of Docker.

Uptime Kuma is awesome, but it’s only as awesome as you make it, so let’s look at how to configure it on Docker and then how to customize it.

How to Install Uptime Kuma with Docker Compose

The easiest way to configure Uptime Kuma is by using Docker Compose. It doesn’t matter which device you’re using and can configure this on something like Portainer, Synology’s Container Manager, or even just through the CLI with Docker Compose.

Modify the script below to point the volume to a location on your Docker host, then create the container. It’ll be different based on the application you’re using, but this will be a path on your Docker host. The /var/run/docker.sock path is so that we can monitor the Docker Containers on our host.

version: '3.3'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    volumes:
      - /your_path_here/:/app/data
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 3001:3001
    restart: always
uptime kuma docker compose

After the Docker Container is configured, access Uptime Kuma by navigating to the IP address and port, then create a user account.

http://DOCKER_IP:3001

Configuring Uptime Kuma & Creating Monitors

Now that Uptime Kuma is installed, we can configure the application. Each monitor will be different based on the type of monitor. For example, if you’re using a Hypervisor like Proxmox, you might want to monitor the web interface (HTTP(s) or just ping the server by IP). There isn’t a right or wrong answer, but you’ll have to make this decision based on each service.

  1. Add a new monitor, select a Monitor Type, then paste in the hostname/IP address and port. Based on the Monitor Type, you’ll have different required fields to configure.
adding a new monitor

2. You can then add the device to a Group, add any tags, and determine how often the device or service should be checked (heartbeat). Upside Down Mode can be configured if you’d like the device to be OFF and report as UP. This is helpful if you’d like to ensure that a device stays offline.

monitor settings.

Configuring Access for Docker Containers

The Docker Compose file we used allows us to monitor our Docker Containers by name. Select Settings, then Docker Hosts, and Setup Docker Host. From there, give it a name and Test the connection. If it succeeds, select Save.

setting up a docker host.

Now when you configure a Monitor, you can monitor the Docker Container directly by entering its name or Container ID.

creating a docker monitor by using the docker host.

Configuring Notifications

This is arguably the most important part. If you configure notifications, you’ll be alerted when a device goes offline. This is determined by the Retries parameter, meaning that if you’d like a system to report as offline five total times before being alerted, you’d modify that parameter to be five.

This is helpful for external websites, as I’ve noticed with mine that it may report as offline even if it’s online, so I changed that service to three and now won’t receive alerts unless the system is down three total times.

heartbeat interval.

In terms of configuring notifications, select your icon in the top right, then Settings, and finally, Notifications. From there, select Setup Notification.

setting up notifications.

At this point, you’ll have to select a Notification Type. It’s going to be totally different based on the notification you’d like to receive (Email, SMS, Push Notification, etc), but after you configure it, you can check off if you’d like this notification to apply to all existing monitors and if it should be enabled by default.

notification settings.

With the monitors configured properly and notifications set up (even multiple, if you’d like certain types based on severity), you’ll have a fully functional monitoring service set up in a self-hosted environment. Just keep in mind that as with everything, if Uptime Kuma is down for whatever reason (server hosting it, network, etc), you won’t receive any notifications.