Server outages rarely happen at a convenient time. Without monitoring in place, you may not discover a website, API, or service failure until users start reporting problems. Uptime Kuma solves that issue by continuously checking your services and alerting you when something goes wrong.
In this tutorial, you’ll learn how to install Uptime Kuma, a free and open-source self-hosted monitoring platform, on an Ubuntu VPS using Docker. By the end, you’ll have a working monitoring dashboard, your first uptime monitor, and optional notifications to alert you when downtime occurs.
Prerequisites
Before getting started, make sure you have:
- An Ubuntu 22.04 or Ubuntu 24.04 VPS
- A user account with sudo privileges
- At least 512 MB of available RAM
- Internet access to download Docker and Uptime Kuma
Note: This guide uses Docker for installation because it offers a fast setup process and simplifies future upgrades.
Step 1: Install Docker
If Docker is not already installed on your server, use Docker’s official convenience script.
Run the following command:
curl -fsSL https://get.docker.com | sudo shThis command downloads and installs the latest Docker packages for your system.
After the installation completes, verify that Docker is working correctly:
docker --version
You should see output similar to:
Docker version 29.2.1, build a5c7197
Fix Docker Permission Issues
If you receive a permission error while running Docker commands without sudo, add your user account to the Docker group:
sudo usermod -aG docker $USERLog out and log back in before testing Docker again.
Step 2: Launch the Uptime Kuma Container
With Docker installed, deploy Uptime Kuma using a single command:
docker run -d --restart=unless-stopped \
-p 3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:1
Let’s break down what each option does:
- -d Runs the container in the background (detached mode).
- –restart=unless-stopped Automatically restarts the container after crashes or server reboots.
- -p 3001:3001 Maps port 3001 on the server to port 3001 inside the container.
- -v uptime-kuma:/app/data Creates a persistent Docker volume to store monitoring data and settings.
- –name uptime-kuma Assigns a recognizable name to the container.
- louislam/uptime-kuma:1 Pulls and runs the Uptime Kuma image.
The first execution will download the image and create the container automatically.
You may see output similar to:
Status: Downloaded newer image for louislam/uptime-kuma:1
37cc155cfa0a6c642568d27b1e388b27a091066d6d490d0d3c1ce2894e904360
The long string at the end is the container ID, indicating that the deployment was successful.
Important: The Docker volume (uptime-kuma) ensures your monitors, settings, and historical data remain available even if the container is recreated.
Step 3: Verify That Uptime Kuma Is Running
Check the container status using:
docker ps --filter name=uptime-kumaA status of Up indicates that the container is running correctly.
Configure Firewall Access
If your server uses UFW (Uncomplicated Firewall), allow traffic on port 3001:
sudo ufw allow 3001Security Note: Opening port 3001 is acceptable for testing, but for production environments it’s recommended to place Uptime Kuma behind a reverse proxy with HTTPS. We’ll cover that later in this tutorial.
Step 4: Create the Administrator Account
Open the following URL in your web browser:
http://YOUR_SERVER_IP:3001
When accessing Uptime Kuma for the first time, you’ll see the setup wizard.
- Select your preferred language.
- Create an administrator username.
- Set a strong password.
- Click Create.
After completing the setup, you’ll be redirected to the main dashboard.
Important: Use a strong unique password because this account controls access to your monitoring system.
Step 5: Add Your First Monitor
Now that Uptime Kuma is running, you can begin monitoring a website or API.
Click Add New Monitor.
Complete the following fields:
- Monitor Type
- Choose: HTTP(s)
- This option is ideal for websites and web APIs.
- Friendly Name
- Enter an easily recognizable label.
- Example:Lineserve Website
- URL
- Enter the full URL you want to monitor.
- Example: https://www.lineserve.net
- Heartbeat Interval
- The default value is: 60 seconds
This means Uptime Kuma will perform a health check every minute.
Once configured, click Save.
Uptime Kuma immediately performs its first check. If the website responds successfully, the monitor status will turn green and display a successful response notification.
Step 6: Understand the Monitoring Dashboard
The dashboard provides a quick overview of service health and performance.
Key metrics include:
a) Service Status
Displays whether the monitored endpoint is currently:
- Up
- Down
You’ll also see a heartbeat timeline showing recent monitoring checks.
b) Response Time
Response time is measured in milliseconds and helps identify performance issues before a complete outage occurs.
For example: 202 ms
A steadily increasing response time may indicate server resource issues, network congestion, or application performance problems.
c) Uptime Percentage
Uptime Kuma calculates service availability over time, including:
- 24-hour uptime
- 30-day uptime
These statistics make it easy to track reliability.
d) SSL Certificate Expiration
For HTTPS-enabled websites, Uptime Kuma monitors SSL certificate validity and displays the remaining days until expiration.
This feature helps prevent unexpected certificate-related outages.
Step 7: Configure Downtime Notifications
Monitoring is most useful when alerts are delivered automatically.
To enable notifications:
- Open Settings.
- Select Notifications.
- Click Setup Notification.
- Choose your preferred notification provider.
Uptime Kuma supports numerous notification channels, including:
- Telegram
- Slack
- Discord
- Email (SMTP)
- Webhooks
- Many additional integrations
After creating the notification method, edit your monitor and attach the notification channel. Once configured, you’ll receive alerts whenever the monitored service goes offline or recovers.
Step 8: Secure Uptime Kuma with a Domain and HTTPS
Accessing Uptime Kuma using an IP address and open port is fine during testing, but a custom domain and SSL certificate provide better security and usability.
A common setup uses:
- A subdomain such as status.yourdomain.com
- Nginx as a reverse proxy
- Let’s Encrypt SSL certificates
Example Nginx configuration:
server {
listen 80;
server_name status.yourdomain.com;
location / {
proxy_pass http://localhost: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-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}The following directives allow WebSocket connections to function correctly:
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection ‘upgrade’;
Uptime Kuma relies on WebSockets for real-time dashboard updates. Without these headers, parts of the interface may fail to load properly.
Enable HTTPS with Let’s Encrypt
After enabling the Nginx site, obtain a free SSL certificate using Certbot:
sudo certbot --nginx -d status.yourdomain.comOnce HTTPS is working, close direct public access to port 3001 and route all traffic through Nginx.
Keeping Uptime Kuma Updated
Updating Uptime Kuma is straightforward because the application data is stored in a persistent Docker volume.
a) Pull the Latest Image
docker pull louislam/uptime-kuma:1This downloads the latest image tagged with the major version.
b) Stop the Existing Container
docker stop uptime-kumaStops the currently running container.
c) Remove the Old Container
docker rm uptime-kumaRemoves the container while keeping the stored data intact.
d) Recreate the Container
Run the same deployment command used earlier:
docker run -d --restart=unless-stopped \
-p 3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:1Because all data is stored inside the uptime-kuma volume, your monitors, uptime history, notifications, and settings remain unchanged.
Conclusion
Uptime Kuma provides a powerful and cost-effective way to monitor websites, APIs, and services without relying on third-party monitoring platforms.
With Docker, you can deploy it in just a few minutes, create monitors, configure notifications, and track uptime from a clean web dashboard. For production use, place it behind Nginx with HTTPS and keep the Docker image updated regularly to maintain both security and reliability.
