How to Install Uptime Kuma on AlmaLinux 9 Using Docker Compose

Estimated reading: 4 minutes 141 views

Introduction

Uptime Kuma is a lightweight, open-source monitoring tool that allows you to monitor websites, servers, network services, APIs, and other infrastructure.

In this guide, we will install Uptime Kuma on AlmaLinux 9 using Docker Compose. Uptime Kuma will run inside a Docker container with persistent storage, making the installation easy to manage and maintain.

This guide focuses only on installing Uptime Kuma. Monitor and notification configuration can be completed after the installation.

Prerequisites

Before starting, make sure you have:

AlmaLinux 9 server
Root or sudo access
At least 1 CPU core
At least 512 MB RAM
At least 5 GB of available storage
Internet access

Step 1: Update the System

Connect to your AlmaLinux 9 server using SSH.

Update all system packages:

dnf update -y

Install the required packages:

dnf install curl dnf-plugins-core -y

The dnf-plugins-core package provides the config-manager command used to add the Docker repository.

Step 2: Install Docker

Add the official Docker repository:

dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Install Docker Engine, Docker CLI, containerd, Buildx, and the Docker Compose plugin:

dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Enable Docker and start the service:

systemctl enable --now docker

Check the Docker service:

systemctl status docker

If Docker is running correctly, the service should show:

Active: active (running)

Verify the Docker version:

docker --version

Verify Docker Compose:

docker compose version

If both commands return version information, Docker and Docker Compose have been installed successfully.

Step 3: Create the Uptime Kuma Directory

Create a dedicated directory for Uptime Kuma:

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

Create a directory for persistent application data:

mkdir -p data

The data directory stores Uptime Kuma’s database and configuration files.

Because the data is stored outside the container, it will remain available even if the Docker container is recreated or updated.

Step 4: Create the Docker Compose File

Create a new Docker Compose configuration file:

nano docker-compose.yml

Add the following configuration:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

Save the file and exit Nano.

The configuration uses port 3001 for the Uptime Kuma web interface and stores persistent data in /opt/uptime-kuma/data.

Step 5: Start Uptime Kuma

Start Uptime Kuma using Docker Compose:

docker compose up -d

Docker will download the Uptime Kuma image and create the container automatically.

Check the container status:

docker compose ps

You can also check the container directly:

docker ps

The container should show a status similar to:

Up

If the container is running, Uptime Kuma has been successfully started.

Step 6: Configure the Firewall

AlmaLinux 9 commonly uses firewalld to manage the system firewall.

Allow TCP port 3001:

firewall-cmd --permanent --add-port=3001/tcp

Reload the firewall:

firewall-cmd --reload

Verify the firewall configuration:

firewall-cmd --list-ports

You should see:

3001/tcp

If firewalld is not running, check its status:

systemctl status firewalld

If you are using another firewall or an external VPS firewall, make sure TCP port 3001 is also allowed there.

Step 7: Access Uptime Kuma

Once Uptime Kuma is running and port 3001 is accessible, open a web browser and visit:

http://SERVER_IP:3001

Replace SERVER_IP with the public IP address of your AlmaLinux server.

For example:

http://203.0.113.10:3001

If the Uptime Kuma setup page appears, the installation was successful.

You can now create the administrator account and access the Uptime Kuma dashboard.

Useful Uptime Kuma Commands

Check Container Status

cd /opt/uptime-kuma
docker compose ps

View Container Logs

docker logs -f uptime-kuma

Press Ctrl + C to exit the log view.

Restart Uptime Kuma

docker restart uptime-kuma

Stop Uptime Kuma

cd /opt/uptime-kuma
docker compose down

Start Uptime Kuma

cd /opt/uptime-kuma
docker compose up -d

Check Docker Service

systemctl status docker

Uptime Kuma Data Location

All persistent Uptime Kuma data is stored in:

/opt/uptime-kuma/data

The Docker Compose configuration is stored in:

/opt/uptime-kuma/docker-compose.yml

These files should be retained if you need to migrate or restore the Uptime Kuma installation.

Conclusion

Uptime Kuma is now installed and running on AlmaLinux 9 using Docker Compose.

The Uptime Kuma web interface is available at:

http://SERVER_IP:3001

The installation uses persistent storage at /opt/uptime-kuma/data, so Uptime Kuma’s configuration and database remain available even if the Docker container is restarted or recreated.

You can now log in to the Uptime Kuma web interface and begin configuring your monitors and notification services.