DEV Community

Cover image for How To Deploy Uptime Kuma On A Linux Server With Docker Compose
William Kwabena Akoto
William Kwabena Akoto

Posted on

How To Deploy Uptime Kuma On A Linux Server With Docker Compose

#docker #monitoring #tutorial #linux

Introduction

Uptime Kuma is an open-source, self-hosted monitoring tool. It helps you track the uptime, response time, and availability of your websites, APIs, servers, and other network resources.

In this tutorial, I’ll walk through deploying Uptime Kuma using Docker Compose with persistent storage, making it easy to set up and manage.

Prerequisites

Before starting, ensure you have:

  • A Linux server (Ubuntu, Debian, CentOS, etc.)
  • Docker installed
  • Docker Compose installed

Directory Setup

We’ll keep all Uptime Kuma files under /your-desired-folder/uptime-kuma.

sudo mkdir -p /your-desired-folder/uptime-kuma/data
cd /your-desired-folder/uptime-kuma
Enter fullscreen mode Exit fullscreen mode

Directory structure:

/your-desired-folder/
└── uptime-kuma/
    ├── data/                  
    └── docker-compose.yml
Enter fullscreen mode Exit fullscreen mode

Docker Compose File

Create a docker-compose.yml inside /your-desired-folder/uptime-kuma:

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma
    container_name: uptime-kuma
    volumes:
      - /your-desired-folder/uptime-kuma/data:/app/data
    ports:
      - "your-desired-port:3001"
    restart: always
Enter fullscreen mode Exit fullscreen mode

Explanation

  • image: louislam/uptime-kuma → Uses the official Uptime Kuma Docker image.
  • container_name → Assigns a fixed container name for easy management.
  • volumes → Maps /your-desired-folder/uptime-kuma/data (host) → /app/data (container) for persistent storage.

  • ports: "your-desired-port:3001" → Exposes Kuma’s web UI on port your-desired-port of the host.

    • Access via: http://<your-server-ip>:your-desired-port

  • restart: always → Automatically restarts if the container stops or after a server reboot.

Deploy Uptime Kuma

Run:

docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

Check container status:

docker ps
Enter fullscreen mode Exit fullscreen mode

View logs:

docker logs -f uptime-kuma
Enter fullscreen mode Exit fullscreen mode

Accessing the Dashboard

Once the container is running, open a browser and visit:

http://<your-server-ip>:your-desired-port
Enter fullscreen mode Exit fullscreen mode

On first launch, you’ll be prompted to create an admin account.

Managing Uptime Kuma

  • Start service 
  docker-compose up -d
Enter fullscreen mode Exit fullscreen mode
  • Stop service 
  docker-compose down
Enter fullscreen mode Exit fullscreen mode
  • Update to latest version 
  docker-compose pull
  docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

Best Practices

  • Use an NGINX reverse proxy with Let’s Encrypt for HTTPS instead of exposing Uptime Kuma directly on port your-desired-port.
  • Regularly back up /your-desired-folder/uptime-kuma/data to avoid losing configs and monitoring history.
  • Restrict access via firewall if your server is exposed to the internet.

Conclusion

You now have Uptime Kuma running with Docker Compose. With this setup, you can monitor your infrastructure and services easily, while keeping everything self-hosted and under your control.

Top comments (0)