How to Set Up Uptime Kuma for Service Monitoring on RHEL 7

January 17, 2026
Linux
Comment off

How to Set Up Uptime Kuma for Service Monitoring on RHEL 7

Uptime Kuma is a self-hosted, open-source uptime monitoring tool that provides a clean web interface for tracking the availability of HTTP endpoints, TCP ports, DNS records, and more. It supports multiple notification channels including email, Slack, and Telegram, and includes a built-in public status page you can share with your users or clients. This guide walks through a complete installation of Uptime Kuma on Red Hat Enterprise Linux 7, covering both the direct Node.js method and a Docker-based alternative, along with Nginx reverse proxy configuration for production use.

Prerequisites

RHEL 7 server with a non-root sudo user
At least 512 MB RAM (1 GB recommended)
Git installed (yum install git)
Node.js 18 or later (see installation steps below)
Nginx installed for the reverse proxy (yum install nginx)
Firewall access to port 3001 (or 80/443 via Nginx)

Step 1: Install Node.js 18 on RHEL 7

RHEL 7 ships with an older version of Node.js in its default repositories. Uptime Kuma requires Node.js 18 or higher, so you must install it from the NodeSource repository.

# Install the NodeSource Node.js 18 repository
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -

# Install Node.js 18 and npm
sudo yum install -y nodejs

# Verify the installation
node --version
npm --version

You should see output similar to v18.x.x for Node.js and 9.x.x for npm. Next, install PM2, a production process manager for Node.js applications that will keep Uptime Kuma running after you close your terminal session and restart it automatically after system reboots.

# Install PM2 globally
sudo npm install -g pm2

# Verify PM2 installation
pm2 --version

Step 2: Clone and Install Uptime Kuma

Clone the Uptime Kuma repository from GitHub and install its Node.js dependencies. It is good practice to run the application as a dedicated non-privileged user rather than root.

# Create a dedicated system user
sudo useradd -r -s /sbin/nologin -d /opt/uptime-kuma uptimekuma

# Create the application directory
sudo mkdir -p /opt/uptime-kuma
sudo chown uptimekuma:uptimekuma /opt/uptime-kuma

# Clone the repository as the uptimekuma user
sudo -u uptimekuma git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma

# Change into the directory
cd /opt/uptime-kuma

# Install Node.js dependencies
sudo -u uptimekuma npm install --production

The npm install step may take several minutes as it downloads and compiles native modules. Once complete, you can perform a quick test run to confirm the application starts correctly before configuring it as a service.

# Test run (press Ctrl+C after confirming it starts)
sudo -u uptimekuma node server/server.js

You should see log output ending with something like Listening on :3001.

Step 3: Start Uptime Kuma with PM2

Use PM2 to start Uptime Kuma and configure it to launch automatically on system boot.

# Start the application with PM2 (run as uptimekuma user)
sudo -u uptimekuma bash -c "cd /opt/uptime-kuma && pm2 start server/server.js --name uptime-kuma"

# Save the PM2 process list so it persists across reboots
sudo -u uptimekuma pm2 save

# Generate and enable the systemd startup script for PM2
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u uptimekuma --hp /opt/uptime-kuma
sudo systemctl enable pm2-uptimekuma
sudo systemctl start pm2-uptimekuma

# Verify the service is running
sudo systemctl status pm2-uptimekuma
pm2 list

Step 4: Docker Alternative (Optional)

If Docker is installed on your RHEL 7 server, you can run Uptime Kuma as a container instead of managing the Node.js process directly. This is a simpler approach that bundles all dependencies.

# Pull and run the Uptime Kuma Docker image
docker run -d 
  --restart=always 
  --name uptime-kuma 
  -p 3001:3001 
  -v uptime-kuma:/app/data 
  louislam/uptime-kuma:1

# Verify the container is running
docker ps

# View container logs
docker logs uptime-kuma

Step 5: Configure the Firewall and Access the UI

Open port 3001 in firewalld to access the Uptime Kuma web interface directly, or restrict it to localhost if you plan to use Nginx as a reverse proxy.

# Open port 3001 temporarily for initial setup testing
sudo firewall-cmd --zone=public --add-port=3001/tcp --permanent
sudo firewall-cmd --reload

# Verify the rule was added
sudo firewall-cmd --list-ports

Navigate to http://your-server-ip:3001 in a browser. On first launch, you will be prompted to create an admin account. Choose a strong password, as the dashboard is publicly accessible on port 3001 until you restrict it.

Step 6: Configure Nginx Reverse Proxy with WebSocket Support

Uptime Kuma uses WebSockets for real-time updates in the browser. The Nginx configuration must include the Upgrade and Connection headers to proxy WebSocket traffic correctly.

# Create the Nginx virtual host configuration
sudo vi /etc/nginx/conf.d/uptime-kuma.conf

Add the following content:

upstream uptime_kuma {
    server 127.0.0.1:3001;
    keepalive 32;
}

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

    location / {
        proxy_pass         http://uptime_kuma;
        proxy_http_version 1.1;

        # WebSocket headers — required for Uptime Kuma
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";

        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_read_timeout  600s;
        proxy_send_timeout  600s;
    }
}

# Test the Nginx configuration for syntax errors
sudo nginx -t

# Enable and start Nginx
sudo systemctl enable nginx
sudo systemctl start nginx

# Open HTTP and HTTPS through the firewall
sudo firewall-cmd --zone=public --add-service=http --permanent
sudo firewall-cmd --zone=public --add-service=https --permanent
sudo firewall-cmd --reload

Step 7: Adding Monitors in the Uptime Kuma UI

Once logged in, click Add New Monitor on the dashboard. Uptime Kuma supports several monitor types suited to different use cases.

HTTP(s) — Checks that a URL returns a successful HTTP status code (e.g., 200). You can also match against specific keywords in the response body.
TCP Port — Verifies that a TCP port is open and accepting connections. Useful for monitoring database ports, SMTP, and other non-HTTP services.
Ping (ICMP) — Sends ICMP echo requests to verify host reachability. Suitable for bare-metal servers and network devices.
DNS — Resolves a hostname and checks that the result matches an expected IP address or record value.

Key configuration fields for an HTTP monitor include the heartbeat interval (check frequency), the number of retries before marking a service as down, and an optional accepted status code range. Set a meaningful Friendly Name so notifications are immediately descriptive.

Step 8: Configure Notification Channels

Navigate to Settings → Notifications to add alert channels. Uptime Kuma supports dozens of providers; below are the most commonly used.

Email (SMTP)

Notification Type: Email (SMTP)
SMTP Host:         smtp.example.com
SMTP Port:         587
Security:          STARTTLS
Username:          [email protected]
Password:          <app-password>
From:              [email protected]
To:                [email protected]

Slack

Notification Type: Slack
Webhook URL:       https://hooks.slack.com/services/T000/B000/xxxx
Channel:           #ops-alerts
Username:          Uptime Kuma

Notification Type: Telegram
Bot Token:         123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Chat ID:           -100123456789

After saving a notification, use the Test button to confirm delivery before assigning it to monitors.

Step 9: Create a Public Status Page

Uptime Kuma includes a built-in status page you can share with customers or stakeholders. Go to Status Page in the sidebar and click New Status Page. Give it a title and a URL slug (e.g., status, which will be available at http://monitor.example.com/status/status). Add monitor groups and individual monitors to the page. You can customise the theme, logo, and incident description. The status page automatically reflects current monitor states in real time via WebSocket.

Conclusion

You now have a fully functional Uptime Kuma installation on RHEL 7, managed by PM2 or Docker and fronted by an Nginx reverse proxy with proper WebSocket support. Monitors for HTTP endpoints, TCP ports, ICMP pings, and DNS records will alert your team through email, Slack, or Telegram the moment a service goes down. The public status page provides transparent uptime reporting without requiring stakeholders to log in to the dashboard. As your infrastructure grows, Uptime Kuma scales easily — simply add new monitors and notification groups from the web interface without any configuration file changes.

How to Set Up Uptime Kuma for Service Monitoring on RHEL 7