SERVER

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.

Uptime Kuma: Easily Install Your Open-Source Monitoring Tool with Docker hero image

Table of Contents

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.

  1. 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

  2. Create Docker Compose File Make a compose.yaml file with a text editor like nano):

    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 (like ghcr.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 the data 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, use Ctrl+O, Enter, then Ctrl+X).

  3. 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:

  1. Select Language: Choose your preferred language.
  2. Create User Account: Set up an administrator username and a secure password.
  3. 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”.

  1. Monitor Type: Choose the appropriate type. For a website, “HTTP(s)” is common.
  2. Friendly Name: A descriptive name, e.g., “My Website”.
  3. URL: The full URL, e.g., https://deployn.de.
  4. Heartbeat Interval: How often to check (e.g., every 60 seconds).
  5. Retries on Failure: How many times a failure must occur before the service is marked as “Down”.
  6. Notifications: Select your previously configured notification channels for this monitor.
  7. 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.

  1. Click “Status Pages” in the menu.
  2. Click ”+ New Status Page”.
  3. Name: e.g., “Deployn Status”.
  4. Slug: A URL-friendly name, e.g., deployn-status.
  5. Click “Next”.
  6. In the next step (“Add Monitors”), select the monitors to be displayed on this status page.
  7. 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.

  1. 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 for uptime-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.

  2. 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: Host uptime-kuma-db, Port 3306, User, Password, and Database Name as specified in your compose.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.

  1. 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

  2. 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 the uptime-kuma container on port 3001.

  3. Adjust Uptime Kuma Docker Compose: Open the compose.yaml for Uptime Kuma again:

    • Ensure the ports section for the uptime-kuma service is commented out or removed, as Caddy will handle access.
    • Add the uptime-kuma service to the proxy 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 if internal isn’t used.

  4. 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.

  1. Bind Docker Socket into Uptime Kuma: Adjust the compose.yaml for the uptime-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.

  2. Restart Containers:

    sudo docker compose up -d

  3. 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”.

  4. 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 or uptime-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!

#uptime kuma #docker #monitoring #self hosted #vps #tutorial #docker compose

Share this post:

Back to all posts
This website uses cookies. These are necessary for the functionality of the website. You can find more information in the privacy policy