Setting Up Uptime Monitoring

Setting Up Uptime Monitoring

This guide details how to set up a self-hosted uptime monitoring solution using Uptime Kuma, a popular and user-friendly alternative to services like Pingdom. We will cover installation, configuration, and basic usage, along with considerations for setting up public status pages.

Introduction

Ensuring your servers and services are consistently available is crucial for any system administrator. Downtime can lead to lost revenue, damaged reputation, and frustrated users. While commercial services offer robust monitoring, self-hosting provides greater control, privacy, and cost-effectiveness. Uptime Kuma is an excellent open-source tool that allows you to monitor various services, receive notifications, and display their status on a public page.

Prerequisites

Before you begin, ensure you have the following:

• A Linux server with root or sudo privileges. A VPS from providers like PowerVPS (https://powervps.net/?from=32) is a good option for hosting monitoring tools.
• Docker and Docker Compose installed on your server. If not, follow the official Docker installation guide for your distribution.
• Basic familiarity with the Linux command line.
• (Optional) A domain name or subdomain for accessing your Uptime Kuma instance and its status page.

Installing Uptime Kuma with Docker Compose

Using Docker Compose simplifies the installation and management of Uptime Kuma.

Step 1: Create a Docker Compose File

Create a directory for your Uptime Kuma installation and navigate into it:

mkdir uptime-kuma
cd uptime-kuma

Create a file named docker-compose.yml with the following content:

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      - /etc/localtime:/etc/localtime:ro
    environment:
      - NODE_ENV=production

• image: louislam/uptime-kuma:1: Specifies the Uptime Kuma Docker image.
• container_name: uptime-kuma: Assigns a friendly name to the container.
• restart: unless-stopped: Ensures the container restarts automatically if it crashes or the server reboots.
• ports: - "3001:3001": Maps port 3001 on your host machine to port 3001 inside the container, which is Uptime Kuma's default port.
• volumes: - ./data:/app/data: This is crucial for data persistence. It maps a local directory named data within your uptime-kuma folder to the container's data directory, ensuring your monitoring configurations are saved even if the container is removed and recreated.
• volumes: - /etc/localtime:/etc/localtime:ro: Syncs the container's time with your host system's time.
• environment: - NODE_ENV=production: Sets the environment to production for optimal performance.

Step 2: Start Uptime Kuma

Run the following command in the same directory as your docker-compose.yml file:

docker-compose up -d

The -d flag runs the container in detached mode, meaning it will run in the background.

Step 3: Access Uptime Kuma

Open your web browser and navigate to http://your_server_ip:3001. You should see the Uptime Kuma setup page.

Step 4: Initial Setup

On the first visit, you will be prompted to create an administrator account. Enter a strong password and click "Save". You will then be redirected to the Uptime Kuma dashboard.

Adding Monitors

The Uptime Kuma dashboard is where you'll add and manage your monitors.

Step 1: Click "Add New Monitor"

On the dashboard, click the prominent "Add New Monitor" button.

Step 2: Configure Monitor Type

Uptime Kuma supports various monitor types:

• **HTTP(s):** Checks if a web server is responding with a 2xx status code.
• **TCP:** Checks if a specific port is open and listening.
• **Ping:** Sends ICMP echo requests to an IP address or hostname.
• **Keyword:** Checks if a specific keyword exists on a web page.
• **Docker:** Monitors the status of Docker containers.
• ** and many more...**

For example, to monitor a website:

• Select "HTTP(s)".
• Enter the URL (e.g., https://yourwebsite.com).
• Give it a name (e.g., "My Website").
• Set the interval (e.g., every 1 minute).
• Configure advanced settings like expected status code (e.g., 200) or response time thresholds if needed.

For example, to monitor a database on a specific port:

• Select "TCP".
• Enter the hostname or IP address (e.g., db.yourdomain.com or 192.168.1.10).
• Enter the port number (e.g., 5432 for PostgreSQL, 3306 for MySQL).
• Give it a name (e.g., "Database Server").
• Set the interval.

Step 3: Save the Monitor

Click "Save" to add the monitor. Uptime Kuma will immediately start checking its status.

Setting Up Notifications

Receiving alerts when a service goes down is essential. Uptime Kuma integrates with numerous notification services.

Step 1: Navigate to "Settings"

Click on the "Settings" icon (gear) in the top-right corner of the dashboard.

Step 2: Go to "Notification Services"

Select "Notification Services" from the left-hand menu.

Step 3: Add a Notification Service

Click "Add Notification Service". Choose your preferred service from the list (e.g., Telegram, Discord, Slack, Email, Webhook).

Step 4: Configure the Service

Follow the on-screen instructions to configure your chosen service. This typically involves providing API keys, tokens, or webhook URLs. For example, for Telegram, you would need your Bot Token and Chat ID.

Step 5: Assign Monitors to Notifications

After setting up a notification service, go back to your monitor's configuration (edit the monitor and scroll down to the "Notifications" section). Select the notification service you just added to receive alerts for that specific monitor.

Public Status Page

Uptime Kuma can generate a public-facing status page to inform your users about the availability of your services.

Step 1: Enable Status Page

Go to "Settings" > "Status Page". Toggle the "Enable Status Page" option.

Step 2: Configure Status Page Appearance

You can customize the title, logo, and theme of your status page.

Step 3: Add Monitors to Status Page

On the "Status Page" settings, you can select which monitors you want to display on the public page.

Step 4: Access Your Status Page

Your status page will be available at http://your_server_ip:3001/status by default. If you have configured a custom domain with a reverse proxy (e.g., Nginx or Caddy), you can access it via that domain.

Advanced Configurations

Reverse Proxy with Nginx

To access Uptime Kuma via a custom domain (e.g., status.yourdomain.com) and secure it with SSL, you can set up a reverse proxy with Nginx.

First, ensure you have Nginx installed and running. Then, create an Nginx configuration file (e.g., /etc/nginx/sites-available/uptime-kuma):

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

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        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;
    }
}

Enable the site and restart Nginx:

sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo systemctl restart nginx

You can then use Certbot to obtain an SSL certificate for status.yourdomain.com.

High Availability and Redundancy

For critical monitoring, consider running multiple Uptime Kuma instances on different servers or even in different geographic locations. For example, you could host a primary instance on a VPS from PowerVPS (https://powervps.net/?from=32) and a secondary instance on a cloud GPU provider like Immers Cloud GPU (https://en.immers.cloud/signup/r/20241007-8310688-334/) for failover.

Troubleshooting

• **Uptime Kuma not starting:** Check Docker logs using docker logs uptime-kuma. Ensure port 3001 is not already in use on your host.
• **Monitors not reporting status:**

   *   Verify the monitor's configuration (URL, IP, port).
   *   Ensure the server running Uptime Kuma can reach the target service (check firewalls).
   *   For HTTP monitors, check if the expected status code is correct.

• **Notifications not sending:**

   *   Double-check your notification service credentials and configuration.
   *   Test the notification service directly if possible.
   *   Check Uptime Kuma's logs for any errors related to notifications.

• **Status page not accessible:**

   *   Ensure the status page is enabled in Uptime Kuma settings.
   *   If using a reverse proxy, check Nginx/Caddy logs and configuration.
   *   Verify firewall rules allow access to the Uptime Kuma port or your reverse proxy's port.

Related Articles

• Introduction to Docker
• Nginx Reverse Proxy Setup
• Server Security Best Practices