How to Deploy Uptime Kuma with Docker on Ubuntu 24.04

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 :2 prevents 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 local data directory. 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.

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.

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.

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)

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.