Setting up Uptime Kuma on the Raspberry Pi

This tutorial will show you how you can set up an uptime monitor on your Raspberry Pi using the Uptime Kuma software.

Uptime Kuma is a free and open-source uptime monitor tool that you can easily install on a Raspberry Pi.

Using this software, you can measure the uptime and response time of various services.

Some of the services that Uptime Kuma can monitor are HTTP(s), TCP, PING, DNS Record, Steam Game Servers, docker containers, and more.

If your Raspberry Pi detects an outage, Uptime Kuma can send a notification to various services. These services include Discord, Telegram, Slack, and Email.

Equipment

Below is a list of the equipment we used while setting up an uptime monitor on our Raspberry Pi.

Recommended

• Raspberry Pi
• Micro SD Card
• Power Supply
• Ethernet Cable or Wi-Fi

Optional

• Raspberry Pi Case
• USB Mouse
• USB Keyboard
• HDMI Cable
• Monitor

This tutorial was last tested on a Raspberry Pi 400 running the latest version of Raspberry Pi OS Bullseye.

Preparing your Raspberry Pi for the Uptime Monitor

Let us start by preparing our Raspberry Pi by installing all of the software we require to run Uptime Kuma. Luckily, the software doesn’t have many requirements and is relatively straightforward to prepare for.

1. Before proceeding, we should ensure that we have an updated package list and upgrade any out-of-date packages.

Use the following two commands within the terminal to update your Raspberry Pi.

sudo apt update
sudo apt upgrade

2. With our Pi up to date, we need to install some of the packages we require to run our uptime monitor on the Raspberry Pi.

We only require the “git” package to clone the Uptime Kuma code to your device. You can install this program by running the command below in the terminal.

sudo apt install git

3. Finally, follow our guide on installing Node.JS to the Raspberry Pi.

This guide will walk you through adding the Node.JS repository and installing the runtime to your device.

4. Once you have installed the Node.JS runtime, you can continue to the next section of this tutorial.

Setting up Uptime Kuma on the Raspberry Pi

This section will show you how to install the Uptime Kuma software to the Raspberry Pi. Installing and setting up Uptime Kuma is a simple process thanks to some additional software we can utilize.

Installing Uptime Kuma

1. Now that our Pi is set up, we can clone the Uptime Kuma repository to the device.

Clone the repository by using the command below within the terminal.

git clone https://github.com/louislam/uptime-kuma.git

2. We can now use the cd command to navigate to the directory where we just cloned the Uptime monitor repository.

Inside this directory, we will run commands to compile the monitor and run it.

cd uptime-kuma

3. As we are in the correct directory, we can now set up Uptime Kuma on our Raspberry Pi using the following command.

A few things occur during this process, such as downloading any required dependencies.

npm run setup

4. Using the command below, you can install the “pm2” using “npm” Node.JS’s package manager.

pm2 is a process manager that allows you to run Node.JS programs in the background easily. Additionally, we can also make it so Uptime Kuma will be started when the Raspberry Pi boots.

sudo npm install -g pm2

5. With pm2 now installed on our Raspberry Pi, our next step is to install one of its modules called “pm2-logrotate“.

This module will rotate the log files when certain conditions are met. Additionally, it will remove log files that are passed a certain date. This stops log files from potentially bloating and consuming significant space.

You can install this module by using the command below in the terminal.

pm2 install pm2-logrotate

Running Uptime Kuma on the Raspberry Pi

6. Finally, we can start up Uptime Kuma on our Raspberry Pi using the following command.

This command uses the “pm2” module we installed to run the uptime monitor. It will be placed in the background and identified by pm2 as “uptime-kuma“.

pm2 start server/server.js --name uptime-kuma

7. While we have Uptime Kuma now running, we should now set it up so that it will start at startup.

Before doing this, we must “save” the currently running programs so we can resume them by using the command below.

pm2 save

8. Next, we need to run the following command within the terminal. Running this will generate a command we will need to run to get Uptime Kuma to start up on our Raspberry Pi at boot

pm2 startup

After running the above command, you will need to run the command printed into the terminal. This command will differ depending on your system. The one we were required to run is shown below.

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u pi --hp /home/pi

Using the Uptime Kuma Web Interface

Now that we have installed Uptime Kuma on the Raspberry Pi, we can access its web interface.

1. Before proceeding, if you aren’t running this on your Pi, you will need to know its local IP address.

The easiest way to get the local IP address of your Raspberry Pi is to use the hostname command.

hostname -I

2. With your IP address handy, go to the following address in your favorite web browser. As you can see, Uptime Kuma on your Raspberry Pi operates on port 3001 by default.

Make sure to replace “[IPADDRESS]” with your IP.

http://[IPADDRESS]:3001

3. When you first load up the Uptime Kuma web interface, you will be greeted with the following screen.

Using this screen, you will create the account you will use to log in to the web interface. Fill out the login details for your new account (1.).

Once you have filled out all your details, click the “Create” button (2.) to continue.

4. After creating your account, you will be greeted with a blank dashboard since you wouldn’t have added any monitors.

Adding a monitor using the web interface is a super easy process that you can start by clicking the “Add New Monitor” button.

5. Uptime Kuma will display a bunch of text boxes on the left-hand side of the screen. Using these, you can configure your brand-new monitor.

With the default options, you must at least specify two details for the monitor to be created.

• The first option you must set is the “Friendly Name” (1.). This field dictates the name that will be used for this monitor within the web interface.
• Secondly, you must also specify the URL you want to monitor (2.). With the default monitor type (HTTP(s)), the Raspberry Pi will constantly grab the page and check the status code is OK (200-299).

Once you have configured your new uptime monitor, click the “Save” button (3.) located at the bottom of the page.

5. Your Raspberry Pi will now successfully be using the Uptime Kuma software to monitor your chosen service.

You should immediately start to see data populated for your chosen service. For example, below, you can see how ours looked after running the uptime monitor for a few minutes.

Updating Uptime Kuma on the Raspberry Pi

Once the Uptime Kuma team releases an update you will likely want to upgrade to it. This following section will show you how you can update the software in a few simple steps.

1. First, we will need to change into the directory where we cloned Uptima Kuma to on our Raspberry Pi.

You can change to this directory by using the command below.

cd ~/uptime-kuma

2. Now that you are in the correct directory you will want to use git to pull the latest version of the Uptime Kuma code.

git pull

3. Once the latest version of the code has been cloned, we will now want to re-run the setup script using npm.

npm run setup

4. Once the setup process completes, you now will want to tell “pm2” to restart the Uptime Kuma service by using the following command.

pm2 restart uptime-kuma

5. At this point you should now be running the latest version of Uptime Kuma on your Raspberry Pi.

Conclusion

In this tutorial, we showed you how to set up your Raspberry pi as an uptime monitor using the Uptime Kuma software.

Uptime Kuma as you have seen, is a super modern, sleek, and free uptime monitor packed with functionality.

Please comment below if you have had any issues running Uptime Kuma on the Raspberry Pi.

If you liked this tutorial, you may want to check out our many other Raspberry Pi projects.

Weekly Updates Straight To Your Inbox

Receive our Raspberry Pi projects, coding tutorials, Linux guides and more!

Subscribe