Practical Monitoring on a Budget (Uptime Kuma + Alerts)

TL;DR

Uptime Kuma is a self-hosted monitoring solution that provides an easy way to track the uptime of your services. This guide will help you set it up on a Debian 13 server with alerts, all while keeping costs low.

1. Install Docker and Docker Compose: First, ensure you have Docker and Docker Compose installed, as Uptime Kuma runs in a containerized environment.

   sudo apt update && sudo apt install -y docker.io docker-compose
   sudo systemctl enable --now docker  # Enable Docker to start on boot
   

2. Set Up Uptime Kuma: Create a directory for Uptime Kuma and set up the Docker Compose file.

   mkdir uptime-kuma && cd uptime-kuma
   cat <<EOF > docker-compose.yml
   version: '3'
   services:
     uptime-kuma:
       image: louislam/uptime-kuma
       restart: always
       ports:
         - "3001:3001"  # Change if needed
       volumes:
         - ./data:/app/data  # Persistent storage
   EOF
   

3. Run Uptime Kuma: Start the Uptime Kuma service using Docker Compose.

   sudo docker-compose up -d  # Run in detached mode
   

4. Access the Web Interface: Open your web browser and navigate to http://<your-server-ip>:3001 to access the Uptime Kuma dashboard.

5. Set Up Alerts: Configure alerts within the Uptime Kuma interface to receive notifications via email or other channels. Always use secure credentials for any notification services.

6. Security Considerations:

   • Ensure your server’s firewall allows traffic on the port you configured (default 3001).
   • Regularly update your Docker images to mitigate vulnerabilities.

By following these steps, you can effectively monitor your services without incurring significant costs, while ensuring a secure and reliable setup.

Installation of Uptime Kuma

To install Uptime Kuma on your Debian 13 server, follow these steps to ensure a smooth setup.

First, update your package list and install necessary dependencies:

sudo apt update && sudo apt upgrade -y  # Update package list and upgrade installed packages
sudo apt install -y git curl docker.io docker-compose  # Install Git, cURL, Docker, and Docker Compose

Next, enable and start the Docker service:

sudo systemctl enable docker  # Enable Docker to start on boot
sudo systemctl start docker   # Start Docker service

Now, create a directory for Uptime Kuma:

mkdir ~/uptime-kuma && cd ~/uptime-kuma  # Create and navigate to the Uptime Kuma directory

Clone the Uptime Kuma repository:

git clone https://github.com/louislam/uptime-kuma.git .  # Clone the Uptime Kuma repository into the current directory

Next, set up the Docker containers using Docker Compose. Create a docker-compose.yml file:

nano docker-compose.yml  # Open a new file for editing

Insert the following configuration into the file:

version: '3'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    restart: always
    ports:
      - "3001:3001"  # Expose port 3001 for web access
    volumes:
      - ./data:/app/data  # Persist data in the 'data' directory

Save and exit the editor (Ctrl + X, then Y, then Enter).

Now, start Uptime Kuma:

sudo docker-compose up -d  # Run Uptime Kuma in detached mode

To ensure security, consider setting up a reverse proxy with SSL using Nginx or Traefik. This will help secure your monitoring interface. Always monitor your server’s resource usage and adjust Docker settings as necessary to prevent overload.

Configuring Uptime Kuma

To configure Uptime Kuma on your Debian 13 server, follow these steps to ensure a secure and efficient setup.

First, create a dedicated user for Uptime Kuma to run under, minimizing security risks:

sudo adduser --system --no-create-home uptime-kuma

Next, install the necessary dependencies. Ensure you have Node.js and npm installed:

sudo apt update
sudo apt install -y nodejs npm

Verify the installation:

node -v  # Check Node.js version
npm -v   # Check npm version

Now, clone the Uptime Kuma repository:

sudo git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma

Change ownership to the newly created user:

sudo chown -R uptime-kuma:uptime-kuma /opt/uptime-kuma

Navigate to the Uptime Kuma directory and install the required packages:

cd /opt/uptime-kuma
sudo -u uptime-kuma npm install

Next, configure Uptime Kuma. You can run it using Docker for easier management. First, install Docker:

sudo apt install -y docker.io
sudo systemctl enable --now docker

Then, run Uptime Kuma using Docker:

sudo docker run -d -p 3001:3001 \
  --restart always \
  --name uptime-kuma \
  -v uptime-kuma-data:/app/data \
  louislam/uptime-kuma

This command sets Uptime Kuma to restart automatically and maps port 3001 for web access. Ensure your firewall allows traffic on this port:

sudo ufw allow 3001/tcp  # Allow access to Uptime Kuma

Finally, access Uptime Kuma by navigating to http://your-server-ip:3001 in your web browser. Remember to secure your installation by setting up HTTPS and user authentication as needed.

Setting Up Alerts

To set up alerts for your Uptime Kuma monitoring system on Debian 13, you can utilize built-in notification features to receive timely updates about your services. Here’s how to configure email alerts using Postfix and Uptime Kuma.

First, you need to install Postfix, which will handle sending emails from your server.

sudo apt update
sudo apt install postfix mailutils

During installation, select “Internet Site” when prompted and set your system’s mail name to your domain or server’s hostname.

Step 2: Configure Postfix

Edit the Postfix configuration to ensure it uses your server’s hostname:

sudo nano /etc/postfix/main.cf

Make sure the following lines are present and correctly set:

myhostname = your-server-hostname
mydestination = $myhostname, localhost.$mydomain, localhost

After editing, restart Postfix to apply changes:

sudo systemctl restart postfix

Step 3: Set Up Email Alerts in Uptime Kuma

1. Log in to your Uptime Kuma dashboard.

2. Navigate to “Settings” and then “Notifications.”

3. Click on “Add Notification” and select “Email.”

4. Fill in the required fields:

   • Name: A descriptive name for your alert.
   • Email: Your email address for receiving alerts.
   • SMTP Server: localhost
   • SMTP Port: 25
   • From Email: Your email address.

5. Test the configuration by sending a test email.

Caution

Ensure that your firewall allows outbound connections on port 25 for email delivery. If you are using a cloud provider, check their documentation for any restrictions on SMTP traffic.

Safe Defaults

For security, consider using a dedicated email account for alerts and configure SPF/DKIM records if you plan to send emails from a custom domain. This helps prevent your emails from being marked as spam.

Verification

To ensure that Uptime Kuma is functioning correctly and that alerts are being sent as expected, you can perform a series of verification steps.

First, check the status of the Uptime Kuma service to confirm it is running:

sudo systemctl status uptime-kuma

Look for the “active (running)” status. If it is not running, you can start it with:

sudo systemctl start uptime-kuma

Next, verify that the web interface is accessible. Open a web browser and navigate to http://<your-server-ip>:3001. You should see the Uptime Kuma dashboard. If you encounter issues, ensure that the firewall allows traffic on port 3001:

sudo ufw allow 3001

To test the alerting functionality, you can manually trigger an alert. In the Uptime Kuma dashboard, create a test monitor for a known service (like a website you control) and configure it to send an alert via your chosen method (email, Discord, etc.). After setting it up, you can temporarily take the service down to see if Uptime Kuma sends the alert.

For email alerts, ensure that your mail server is configured correctly. You can test email sending from the command line:

echo "Test email from Uptime Kuma" | mail -s "Test Alert" your-email@example.com

Replace your-email@example.com with your actual email address. Check your inbox for the test email.

Finally, review the logs for any errors or warnings that may indicate issues with the service or alerting:

sudo journalctl -u uptime-kuma

Look for any entries that might indicate problems. If you see errors, consult the Uptime Kuma documentation or community forums for troubleshooting steps. Always ensure your configurations are backed up before making significant changes.

• Linux
• Security
• Smb