Uptime Kuma Setup with Docker

Uptime Kuma is an easy-to-use and easy-to-setup uptime monitoring tool for online services, websites, and more. If you’re seeking a seamless and efficient way to deploy Uptime Kuma, look no further. In this guide, we will show you how to setup and run Uptime Kuma with docker.

Some of the highlighted features of Uptime Kuma are:

• Monitoring uptime for HTTP(s) / TCP / HTTP(s) Keyword / HTTP(s) Json Query / Ping / DNS Record / Push / Steam Game Server / Docker Containers
• Fancy, Reactive, Fast UI/UX
• Notifications via Telegram, Discord, Gotify, Slack, Pushover, Email (SMTP), and more
• 20 second intervals
• Multiple status pages
• Map status pages to specific domains

Let’s dive in and get your Uptime Kuma instance up and running!

Installation with docker

If you have a fresh server, this how-to guide will walk you through the installation and system update using Ubuntu 22.04 LTS.

apt update && apt upgrade

Next, you can install docker in one of two ways: either from the local repository or by adding the docker repository. For this guide, we’ll use the bash script provided by the docker website for installation. The command below will take care of all the necessary actions, including adding the repository and installing docker.

curl -fsSL get.docker.com | sudo sh

After completing the previous steps, run the following command to install the Uptime Kuma docker container and execute it in the background using the -d flag.

-d = run in the background

-p = port

-v = volume path (Use a local path on the server, such as /opt/kuma_data or /var/kuma_data, and create the kuma_data directory beforehand).

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

After successful installation, Uptime Kuma will be available at localhost:3001.

Up to this point, we have completed the setup. However, we also want it to be available on port 80 or 443 (SSL). To achieve this, we will use a reverse proxy (in this case, Apache).

Apache reverse proxy

Install Apache and enable the necessary modules.

apt install apache2

a2enmod ssl rewrite headers proxy proxy_http deflate cache proxy_wstunnel

systemctl enable apache2
systemctl start apache2

Create a Kuma configuration file for Apache.

cd /etc/apache2/sites-available/
touch kuma.conf

Port 80

This is for those who do not plan to use SSL. If you want to use SSL, you can skip this section. I highly recommend getting and using SSL for enhanced security.

vim kuma.conf

Add the following configuration settings into the kuma file.

<VirtualHost *:80>
	ServerName DOMAIN.COM

	ProxyPass / http://localhost:3001/
	RewriteEngine on
	RewriteCond %{HTTP:Upgrade} websocket [NC]
	RewriteCond %{HTTP:Connection} upgrade [NC]
	RewriteRule ^/?(.*) "ws://localhost:3001/$1" [P,L]
</VirtualHost>

apachectl -t
systemctl restart apache2

Port 443 (SSL)

If you have an SSL certificate from a vendor of your choice, you can use that certificate. Otherwise, you can obtain a free SSL certificate from Let’s Encrypt.

The crucial step is to include a basic port 80 configuration for this. If you’ve already added the above configuration, replace it with the following.

<VirtualHost *:80>
	ServerName DOMAIN.COM
	DocumentRoot /var/www/html

	<Directory "/var/www/html">
		AllowOverride All
		Options -Indexes +FollowSymLinks
	</Directory>

	ErrorLog /var/log/apache2/kuma_error.log
</VirtualHost>

apachectl -t
systemctl restart apache2

To get an SSL, first, install the Certbot snap package.

snap install certbot --classic

Next, obtain a certificate for the domain you wish to use and provide your email when prompted.

certbot certonly --webroot -w /var/www/html -d DOMAIN.COM

Now, you can add the port 443 block to the configuration file.

vim kuma.conf

<VirtualHost *:443>
  	ServerName DOMAIN.COM

	SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-GCM-SHA256:AES256+EDH:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4
	SSLProtocol All -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
	SSLHonorCipherOrder On
	Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
	Header always set X-Frame-Options DENY
	Header always set X-Content-Type-Options nosniff

	Protocols h2 http/1.1

	ErrorLog /var/log/apache2/kuma_error.log

	SSLEngine on
	SSLCertificateKeyFile /etc/letsencrypt/live/DOMAIN.COM/privkey.pem
	SSLCertificateFile /etc/letsencrypt/live/DOMAIN.COM/fullchain.pem

	ProxyPass / http://localhost:3001/
	RewriteEngine on
	RewriteCond %{HTTP:Upgrade} =websocket
	RewriteRule /(.*) ws://localhost:3001/$1 [P,L]
	RewriteCond %{HTTP:Upgrade} !=websocket
	RewriteRule /(.*) http://localhost:3001/$1 [P,L]
</VirtualHost>

Test the configuration file and restart Apache.

apachectl -t
systemctl restart apache2

How to update it?

Updating is as easy as getting a new container.

docker pull louislam/uptime-kuma:1
docker stop uptime-kuma
docker rm uptime-kuma

Now run and start the latest container.

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