Uptime Kuma: Easily Install Your Open-Source Monitoring Tool with Docker
Set up Uptime Kuma, an open-source monitor, using Docker and Docker Compose on your VPS. Keep an eye on your websites, servers, and other services. This guide shows you how.

Table of Contents
- What is Uptime Kuma?
- Prerequisites
- Installation with Docker Compose
- Initial Setup of Uptime Kuma
- Exploring and Configuring Uptime Kuma
- Extension: External MariaDB Database (Optional)
- Extension: Reverse Proxy with Caddy (Optional)
- Extension: Monitoring Docker Containers (Optional)
- Don’t Forget Backups!
- Conclusion
What is Uptime Kuma?
Uptime Kuma is a self-hosted tool to watch your websites, servers, and almost any online service. It has a clean design and lots of ways to send you alerts, so you’ll know quickly if something stops working. It has a modern, snappy interface and can monitor many things:
- HTTP(s) / TCP / HTTP(s) Keyword / HTTP(s) Json Query
- Ping / DNS Record / Push
- Steam Game Server / Docker Container
- Notifications via 90+ services (Telegram, Discord, Email, etc.)
- Short monitoring intervals (down to 20 seconds)
- Multilingual support
- Creation of multiple status pages, also assignable to custom domains
- Certificate information and ping charts
- Proxy and 2FA support
Best of all, it’s open source, so you control your data.
Prerequisites
- A VPS, maybe running Ubuntu 24.04 or another Linux.
- You’ll need Docker and Docker Compose on your server.
- Basic knowledge of command-line operations.
- (Optional) A domain, if you want to use your own address for Uptime Kuma with a reverse proxy later.
Installation with Docker Compose
We’ll use Docker Compose to install Uptime Kuma. It’s flexible, which is great if you want to add a separate database or a reverse proxy later on.
-
Connect to the Server and Create a Directory Connect to your VPS via SSH. Then create a directory for Uptime Kuma, change into it, and create a subdirectory for the data:
mkdir uptime-kuma cd uptime-kuma mkdir data
-
Create Docker Compose File Make a
compose.yaml
file with a text editor likenano
):nano compose.yaml
Put this in the file. This simple setup uses an SQLite database that’s built into Uptime Kuma. It works well for most people.
services: uptime-kuma: image: louislam/uptime-kuma:1 # Recommended stable version container_name: uptime-kuma volumes: - ./data:/app/data ports: - "3001:3001" # <Host-Port>:<Container-Port> restart: always
image: louislam/uptime-kuma:1
: This is the official stable image from Docker Hub. You can also try beta versions (likeghcr.io/louislam/uptime-kuma:beta
) if you like to experiment.container_name: uptime-kuma
: A name you pick for the container.volumes: ./data:/app/data
: This is key. It tells Docker to save Uptime Kuma’s data (settings, checks, etc.) in thedata
folder on your server. So, your data stays safe if you restart or update the container.ports: "3001:3001"
: Uptime Kuma uses port 3001 in the container. We link this to port 3001 on your VPS. If port 3001 is taken, you can use a different host port (like"3002:3001"
).restart: always
: This makes sure the container starts up again if your server reboots or the container stops.
Save the file (in
nano
, useCtrl+O
, Enter, thenCtrl+X
). -
Start Uptime Kuma Since we are in the directory containing the
compose.yaml
file, we can simply start the containers:sudo docker compose up -d
Docker will now download the Uptime Kuma image (this may take a moment the first time) and start the container in the background (
-d
for detached mode).You can check the status of the containers:
sudo docker compose ps
And view the logs:
sudo docker compose logs uptime-kuma
To see resource consumption:
sudo docker compose stats
Initial Setup of Uptime Kuma
Now, open your web browser and enter your server’s IP address followed by port 3001: http://YOUR_SERVER_IP:3001
.
You will be greeted by the setup wizard:
- Select Language: Choose your preferred language.
- Create User Account: Set up an administrator username and a secure password.
- Database Type (optional for this guide): With the
compose.yaml
above, SQLite is used by default, which is integrated into Uptime Kuma and requires no further configuration. In the beta version, you can choose an integrated MySQL database or connect to an additional MariaDB/MySQL database.
Click “Create” and you will land on the Uptime Kuma dashboard.
Exploring and Configuring Uptime Kuma
Dashboard
The dashboard is your central hub. Here you can see all your monitors and their current status.
Settings
Click on your profile picture in the top right corner and then on “Settings”. Here are some important points:
- General:
- Time Zone: Set your local time zone.
- Primary Base URL: Important if you use a reverse proxy later.
- Search Engine Visibility: Prevent your Uptime Kuma instance from being indexed by Google.
- Appearance: Choose between light, dark, or automatic themes.
- Notifications: The core feature! Set up your notification channels here.
- Click “Setup Notification”.
- Choose the type (e.g., Email (SMTP), Telegram, Discord).
- Enter the required data. For SMTP, you’ll need your mail server details or a service like Maileroo Affiliate Link.
- You can send test notifications.
- About:
- Here you can check for updates. If you are using the beta version, check the “Check Beta Release” box.
Adding a Monitor
Go back to the dashboard and click ”+ Add New Monitor”.
- Monitor Type: Choose the appropriate type. For a website, “HTTP(s)” is common.
- Friendly Name: A descriptive name, e.g., “My Website”.
- URL: The full URL, e.g.,
https://deployn.de
. - Heartbeat Interval: How often to check (e.g., every 60 seconds).
- Retries on Failure: How many times a failure must occur before the service is marked as “Down”.
- Notifications: Select your previously configured notification channels for this monitor.
- Advanced Settings: You can, for example, set expected HTTP status codes or search for keywords in the page content.
Click “Save”. Your monitor will now appear on the dashboard and be checked regularly.
Creating a Status Page
With Uptime Kuma, you can create public or private status pages to display the status of your services.
- Click “Status Pages” in the menu.
- Click ”+ New Status Page”.
- Name: e.g., “Deployn Status”.
- Slug: A URL-friendly name, e.g.,
deployn-status
. - Click “Next”.
- In the next step (“Add Monitors”), select the monitors to be displayed on this status page.
- Click “Save”.
You will get a link to your status page (e.g., http://YOUR_SERVER_IP:3001/status/deployn-status
). You can share this to provide users with transparency about your system availability.
Extension: External MariaDB Database (Optional)
If you prefer a more robust database solution or already use MariaDB, you can connect Uptime Kuma to a separate MariaDB instance.
-
Adjust Docker Compose: First, stop your running Uptime Kuma containers and create a new folder for the MariaDB data:
sudo docker compose down mkdir mariadb-data
Open your
compose.yaml
and extend it:services: uptime-kuma: image: ghcr.io/louislam/uptime-kuma:beta container_name: uptime-kuma volumes: - ./data:/app/data ports: - 3001:3001 restart: always networks: - internal # For internal communication depends_on: - uptime-kuma-db uptime-kuma-db: image: mariadb:11 container_name: uptime-kuma-db restart: always networks: - internal volumes: - ./mariadb-data:/var/lib/mysql # Important for DB data persistence! environment: - MARIADB_ROOT_PASSWORD=uptimekumapassword # Root password for the DB - MARIADB_DATABASE=uptimekuma - MARIADB_USER=uptimekuma - MARIADB_PASSWORD=password # Ensure this matches UPTIME_KUMA_DB_PASSWORD if used networks: internal: external: false
Important Changes:
- We’ve added a new service
uptime-kuma-db
for MariaDB. - Adjust passwords and names!
- The volume
./mariadb-data:/var/lib/mysql
is mapped foruptime-kuma-db
to persistently store database data. - An
internal
network has been defined for communication between containers. - The volume for
uptime-kuma
should be- ./data:/app/data
as per your initial setup for SQLite. If you switch to MariaDB with a fresh Uptime Kuma setup, it will use MariaDB. If migrating, you’d need to handle that separately.
- We’ve added a new service
-
Restart Containers:
sudo docker compose up -d
If you start Uptime Kuma for the first time with this configuration and the
./data
directory is empty (or you are re-initializing), you will go through the setup process again. Then select “External MariaDB/MySQL” and enter the details: Hostuptime-kuma-db
, Port3306
, User, Password, and Database Name as specified in yourcompose.yaml
.
Extension: Reverse Proxy with Caddy (Optional)
To access Uptime Kuma via your own domain (e.g., status.your-domain.com
) with HTTPS, a reverse proxy is ideal. Here’s an example with Caddy.
-
Prerequisite: Caddy is already installed and running on your server (e.g., also as a Docker container). You have a Docker network (here called
proxy
) that Caddy and Uptime Kuma can share.# If not already present, create an external Docker network sudo docker network create proxy
-
Adjust Caddyfile: Add an entry for Uptime Kuma to your Caddyfile (or the corresponding configuration file):
status.your-domain.com { reverse_proxy uptime-kuma:3001 }
status.your-domain.com
: Replace this with your desired domain/subdomain. Ensure the DNS record for it points to your server’s IP.uptime-kuma:3001
: Caddy forwards requests to theuptime-kuma
container on port3001
.
-
Adjust Uptime Kuma Docker Compose: Open the
compose.yaml
for Uptime Kuma again:- Ensure the
ports
section for theuptime-kuma
service is commented out or removed, as Caddy will handle access. - Add the
uptime-kuma
service to theproxy
network and declare it as external:
services: uptime-kuma: # ... (other settings) ... # ports: # Comment out or remove # - "3001:3001" networks: - internal - proxy # Add this # ... (Rest of the settings) ... networks: internal: # If using MariaDB setup external: false proxy: # Add this external: true
Note: If you are not using the external MariaDB setup, Uptime Kuma might just be on the
default
network created by Docker Compose, or you might want to explicitly define its primary network ifinternal
isn’t used. - Ensure the
-
Restart Containers and Reload Caddy:
sudo docker compose up -d # Restarts Uptime Kuma with network changes sudo docker reload caddy # Or the command to reload your Caddy configuration
You should now be able to access Uptime Kuma at
https://status.your-domain.com
. In Uptime Kuma settings under “Primary Base URL,” you can enter this new address.
Extension: Monitoring Docker Containers (Optional)
Uptime Kuma can also monitor the status of other Docker containers on the same host.
-
Bind Docker Socket into Uptime Kuma: Adjust the
compose.yaml
for theuptime-kuma
service to bind the Docker socket read-only:# ... (services -> uptime-kuma) ... volumes: - ./data:/app/data - /var/run/docker.sock:/var/run/docker.sock:ro # Add this # ... (Rest of the settings) ...
Caution: Binding the Docker socket gives the container potentially extensive control over Docker. Use this wisely and understand the security implications.
:ro
(read-only) is an important first step here. -
Restart Containers:
sudo docker compose up -d
-
Add Docker Host in Uptime Kuma:
- Go to Uptime Kuma Settings -> Docker Host.
- Click ”+ Add Docker Host”.
- Friendly Name: e.g., “Local Docker Host”.
- Connection Type: Select “Socket (/var/run/docker.sock)“.
- The path
/var/run/docker.sock
should already be correct. - Click “Save”.
-
Create Docker Container Monitor:
- Go to the Dashboard and click ”+ Add New Monitor”.
- Monitor Type: “Docker Container”.
- Docker Host: Select the previously created “Local Docker Host”.
- Container Name: Enter the exact name of the container you want to monitor (e.g.,
caddy
oruptime-kuma-db
). - Click “Save”.
Uptime Kuma will now display the status (Up/Down) of the specified container.
Don’t Forget Backups!
A monitoring tool is only as good as its availability and the security of its data. Remember to create regular backups of your persistent data:
- The
./data
folder (contains configuration and SQLite DB, if used). - The
./mariadb-data
folder (if you use an external MariaDB as described above).
Tools like Duplicati (which you can also run as a Docker container) can help you back up these folders regularly, e.g., to an external drive or the cloud.
Conclusion
Uptime Kuma is really quick to set up with Docker and Docker Compose and offers a great, modern way to keep an eye on your services. The flexibility of Docker Compose also allows you to adapt the setup to your own needs, whether through an external database or integration with a reverse proxy.
I hope this tutorial helped you!