Aug 5, 2024 4 min read

Uptime Kuma: Self-Hosting Made Simple

Uptime Kuma: Self-Hosting Made Simple
Table of Contents

Uptime Kuma is a modern, self-hosted monitoring tool designed to keep track of the uptime, performance, and availability of your services, websites, or APIs. Its intuitive interface, robust features, and lightweight design make it an excellent choice for developers and system administrators who value customization and control over their monitoring stack. In this guide, we’ll walk through installing, configuring, securing, and managing Uptime Kuma to get you up and running in no time.

Installing Uptime Kuma

πŸ“¦ Docker/Docker Compose Setup

Docker is the easiest and most popular way to deploy Uptime Kuma. Below is a docker-compose.yml file tailored to Uptime Kuma:


version: '3.3'

services:

uptime-kuma:

image: louislam/uptime-kuma:latest

container_name: uptime-kuma

restart: always

ports:

- "3001:3001" # Map port 3001 on the host to port 3001 in the container

volumes:

- /path/to/uptime-kuma/data:/app/data # Persistent data storage

Save the above file as docker-compose.yml and run the following commands to deploy Uptime Kuma:


cd /path/to/docker-compose

## Deploy the container

docker-compose up -d

Verify that the app is running by visiting http://<your-server-ip>:3001 in your browser.

πŸš€ Manual Installation

For those who prefer not to use Docker, you can install Uptime Kuma directly on a Linux server:


## Update system packages

sudo apt update && sudo apt upgrade -y

## Install Node.js and npm (minimum version: Node.js 14.x)

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -

sudo apt install nodejs -y

## Clone the Uptime Kuma repository

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

cd uptime-kuma

## Install dependencies

npm install

## Start Uptime Kuma

node server/server.js

By default, Uptime Kuma will run on port 3001. You can access it via http://<your-server-ip>:3001.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Setting up Nginx as a reverse proxy allows you to serve Uptime Kuma on a custom domain and improve accessibility. Create an Nginx server block:


sudo nano /etc/nginx/sites-available/uptime-kuma

Add the following configuration (replace example.com with your domain):


server {

listen 80;

server_name example.com;

location / {

proxy_pass http://127.0.0.1:3001;

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 configuration and reload Nginx:


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

sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Use Certbot to secure your domain with Let's Encrypt:


sudo apt install certbot python3-certbot-nginx -y

sudo certbot --nginx -d example.com

Automatically renew your certificates by adding Certbot to the crontab:


sudo crontab -e

## Add the following line

0 0 * * * certbot renew --quiet

Verify that your site is now accessible via https://example.com.

Logging and Debugging Uptime Kuma

πŸ—ƒοΈ Enabling Debug Logs

To enable debug logs, set the LOG_LEVEL environment variable to debug in your Docker Compose file or server configuration:


environment:

- LOG_LEVEL=debug

Restart the application to apply the changes.

πŸ“„ Viewing Logs

For Docker deployments, view logs using the following command:


docker logs uptime-kuma

For manual installations, logs are stored in the logs directory:


tail -f /path/to/uptime-kuma/logs/server.log

πŸ› οΈ Troubleshooting Common Issues

  • Port conflicts: Ensure no other services are using port 3001. Modify the docker-compose.yml file or Node.js server configuration to change the port if necessary.

  • Nginx errors: Use sudo nginx -t to test Nginx configurations before reloading.

  • SSL issues: Check Certbot logs at /var/log/letsencrypt/letsencrypt.log.

πŸ“€ Exporting Logs

To send logs to an external system like ELK Stack, configure a log forwarder such as Filebeat or Fluentd to process Uptime Kuma’s log files.

Backup and Restore

πŸ—‚οΈ File-Based Backups

To back up Uptime Kuma’s data directory (used by Docker or manual installations):


tar -czvf uptime-kuma-backup.tar.gz /path/to/uptime-kuma/data

πŸ”„ Database Backups

If you’re using SQLite (default), the database file is stored in data/kuma.db. Backup the database with:


cp /path/to/uptime-kuma/data/kuma.db /path/to/backup/

πŸ“… Automated Backup Scripts

Automate backups with a simple cron job:


crontab -e

## Add the following line to back up daily at midnight

0 0 * * * tar -czvf /path/to/backup/uptime-kuma-$(date +\%F).tar.gz /path/to/uptime-kuma/data

Updating and Upgrading Uptime Kuma

⬆️ Updating Docker Images

Update your Docker image and redeploy the container:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations, pull the latest changes from the repository and reinstall dependencies:


cd /path/to/uptime-kuma

git pull

npm install

node server/server.js

πŸ” Checking for Updates

To check for the latest version of Uptime Kuma, visit the GitHub repository.

Leveraging Uptime Kuma’s Unique Features

πŸ”§ Enabling APIs

Uptime Kuma supports API endpoints for integration with external systems. Example: Add a monitor via the API using curl:


curl -X POST http://<your-server-ip>:3001/api/monitor \

-H "Authorization: Bearer <your-api-token>" \

-H "Content-Type: application/json" \

-d '{

"name": "Example Monitor",

"url": "https://example.com",

"method": "GET",

"interval": 60

}'

🌟 Advanced Configurations

Enable Telegram notifications by adding a bot token and chat ID under the Notifications section of the UI. For Slack, use a webhook URL for alerts.

Wrapping Up

This guide covered the essential steps to install, configure, and manage Uptime Kuma. By following these instructions, you can take full control of your monitoring stack, from securing your deployment with SSL to leveraging advanced APIs for integrations. With Uptime Kuma’s flexibility and rich feature set, you can customize it to perfectly suit your infrastructure needs. Start exploring its capabilities today!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.