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!