Setup of Standalone Uptime Kuma on Ubuntu with a Reverse Proxy

Introduction

This tutorial describes how to set up an Uptime Kuma instance on Ubuntu 20.04. Uptime Kuma is a free and open source uptime monitor. It is a self-hosted alternative to services like Uptime Robot or StatusCake. It is available as a Docker image, but this tutorial describes how to set up an instance without Docker (as a standalone).

This tool is very useful for getting notified when a service is down.

The time needed to follow this tutorial is approximately 10 - 20 minutes.

The tutorial was tested on Ubuntu 22.04 (November 2023).

The tutorial uses the example ip 123.123.123.123.
This hostname needs to be replaced by the name of your own server when you perform the steps described below.
We will also use the domain example.com in this tutorial. Replace it with your own domain.

We will not use the installation script provided by Uptime Kuma, because it is sometimes buggy.

Requirements

For a 'small instance' (up to 20 monitored services) VPS 200 is sufficient.

I recommend setting up the instance on a VPS 200.
If you feel like the instance is slowing down, you can always update to a bigger server trough the CCP.

The server needs to have Ubuntu 20.04 and SSH already installed.

You will also need a domain. A domain used in a webhosting package is sufficient. (You can still use it for your webhosting, because we will use a subdomain.)

Step 1 - Finding out the IP of your server

1. Log in to the SCP (ServerControlPanel) under https://www.servercontrolpanel.de.
2. Click on the server you want to use.
3. If you are already on the "General" tab, you'll see a pane labeled "Network" in the bottom right corner.
4. Here you can find the IP of your server (under IPv4).
5. Write the IP of your server down.

Step 2 - Configuring DNS

1. Log in to the CCP (CustomerControlPanel) under https://www.customercontrolpanel.de.
2. In the sidebar on the left, click on "Domains".
3. Find the domain you want to use and click on the magnifying glass symbol next to it.
4. In the new window, click on "DNS".
5. Scroll down until there are empty fields.
6. In the first field, write your subdomain name (I recommend using "status").
7. In the dropdown menu, select A.
8. In the last field, enter the IP of your server (from Step 1).
9. Click on "Save DNS records".

Step 3 - Preparing the server

First you need to log in to your server via SSH, then follow these steps:

1. Enter sudo -s to get root privileges.
2. If asked for your password, enter it and press Enter.
3. Now enter apt update -y && apt upgrade -y to update the server.
4. If a pink window appears, press Enter once to continue.
5. Enter apt install curl nginx git -y to install all the required software.
6. Enter adduser uptimekuma --gecos "" --disabled-password && su uptimekuma to create a new user and switch to it.

Step 4 - Installing Node.js

1. Enter cd && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash to install NVM.
2. Enter source ~/.bashrc to install all the required software.
3. Enter nvm install 18 && nvm use 18 to install and activate NodeJS 18.
4. Enter npm install npm pm2 -g && pm2 completion install to install pm2 and its auto completion.

Step 5 - Installing Uptime Kuma

Enter the following command to install Uptime Kuma:

1. Enter git clone https://github.com/louislam/uptime-kuma.git to clone the repository.
2. Change directory by executing cd uptime-kuma.
3. Enter npm run setup to install all dependencies.
4. Now start Kuma by entering npm run start-server.

Once you see "Listening on 3001" in the terminal, go to your IP on Port 3001 (e.g. 123.123.123.123:3001) in your browser. If you see the Uptime Kuma setup screen, you have successfully installed Uptime Kuma. Please stop the server by pressing Ctrl + C in the terminal once. You have to wait a little while until the server stops.

Step 6 - Reverse Proxy with nginx

1. Enter sudo -s to get root privileges.
2. If asked for your password, enter it and press Enter.
3. Enter nano /etc/nginx/sites-available/uptimekuma to create a new nginx config file.
4. Paste the following code into the file:

server  {
    listen 80;
    listen [::]:80;
    server_name    sub.domain.com;
    location / {
        proxy_pass         http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

5. Replace sub.domain.com with your subdomain (e.g. status.example.com).
6. Exit the file by pressing Ctrl + X and then Y and then Enter.
7. Enter ln -s /etc/nginx/sites-available/uptimekuma /etc/nginx/sites-enabled/uptimekuma to enable the config file.
8. Enter nginx -t to test the config file.
9. If you see test is successful, you can reload nginx by entering systemctl reload nginx.

Step 7 - Setting up Uptime Kuma to start on boot

We want to start Uptime Kuma automatically when the server starts.
This is useful when the server reboots, as we cannot monitor the server running Kuma. When it is restarted, Kuma will also be restarted.

1. Enter nano /etc/systemd/system/uptimekuma.service to create a new systemd service file.
2. Paste the following code into the file:

[Unit]
Description=Uptime-Kuma - A free and open source uptime monitoring solution
Documentation=https://github.com/louislam/uptime-kuma
After=network.target

[Service]
Type=simple
User=uptimekuma
WorkingDirectory=/home/uptimekuma/uptime-kuma
ExecStart=/home/uptimekuma/.nvm/versions/node/v18.18.2/bin/node /home/uptimekuma/uptime-kuma/server/server.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

3. Exit the file by pressing Ctrl + X and then Y and then Enter.
4. Enter systemctl daemon-reload to reload the systemd daemon.
5. Enter systemctl enable uptime-kuma to enable the service.
6. Enter systemctl start uptime-kuma to start the service.

Step 8 - Setting up HTTPS

1. Enter snap install --classic certbot to install CertBot.
2. Enter certbot --nginx to start the CertBot setup.
3. I recommend using these settings:
   1. Enter your email address.
   2. Yes (Terms of Service)
   3. No (Advertisement)
   4. Press Enter to select the only option (your domain).
   5. This process can take a while, so please be patient.

Step 9 - Setting up the Firewall

We need a firewall to protect our server from unwanted connections.

We will use ufw (Uncomplicated Firewall) to set up the firewall, because it is easy to use and configure and is also pre-installed on Ubuntu.

1. Enter ufw allow ssh && ufw allow http && ufw allow https && ufw enable to setup the firewall and then enable it.
2. Press Y and then Enter to confirm.

Step 10 - Setting up Uptime Kuma

1. Open your browser and go to your subdomain (e.g. https://status.example.com).
2. You should see the Uptime Kuma setup screen.
3. Enter your username and password, also choose the right language. The username is case sensitive!
4. Click on "Create".
5. In the top right corner, click on the dropdown menu and select "Settings".
6. In the "General" tab under "Primary Base URL", click on "Auto Get" so that the URL is automatically set.

If this works, you should now restart the server and check if everything starts automatically as it should. To do this, execute shutdown -r now. After executing the command, you can close the SSH connection.

Conclusion

Now you have successfully installed Uptime Kuma and set it up to start on boot.

From now on your Kuma instance will be available under your subdomain (e.g. https://status.example.com).

If you want to update Uptime-Kuma, you can follow the tutorial Update Your Uptime Kuma Instance folgen.
Wenn du Alerts einrichten möchtest, kannst du dem Tutorial Setup of Uptime Kuma Real-Time Alerts folgen.

Thank you for using this tutorial!

Licence

Copyright (c) 2023 Konstantin Protzen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributor's Certificate of Origin

By making a contribution to this project, I certify that:

1. The contribution was created in whole or in part by me and I have the right to submit it under the licence indicated in the file; or

2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate licence and I have the right under that licence to submit that work with modifications, whether created in whole or in part by me, under the same license (unless I am permitted to submit under a different licence), as indicated in the file; or

3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the licence(s) involved.