Introduction
Uptime Kuma is a self-hosted, open-source monitoring tool that tracks the availability of your websites, APIs, and services in real time. By deploying Uptime Kuma on your Raff VM, you get a private monitoring dashboard with unlimited monitors, customizable alerts, and public status pages — without paying per-monitor fees to third-party services.
Uptime Kuma supports over 20 monitor types including HTTP(S), TCP, Ping, DNS, Docker container health, and push-based monitors for cron jobs. It sends alerts through 90+ notification providers such as email, Slack, Telegram, Discord, and webhooks. Version 2.0 introduced MariaDB support, rootless Docker images, and a refreshed UI, while version 2.1 added domain expiry monitoring and Globalping integration for worldwide probes.
In this tutorial, you will deploy Uptime Kuma using Docker Compose with persistent data storage, configure the UFW firewall, create your admin account, add your first monitor, and set up notification alerts. Docker is required as a prerequisite — if you have not installed it yet, follow our tutorial on How to Install Docker on Ubuntu 24.04 first.
Step 1 — Create the Project Directory
Organize your Uptime Kuma deployment in a dedicated directory. This keeps the Docker Compose file and persistent data in one location for easy management and backups.
Create the directory structure:
bashmkdir -p ~/uptime-kuma/data
cd ~/uptime-kuma
The data subdirectory will store Uptime Kuma's SQLite database, which contains all your monitor configurations, alert settings, and uptime history.
Step 2 — Create the Docker Compose File
Docker Compose lets you define and manage the Uptime Kuma container with a simple configuration file. This approach is more maintainable than a raw docker run command and makes updates straightforward.
Create the Compose file:
bashnano docker-compose.yml
Add the following configuration:
yamlservices:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: always
ports:
- "3001:3001"
volumes:
- ./data:/app/data
environment:
- TZ=UTC
Save and close the file.
Here is what each setting does:
image: louislam/uptime-kuma:2— Uses the official Uptime Kuma v2 image. Pinning to:2prevents unexpected breaking changes when v3 releases.restart: always— Automatically restarts the container after server reboots or crashes.ports: "3001:3001"— Maps port 3001 on the host to port 3001 in the container, where Uptime Kuma's web interface runs.volumes: ./data:/app/data— Persists the SQLite database and configuration to the localdatadirectory. Without this, all data would be lost when the container is recreated.TZ=UTC— Sets the timezone for accurate monitoring timestamps. Change to your local timezone (e.g.,America/New_York,Europe/London) if preferred.
Warning
Uptime Kuma's SQLite database requires POSIX file lock support. Do not mount the data directory on an NFS share, as this can cause database corruption.
Step 3 — Start Uptime Kuma
Launch the container in detached mode:
bashdocker compose up -d
Docker will pull the Uptime Kuma image (approximately 200 MB) and start the container. This takes about 30-60 seconds on the first run.
Verify the container is running:
bashdocker compose ps
Expected output:
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
uptime-kuma louislam/uptime-kuma:2 "/usr/bin/dumb-init …" uptime-kuma 30 seconds ago Up 29 seconds 0.0.0.0:3001->3001/tcp
You can also check the container logs for any startup errors:
bashdocker compose logs -f
Look for the line Listening on 3001 to confirm Uptime Kuma is ready. Press Ctrl+C to exit the log view.
Step 4 — Configure the Firewall
If UFW is enabled on your server, allow traffic on port 3001 so you can access the Uptime Kuma web interface:
bashsudo ufw allow 3001/tcp
sudo ufw reload
Verify the rule was added:
bashsudo ufw status
You should see port 3001 listed as ALLOW.
Tip
For production deployments, a more secure approach is to place Nginx in front of Uptime Kuma as a reverse proxy with SSL, then only expose ports 80 and 443. In that case, you would change the port mapping to "127.0.0.1:3001:3001" so Uptime Kuma only accepts connections from the local machine.
Step 5 — Create Your Admin Account
Open a web browser and navigate to:
http://your_server_ip:3001
Replace your_server_ip with your Raff VM's public IP address.
On the first visit, Uptime Kuma presents the account creation page. Fill in the following:
- Language: Select your preferred language
- Username: Choose an admin username
- Password: Set a strong password (minimum 6 characters, use a mix of letters, numbers, and symbols)
Click Create to set up your account and enter the dashboard.
Warning
There is no email-based password recovery for Uptime Kuma. If you lose your admin password, you will need to reset it by modifying the SQLite database directly. Store your credentials securely.
Step 6 — Add Your First Monitor
From the Uptime Kuma dashboard, click Add New Monitor to start tracking a service.
Configure the monitor with these settings:
- Monitor Type: Select the appropriate type. For a website, choose HTTP(s).
- Friendly Name: A descriptive label (e.g., "Company Website")
- URL: The full URL to monitor (e.g.,
https://example.com) - Heartbeat Interval: How often to check, in seconds. The default is 60 seconds (1 minute). Set to 30 for more frequent checks.
- Retries: Number of failed checks before triggering an alert. Set to 3 to avoid false positives from transient network issues.
Click Save at the bottom of the page. Uptime Kuma will immediately begin monitoring and display the response time, status, and uptime percentage on the dashboard.
Other useful monitor types include:
- TCP Port — Check if a specific port is open (useful for database servers, SSH)
- Ping — ICMP ping to verify network reachability
- DNS — Verify that DNS records resolve correctly
- Docker Container — Check if a Docker container is running (requires mounting the Docker socket)
- Push — Your service sends heartbeats to Uptime Kuma (ideal for cron jobs and batch processes)
Step 7 — Set Up Notification Alerts
Monitoring is only useful if you are alerted when something goes down. Configure at least one notification channel.
Click on your profile icon in the top-right corner and select Settings, then navigate to the Notifications tab.
Click Setup Notification and choose a provider. Here are the most common options:
Email (SMTP):
- Notification Type: SMTP
- SMTP Host: Your email provider's SMTP server (e.g.,
smtp.gmail.com) - SMTP Port: 587 (for TLS) or 465 (for SSL)
- Username: Your email address
- Password: Your email password or app-specific password
- From Email: The sender address
- To Email: Where alerts should be delivered
Telegram:
- Notification Type: Telegram
- Bot Token: Create a bot via @BotFather on Telegram and paste the token
- Chat ID: Your Telegram user ID or group chat ID
Slack / Discord:
- Notification Type: Slack Incoming Webhook or Discord
- Webhook URL: The webhook URL from your Slack or Discord channel settings
After configuring a notification, click Test to send a test alert and confirm delivery. Then click Save.
To apply a notification to an existing monitor, edit the monitor and check the notification channel under the Notifications section at the bottom.
Step 8 — Update and Back Up Uptime Kuma
Keeping Uptime Kuma updated ensures you have the latest features and security fixes. The Docker-based deployment makes updates simple.
To update to the latest version:
bashcd ~/uptime-kuma
docker compose pull
docker compose up -d
This pulls the newest image tagged as :2 and recreates the container. Your data persists in the ./data directory and is not affected.
To back up your Uptime Kuma data, copy the data directory to a safe location:
bashcp -r ~/uptime-kuma/data ~/uptime-kuma-backup-$(date +%Y%m%d)
Tip
Schedule regular backups of the data directory using a cron job. You can also use Raff's automated VM snapshot feature for full server-level backups that include the entire Docker environment.
To check the running Uptime Kuma version, log into the web interface, click your profile icon, and select Settings > About.
Conclusion
You have deployed Uptime Kuma on your Raff Ubuntu 24.04 VM using Docker Compose, configured firewall access, created your admin account, set up your first monitor, and configured notification alerts. Your self-hosted monitoring dashboard is now tracking the availability of your services.
From here, you can:
- Add monitors for all your websites, APIs, databases, and internal services
- Create a public status page to share uptime information with your users or clients
- Set up an Nginx reverse proxy with Let's Encrypt SSL for secure HTTPS access
- Mount the Docker socket to monitor the health of other containers on the same server
- Configure multiple notification channels for redundant alerting
Uptime Kuma is lightweight and runs comfortably on Raff's smallest VM tier ($3.99/month for 1 vCPU, 1 GB RAM) alongside other Docker containers, making it an affordable addition to any infrastructure monitoring setup.