Uptime Kuma is a self-hosted monitoring tool that is easy to use and offers a range of features including monitoring uptime for various services, notifications, multi-language support, multiple status pages, and more. This tutorial will guide you through the process of installing Uptime Kuma on Ubuntu 22.04 using Docker.
Prerequisites
Before you start with the installation process, make sure you have root or sudo access to your Ubuntu server.
Also, it’s a good idea to check out the Github repository for any project updates.
Step 1: Update the System and Install Required Software
First, update the system and install necessary software like git and Nginx. Reboot the server once done.
sudo apt update
sudo apt upgrade
sudo apt install -y nginx git curl certbot python3-certbot-nginxStep 2: Install Docker
Before installing Docker Engine for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker from the repository.
Set Up The Repository
Update the apt package index and install packages to allow apt to use a repository over HTTPS:
sudo apt update
sudo apt install -y ca-certificates gnupgAdd Docker’s official GPG key:
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpgUse the following command to set up the repository:
echo \
"deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullInstall Docker Engine
Follow the steps outlined in Docker’s official documentation.
Update the apt package index:
sudo apt updateTo install the latest version, run:
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginStep 3: Create Docker Volume Directory
Create a directory to store your Docker volume:
mkdir /docker-volume
mkdir /docker-volume/uptime-kuma
mkdir /opt/uptime-kumaNavigate to the uptime-kuma directory and create a docker-compose file:
cd /opt/uptime-kumaCreate a docker-compose.yml file with the following details.
This configuration will use port 3001 for access and will restart the service automatically in case of server shutdown or crash. The volume will be added to the directory created earlier (/docker-volume/uptime-kuma).
An example docker-compose.yml is also available here.
---
# Simple docker-compose.yml
# You can change your port or volume location
version: '3.3'
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
volumes:
- ./uptime-kuma-data:/app/data
ports:
- 3001:3001 # <Host Port>:<Container Port>
restart: alwaysRun Docker compose to create the container:
docker-compose up -dStep 4: Configure Nginx
Allow public traffic to ports 80 and 443 (HTTP and HTTPS) using the “Nginx Full” UFW application profile:
sudo ufw allow 80
sudo ufw allow 443Add the uptime_kuma configuration into the Nginx proxy by replacing example.com with your domain in the /etc/nginx/sites-available/example.com.conf file:
sudo vi /etc/nginx/sites-available/example.com.confAdd the following configuration to the file:
server {
listen 80;
server_name example.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;
}
}Create a symbolic link to sites-enabled and activate the site. Then, check that the configuration is correct and reload Nginx to apply the settings:
sudo ln -s /etc/nginx/sites-available/example.com.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginxStep 5: Install Certbot
CertBot will help us generate a certificate for our domain and automatically make Nginx use the certificate and port 443.
sudo apt install -y certbot python3-certbot-nginxGenerate a Let’s Encrypt certificate and alter the Nginx configuration in the file uptime-kuma.conf:
sudo certbot --nginx -d example.comStep 6: Exposing Status Page Only
If you would like to make your page public but don’t want users to access your admin dashboard, you may use the following configuration, replacing public-status.example.com and page-name with your domain and page name respectively:
server {
server_name public-status.example.com;
location = /status/page-name {
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;
}
location /api {
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;
}
location /assets {
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;
}
location ~* \.(svg|ico)$ {
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;
}
location / {
return 301 https://$host/status/page-name;
}
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/public-status.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/public-status.example.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
server {
if ($host = public-status.example.com) {
return 301 https://$host$request_uri;
}
listen 80;
server_name public-status.example.com;
return 404;
}At this point, you should have a fully HTTPS-enabled Uptime Kuma instance running on your server.
How to Upgrade to the Latest Release
The first step in the upgrade process is to pull the latest Docker image of Uptime Kuma. You can do this by using the docker pull command:
docker pull louislam/uptime-kumaBefore you can use the new image, you need to stop and remove the current Uptime Kuma container.
You can do this using the docker stop and docker rm commands:
docker stop uptime-kuma
docker rm uptime-kumaNow that the old container has been removed, you can start a new container using the latest image.
Navigate to the directory where your docker-compose.yml file is located and run the docker-compose up -d command:
cd /opt/uptime-kuma
docker-compose up -dThis command starts a new Uptime Kuma container using the latest image and the settings defined in your docker-compose.yml file.
Your Uptime Kuma instance should now be updated to the latest version. Remember to check for updates regularly to ensure that your installation stays current and secure.
