Monitor Everything in Minutes: Install Uptime Kuma with Docker

· 9 min read · updated August 2, 2026

Have your servers or websites ever gone down without you noticing? Worried about losing customers because you can’t react to a failure fast enough?

We have the perfect solution for you. Uptime Kuma is an open-source monitoring tool that keeps you one step ahead. From a modern interface you can track the status of your services and get alerts before a problem escalates. Best of all: installing it with Docker takes less time than making a cup of coffee.

If you don’t have Docker installed, no problem: take a look at our complete guide to installing Docker and Docker Compose. Once that’s done, you’re one command away from monitoring your systems.

Why Should You Choose Uptime Kuma?

The word Why? handwritten next to the Uptime Kuma logo, opening the section on why to choose it

Before we dive into the technical details, here are a few reasons why Uptime Kuma belongs in your toolkit:

Ready to install it? Let’s get to it.

Prerequisites

Before you start, make sure you have the following:

  1. Docker: If you haven’t set it up yet, check our earlier article on how to install Docker.
  2. Linux: A distribution such as Ubuntu 20.04/22.04 or Debian 10/11.
  3. sudo privileges: You’ll need superuser access to install packages and configure Docker.
  4. Internet connection: To download the packages you need.

Steps to Install Uptime Kuma with Docker

Uptime Kuma logo surrounded by radial strokes with the word Installing, introducing the installation steps

Step 1: Update Your System

Before installing anything, make sure everything on your system is up to date:

sudo apt update && sudo apt upgrade -y

This keeps you clear of compatibility problems between packages.

Step 2: Install curl (if you don’t have it yet)

curl is required to download the Docker installation script. If you don’t have it, install it with this command:

sudo apt install curl -y

Step 3: Install Docker (if you don’t have it)

If Docker isn’t installed yet, you can set it up quickly with this command:

curl -sSL https://get.docker.com/ | sh

When the installation finishes, check that everything works by running:

docker --version

If you get a version number back, you’re ready to continue.

Step 4: Install Uptime Kuma with Docker

Here comes the exciting part: deploying Uptime Kuma as a Docker container. Run this command:

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

What Does This Command Do?

You should see something like this:

Terminal pulling the louislam/uptime-kuma image with Docker until every layer completes

Step 5: Access Uptime Kuma

Open your browser and go to the Uptime Kuma interface at:

http://<server-ip-address>:3001

If you’re running it locally, just use:

http://localhost:3001

If you don’t know your IP address, run:

ip a

In our case it is:

ip output with the server address 192.168.101.144/24 outlined in red

From here you can set up your admin account, add monitors and start tracking your services.

Uptime Kuma initial screen for creating the administrator account with language, username and password

Create your admin user, set a strong password and pick your language

Freshly installed Uptime Kuma dashboard, with all stats at zero and a notice that there are no monitors yet

You can now add monitors and start tracking your services.

Where to Go From Here

With Uptime Kuma up and running, here are a few suggestions to get the most out of it:

  1. Add monitors: Track websites, API services, TCP ports, ping and more.
  2. Configure notifications: Connect Uptime Kuma to messaging services like Telegram, Slack or your email.
  3. Explore metrics: Review the historical logs and the uptime of your services.
  4. Update Uptime Kuma: Keep up with new releases by simply removing and recreating the container:
docker pull louislam/uptime-kuma:1
docker stop uptime-kuma
docker rm uptime-kuma  
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1

Conclusion: Your Monitoring in Minutes

Closing illustration with the word Conclusions, a lit lightbulb, check marks and charts

With just a handful of commands you now have Uptime Kuma installed and ready to use. No more worrying about downtime in your services. The tool is easy to install, efficient and highly customizable.

Questions or suggestions? Drop them in the comments and I’ll be glad to help.

Technical Detail:

Share this guide with your colleagues and friends. Together we can improve the way we monitor our services! 🚀

Remote access to Uptime Kuma

By default, Uptime Kuma is only reachable from your local network. To check on it from anywhere you have two options:

Keep the database from growing forever

Uptime Kuma stores every check it runs. At a 60 second interval with ten monitors that is 14,400 rows a day, and by default it deletes none of them. This causes no trouble in the first week: it causes trouble in month six, when the disk fills up and you have no idea why. Worth settling now that you have just installed it.

The Easy Method (Native Feature in Uptime Kuma)

Note: Recent versions of Uptime Kuma include native options for controlling data retention straight from the panel. You can now set how many days of historical data to keep and run a Shrink database to compact it.

Steps for the native method:

  1. Log in to Uptime Kuma and click the account icon in the top right
  2. Click Settings
  3. Click Monitor History.
  4. Set the retention in days to whatever suits you. For example, 30 days.
  5. If you want, click Shrink database to run VACUUM on SQLite. That compacts the database, clearing out the empty fragments.
Uptime Kuma Monitor History settings with retention at 30 days and the button to shrink the database

That way you keep database growth under control without resorting to scripts or cron jobs.

Note: If your database was created after Uptime Kuma 1.10.0, AUTO_VACUUM is already enabled and you may not need the manual method at all. Knowing it, though, gives you a better feel for what happens under the hood and can come in handy in advanced scenarios.

The Granular, Detailed Method (Manual)

If for whatever reason you want finer control, or you’re on an older version of Uptime Kuma without the native options, you can fall back on the manual method below to manage data retention. It also helps if you need more flexibility in your settings, specific retention periods or extra actions.

1. Install SQLite

SQLite is the database engine Uptime Kuma uses. To interact with its database, install it by running:

sudo apt install sqlite3 -y

That gives you the commands you need to clean up and compact the database.

2. Create a Cleanup Script

Go to the directory where the Uptime Kuma database is stored:

cd /var/lib/docker/volumes/uptime-kuma/_data/

Create a file called clean.sh with the following contents:

nano clean.sh

Script Contents:

#!/bin/bash

DB_PATH="/var/lib/docker/volumes/uptime-kuma/_data/kuma.db"

sqlite3 "$DB_PATH" <<EOF
DELETE FROM heartbeat WHERE time < datetime('now', '-1 year');
VACUUM;
.exit
EOF

Save the file and exit the editor (Ctrl+O, Enter, Ctrl+X).

What Does This Script Do?

  1. DB_PATH: Defines the path to the kuma.db database.
  2. Delete old records: Uses the DELETE FROM heartbeat command to remove every row in the heartbeat table older than one year (datetime('now', '-1 year')).
  3. Compact the database: Runs VACUUM, which shrinks the physical file size by clearing out the empty fragments the delete left behind.

How Do You Change the Time Window?

Tune this value to match your own data retention needs.

3. Make the Script Executable

So the script can actually run, change its permissions:

chmod +x clean.sh

4. Schedule Automatic Cleanups with Cron

Set up a cron job so the script runs automatically. Edit the crontab:

crontab -e

Cron Job Configuration

Add the following line at the end of the file to run it every day at 2:00 a.m.:

0 2 * * * /var/lib/docker/volumes/uptime-kuma/_data/clean.sh >> /var/lib/docker/volumes/uptime-kuma/_data/clean.log 2>&1

What Does This Cron Job Do?

How Do You Check the Logs?

You can review the script’s run history with:

cat /var/lib/docker/volumes/uptime-kuma/_data/clean.log

How Do You Change the Frequency?

Save and close the file (Ctrl+O, Enter, Ctrl+X).

Extra Options to Improve Maintenance

Use Nginx Proxy Manager to Reach Uptime Kuma

If you’d rather not expose Uptime Kuma’s internal port directly, or open a specific port for every service, adding Nginx Proxy Manager may be the answer. This reverse proxy lets you funnel traffic through the standard ports (80 and 443) you already have open, which adds a layer of security and simplicity. On top of that, you can set up SSL certificates easily, centralize access to several applications and keep a tidier environment.

To learn how to install it, take a look at our post on how to install Nginx Proxy Manager on Docker.

Run Uptime Kuma in a Virtualized Environment

If you’d rather deploy Uptime Kuma in a virtual machine or an LXC container, Proxmox VE is an excellent option. It lets you create and manage isolated environments efficiently. To learn how to install it, see our guide How to Install Proxmox VE from Scratch: A Step-by-Step Guide, and if you want to dig into the fundamentals of virtualization, check out Proxmox from Scratch: The Complete Guide to Getting Started with Virtualization on Proxmox VE.

Next steps

Over time the Uptime Kuma database can grow quite a bit. Learn how to control data retention and optimize performance in our dedicated guide.

Share this post

Tagged ,

Leave a Reply

Your email address will not be published. Required fields are marked *