How to Install Uptime Kuma on Docker: Self-Hosted Uptime Monitoring

An online store website that suddenly goes down at 2 AM is often only discovered after the first user complains the following afternoon because of a failed checkout. Reputation damage and financial losses have already occurred long before anyone realizes there is a server issue.

Cases like this can be prevented using an automated 24/7 uptime monitoring system. One of the most popular free and open-source monitoring tools today is Uptime Kuma. In this article, we will install Uptime Kuma on Docker step by step, starting from basic installation, initial monitor configuration, setting up notifications, to securing it with a reverse proxy and SSL.

1. Why Uptime Monitoring Is Important

Sysadmins managing production servers carry a huge responsibility: ensuring services remain accessible to visitors and users whenever needed. The problem is that servers and applications do not always notify you when they run into issues. Services can crash, SSL certificates can expire, or database connections can break without sending any alerts to the team.

Without a monitoring tool, sysadmins usually only find out about an issue after users or clients file a complaint via email. At this point, downtime has already lasted for an unknown duration, and both reputational and financial harm have occurred. An uptime monitoring system closes this gap by periodically checking service health and sending immediate alerts upon detecting an anomaly.

2. What Is Uptime Kuma

Uptime Kuma is a self-hosted open-source monitoring tool developed by Louis Lam. Unlike paid monitoring services such as UptimeRobot or Pingdom where data is stored on third-party servers, Uptime Kuma is deployed directly on your own server, keeping monitoring data entirely under the sysadmin's control.

Key features that make Uptime Kuma widely adopted include:

Multi-type monitoring: supports checking HTTP(s), TCP Ports, Ping, DNS Records, and Docker container status.
Multi-channel notifications: integrates with dozens of notification providers like Telegram, Discord, and email via SMTP.
Public status pages: customizable status pages that can be shared with clients or users so they can check service status independently.
Multi-user and multi-language support: suitable for multi-admin teams and includes support for various languages.

Why choose Docker for installation? Because Uptime Kuma runs inside an isolated container separated from the main operating system. Sysadmins do not need to manually install Node.js or other dependencies on the server, making updates and backups significantly simpler than manual installations.

3. Prerequisites Before Installation

Before proceeding with the installation, make sure the following requirements are met.

Supported Operating Systems: Linux (Debian, Ubuntu, Fedora, ArchLinux) or Windows (10 x64 or later, Server 2012 R2 or later). Official resource requirements are not published, but 1 vCPU and 1 GB RAM are generally sufficient for dozens of lightweight monitors.
Docker and Docker Compose Installed. Verify using:
```
docker -v
docker compose version
```
If not installed, run the official Docker installation script (suitable for fresh VPS setups; for production servers, installing via distribution package managers like apt or dnf is recommended):
```
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
Then add your user to the docker group to avoid requiring sudo for Docker commands:
```
sudo usermod -aG docker $USER
newgrp docker
```
SSH Access to the VPS with a user belonging to the docker group.
Filesystem Supporting POSIX File Locking for data storage. Uptime Kuma uses SQLite which relies on this locking mechanism to prevent database corruption. Use a local directory or a standard Docker volume, not NFS.

4. How to Install Uptime Kuma with Docker

There are two common deployment methods: docker run for quick testing, and Docker Compose for cleaner long-term production management.

4.1 Quick Installation via Docker Run

This method is ideal for quickly testing Uptime Kuma. Execute the following command in your VPS terminal:

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

Parameter breakdown:

-d: runs the container in detached mode (background).
--restart=always: automatically restarts the container if Docker or the server reboots.
-p 3001:3001: maps host port 3001 to container port 3001, which is the default Uptime Kuma dashboard port.
-v uptime-kuma:/app/data: persists all application data (monitors, users, history) inside a Docker volume named uptime-kuma mapped to /app/data in the container.
--name uptime-kuma: assigns a container name for easier management via CLI.
louislam/uptime-kuma:2: the official Uptime Kuma image tagged with major version 2.

Avoid using the latest tag as it is deprecated and points to legacy version 1. Always use specific tags: 2 (full version including embedded MariaDB and Chromium for the Browser Engine feature) or 2-slim (lightweight version without those two components).

The command above uses --restart=always based on the official README example. The difference between always and unless-stopped (used in compose.yaml under section 4.2) is that always will restart the container even if manually stopped via docker stop, whereas unless-stopped respects manual stops and only restarts automatically on container crashes or daemon restarts, making it a safer option for daily operations.

If the dashboard only needs to be accessed locally from the server (e.g., when routed behind a reverse proxy), bind the port to localhost to prevent direct public exposure:

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

4.2 Installation via Docker Compose (Recommended)

For production deployments, Docker Compose is recommended because configurations are kept in a single file that can easily be version-controlled and replicated across servers.

Create a project directory and navigate into it:
```
mkdir uptime-kuma && cd uptime-kuma
```

Create a compose.yaml file (official configuration structure; data is saved locally to ./data):

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

Or download it directly:

curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml

Start Uptime Kuma:
```
docker compose up -d
```
Check status:
```
docker compose ps
```
If the STATUS column shows Up, Uptime Kuma is ready to be accessed via browser.

5. Accessing the Uptime Kuma Dashboard

Open your web browser and navigate to http://VPS-IP:3001 (replace with your server IP). Ensure port 3001 is allowed through your firewall/security group. For long-term usage, it should not remain exposed directly to the public; route it through a reverse proxy as shown in section 9.
Select Database. Before creating an admin account, Uptime Kuma v2 presents a database setup page: SQLite or MariaDB (embedded in image 2 or external). Select SQLite for this guide as it is straightforward and aligns with the data volume setup in section 4. If choosing an external MariaDB instance, specify the Hostname, Port (default 3306), Username, Password, and Database Name. These settings are stored in db-config.json; deleting this file will reset the setup wizard.
Create Admin Account: enter a secure username and password, as this account gains full administrative access over all monitor configurations.
Secure Credentials. Uptime Kuma does not provide password resets via email or dashboard interface; if lost, credentials must be reset via CLI inside the container.

6. Configuring Your First Monitor

After logging in, click the Add New Monitor button to configure your first health check. Uptime Kuma supports several Monitor Types, including:

HTTP(s): checks if a website responds with expected HTTP status codes, ideal for tracking end-user web experience.
TCP Port: checks if specific ports (e.g., database or SSH ports) accept network connections.
Ping: checks if a target host responds to ICMP ping requests.
DNS: checks if domain DNS records resolve correctly.
Docker Container: monitors the execution status of Docker containers on the local host.

Example setup for web monitoring:

Select HTTP(s) as the Monitor Type.
Enter a Friendly Name, such as "Primary Website".
Enter the complete target URL.
Set the Heartbeat Interval (frequency of checks). Uptime Kuma warns against intervals below 20 seconds due to risks of overloading target servers and generating network jitter false positives; a 60-second interval with 2 to 3 retries before marking status as down provides a balanced configuration.

To monitor the host VPS itself, a Ping monitor target using the server IP is sufficient. To monitor local Docker containers, use the Docker Container monitor type, which requires mounting -v /var/run/docker.sock:/var/run/docker.sock when launching Uptime Kuma. Because mounting the Docker socket grants full root-equivalent access to the Docker daemon, avoid exposing the dashboard to the public internet when using this configuration.

7. Setting Up Downtime Notifications

Monitoring without alerts forces sysadmins to manually check dashboards continuously. Uptime Kuma features built-in notification drivers for Telegram, Discord, and email, alongside Apprise integration covering 78+ third-party notification platforms.

To configure alerts, go to Settings > Notifications, then click Setup Notification. The setup modal shares a common layout across all drivers:

Notification Type: dropdown list containing supported services grouped by categories such as Chat Platforms (Telegram, Discord, Slack, Teams), Email, Push Services (Pushover, ntfy, Bark), SMS Services, Incident Management (PagerDuty, Opsgenie), and Universal options (Webhooks, Apprise).
Friendly Name: an identifier for the notification channel.
Default enabled: if checked, automatically applies this notification configuration to newly created monitors.
Apply on all existing monitors: if checked, immediately attaches this notification channel to all existing monitors.

Specific inputs under Notification Type vary by provider. Here are configuration steps for three common integrations:

7.1 Notifications via Telegram

Bot Token: API token acquired from BotFather after creating a bot using the /newbot command.
Chat ID: target chat or group ID. Uptime Kuma provides an Auto Get feature to fetch this automatically, provided a message has already been sent to the bot (retrieved via getUpdates).
Message Thread ID (optional): used to target specific topic threads inside Telegram supergroups.
Server URL: defaults to https://api.telegram.org, customizable when self-hosting a Telegram Bot API server.
Message Format: Plain Text, HTML, or MarkdownV2.
Send Silently and Protect Content: options to mute notification alerts or block forwarding/copying.

7.2 Notifications via Discord

Discord Webhook URL: generated within Discord channel settings under Integrations > Webhooks.
Bot Display Name: custom sender display name overriding default application name.
Select message type: defines output format (standard channel message, forum post, or thread target).
Message Format: Normal (rich rich embed view), Minimalist (plain concise text), or Custom (template-based).
Prefix Custom Message: text prepended to alerts, such as role mentions (e.g., @everyone).
Disable URL in Notification and Suppress Notifications: options to hide monitor links or suppress push notifications.

Using the Normal format renders Discord notifications as red embedded messages titled "Your service [Monitor Name] went down" during outages, switching to green embeds titled "Your service [Monitor Name] is up!" upon recovery.

7.3 Notifications via SMTP Email

Hostname and Port: SMTP mail server address and port (e.g., external SMTP service or local MTA running on localhost).
Security: None or TLS. Selecting None reveals a Disable STARTTLS option to prevent opportunistic TLS upgrades.
Ignore TLS Error: useful when utilizing self-signed certificates without official CA verification.
Username and Password: authentication credentials for the SMTP server.
From Email and To Email: sender and recipient email addresses (multiple recipients separated by commas). CC and BCC fields are optionally available.
Custom Subject and Custom Body: optional custom alert text formats supporting HTML markup.

Advanced delivery options include Additional Headers (JSON format) and DKIM Settings (domain, key selector, private key, hash algorithm) to ensure DKIM signing and prevent spam filtering.

The workflow remains identical across all integrations: complete the form fields, click Test to verify delivery, and click Save. If Apply on all existing monitors was left unchecked, channels can still be attached manually within individual monitor settings.

8. Creating a Public Status Page

A status page provides a public interface displaying real-time service health without granting access to the admin dashboard, helping support teams communicate outage information efficiently during incidents.

Navigate to Status Pages, then click New Status Page.
Set a page title and URL slug.
Drag monitors into custom groups (e.g., "Websites" or "APIs").
Click Save to publish changes. Status pages support custom domain mapping alongside default Uptime Kuma subpaths.

9. Securing Uptime Kuma with a Reverse Proxy and SSL

Exposing port 3001 unencrypted without HTTPS exposes login credentials to potential man-in-the-middle attacks. Secure your instance by placing Uptime Kuma behind a reverse proxy handling SSL termination (e.g., Nginx or Caddy).

Point your domain or subdomain A record to your VPS IP address. Note: Uptime Kuma does not support subdirectories like http://example.com/uptimekuma; dedicated root domains or subdomains are required.

Configure the reverse proxy. Nginx example configuration:

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The Upgrade/Connection headers and proxy_http_version 1.1 directives are mandatory because the dashboard relies on WebSockets for real-time status updates. Without them, status updates will freeze.

If binding port 3001 strictly to localhost (section 4.1), enable Trust Proxy under Settings > Reverse Proxy > HTTP Headers → Yes so Uptime Kuma accurately parses real client IP addresses from X-Forwarded-For headers. Enable this only when direct public access to port 3001 is fully blocked.
Issue an SSL certificate using Let's Encrypt via Certbot or automated reverse proxies like Nginx Proxy Manager or Caddy.

10. Updating and Backing Up Uptime Kuma

Uptime Kuma receives regular updates. Sysadmins should follow safe upgrade paths to maintain data integrity across releases.

Updating via Docker Compose (for setups using method 4.2):

docker compose pull
docker compose up -d --force-recreate

The pull command downloads the newest container image layer, while up -d --force-recreate rebuilds container instances while retaining persisted volume data.

Updating via manual Docker Run (for setups using method 4.1):

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

Re-run the original docker run command specified in section 4.1. Because volume storage uptime-kuma remains intact during container removal, configuration data persists safely.

Data Backup. Uptime Kuma stores database records and system files inside /app/data. Backup the entire directory rather than isolating the SQLite file. Mount a temporary container sharing volume data from uptime-kuma to archive contents to the host environment:

docker run --rm --volumes-from uptime-kuma -v $(pwd):/backup alpine tar czf /backup/uptime-kuma-backup.tar.gz /app/data

If utilizing Docker Compose bind mounts to ./data, archive local directories directly via tar czf uptime-kuma-backup.tar.gz ./data.

Store backup archives off-site (e.g., remote object storage or secondary backup servers) to ensure disaster recovery capabilities.

Common Troubleshooting:

Port collision (port is already allocated): rebind host mapping (e.g., 3002:3001) and access the interface on the new host port.
Immediate container exit: review container logs via docker logs uptime-kuma to identify startup exceptions.
Dashboard fails to update live behind reverse proxy: verify WebSocket proxy headers (Upgrade and Connection) are correctly configured as covered in section 9.

11. Conclusion

Uptime Kuma provides sysadmins with a powerful solution to monitor websites and infrastructure without subscription fees while maintaining total control over monitoring telemetry. Leveraging Docker streamlines deployment, upgrades, and maintenance relative to bare-metal installations.

Recommended next steps: expand monitoring coverage across critical infrastructure, construct notification groups ranked by severity, and publish public status dashboards to keep teams and clients informed.

12. Frequently Asked Questions

Is Uptime Kuma completely free?

Yes. Uptime Kuma is open-source software licensed under the MIT license, allowing free usage, modification, and self-hosting without licensing fees. Hosting server infrastructure costs remain the only variable expense.

How many websites can be monitored simultaneously?

The application imposes no artificial monitor limits. Hardware capacity limits depend on host CPU and RAM resources, influenced primarily by aggressive check intervals across large monitor sets.

How does Uptime Kuma differ from UptimeRobot?

UptimeRobot functions as a commercial SaaS provider managing data on third-party infrastructure with tier limits. Uptime Kuma is completely self-hosted, keeping operational data private without monitor count restrictions.

Does Uptime Kuma require a dedicated VPS?

No dedicated VPS is required. Uptime Kuma is lightweight and can co-exist alongside other containerized workloads provided system memory and CPU headroom remain available.