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.ymlfile or Node.js server configuration to change the port if necessary. -
Nginx errors: Use
sudo nginx -tto 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!
