How to Self-Host Uptime Kuma and Remote Access

What Is Uptime Kuma?

Uptime Kuma is an open-source, self-hosted monitoring tool created by Louis Lam and first released in 2021. It is designed as a self-hosted alternative to cloud monitoring services like UptimeRobot, Pingdom, and Better Uptime. Built with Vue 3 on the frontend and Node.js on the backend, it communicates over WebSocket for real-time status updates in the browser without page refreshes.

The core function is simple: Uptime Kuma periodically checks whether your services are up and sends you an alert when something goes down or comes back up. But the breadth of what it can monitor, and the number of ways it can notify you, make it significantly more capable than most cloud alternatives.

Uptime Kuma v1 vs v2: What Changed

Uptime Kuma v2.0 was released in October 2025 and is a major version update with breaking changes. If you are running v1 and considering upgrading, read this section carefully before proceeding.

Requirements

Installation: Docker Compose

Step 1: Install Docker

sudo apt update
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# Log out and back in, then verify:
docker --version
docker compose version

Expected output:

Docker version 27.x.x, build xxxxxxx
Docker Compose version v2.x.x

Step 2: Create the project directory and docker-compose.yml

mkdir ~/uptime-kuma && cd ~/uptime-kuma

cat > docker-compose.yml << 'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Europe/Istanbul
EOF

The port binding 127.0.0.1:3001:3001 makes Uptime Kuma only accessible from the local machine. Access from other devices and networks goes through the Localtonet tunnel (covered below), which is more secure than binding to all interfaces.

Step 3: Start Uptime Kuma

docker compose up -d

# Check status:
docker compose ps

Expected output:

NAME           IMAGE                    STATUS
uptime-kuma    louislam/uptime-kuma:2   Up 30 seconds

# Watch startup logs:
docker compose logs -f uptime-kuma

Expected startup log:

Welcome to Uptime Kuma
Uptime Kuma Version: 2.x.x
Listening on 0.0.0.0:3001

Step 4: Create the admin account

Open http://localhost:3001 in your browser. You are prompted to create the first admin account with a username and password. This account has full access to all monitors, settings, and the admin panel. Use a strong password.

Monitor Types: A Complete Reference

Uptime Kuma supports many monitor types. Choosing the right type for each service is important: the wrong type can produce false positives (alerts for services that are actually up) or miss real outages.

The Push Monitor: Monitoring Services Behind NAT and CGNAT

The Push monitor is arguably the most powerful and underused monitor type. Most monitors are active: Uptime Kuma reaches out to your service. The Push monitor is passive: your service reaches out to Uptime Kuma.

This matters enormously for home server operators. If your services are behind CGNAT, Uptime Kuma cannot reach them for active checks because they have no public IP. The Push monitor inverts the relationship: your internal service sends an outbound HTTP request to the Uptime Kuma public URL. Outbound connections always work behind NAT and CGNAT.

Setting up a Push monitor

# Cron job example: call push URL every 5 minutes:
# Add to crontab with: crontab -e
*/5 * * * * curl -fsS "https://yourpublicdomain/api/push/abcd1234?status=up&msg=OK" > /dev/null

# For a backup script, call at the end of a successful run:
# Only send heartbeat if the backup succeeded
backup_my_files && curl -fsS "https://yourpublicdomain/api/push/abcd1234?status=up&msg=backup_ok"

Setting Up Notifications

Uptime Kuma supports over 90 notification providers. Notifications are configured once and then assigned to one or more monitors. When a monitor changes status (down or recovered), all assigned notifications fire.

To add a notification, go to Settings → Notifications → Add Notification.

Creating a Public Status Page

Uptime Kuma's status page feature lets you create a public-facing page that shows the current status and uptime history of selected services. This is the same concept as status.github.com or status.stripe.com, but self-hosted and fully under your control.

Installation on Raspberry Pi

Uptime Kuma is an excellent fit for a Raspberry Pi. The resource usage is low enough that it runs on a Pi 3 or Pi Zero 2W alongside other services. The Docker Compose setup above works on Raspberry Pi OS 64-bit (Bookworm) without any changes.

# Install Docker on Raspberry Pi OS:
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker pi
# Log out and back in

# Create the project and compose file exactly as above:
mkdir ~/uptime-kuma && cd ~/uptime-kuma
# Create docker-compose.yml with louislam/uptime-kuma:2 image
docker compose up -d

# Check RAM usage after startup (Pi 4, ~25 monitors):
docker stats uptime-kuma --no-stream

Expected output (Pi 4, 25 monitors):

NAME          CPU %   MEM USAGE / LIMIT   MEM %
uptime-kuma   0.10%   152MiB / 3.7GiB     4.1%

Remote Access: Dashboard and Status Page via Localtonet

There are two reasons to expose Uptime Kuma publicly with Localtonet:

• Access the dashboard from anywhere: Check monitor status and manage your setup from your phone, laptop, or any device outside your home network without VPN.
• Make the status page public: Share the status page URL with users, team members, or clients so they can see service status without any login. Push monitors also require a public URL so that your internal services can send heartbeats to Uptime Kuma.

curl -fsSL https://localtonet.com/install.sh | sh
localtonet --version

localtonet --authtoken YOUR_TOKEN_HERE

Primary Base URL: https://mystatus.localto.net

sudo localtonet --install-service --authtoken YOUR_TOKEN_HERE
sudo localtonet --start-service --authtoken YOUR_TOKEN_HERE

Backing Up Uptime Kuma

All Uptime Kuma data lives in the /app/data directory inside the container, mounted to ./data on the host. A complete backup copies this entire directory.

#!/bin/bash
# Save as ~/uptime-kuma/backup.sh
# Add to cron: 0 2 * * * ~/uptime-kuma/backup.sh

BACKUP_DIR=~/uptime-kuma-backups/$(date +%F_%H%M)
mkdir -p "$BACKUP_DIR"

# Uptime Kuma can be backed up while running because SQLite WAL mode
# handles concurrent reads, but a brief stop gives a cleaner backup:
cd ~/uptime-kuma
docker compose stop uptime-kuma

# Copy the entire data directory:
rsync -a ./data/ "$BACKUP_DIR/data/"

# Restart:
docker compose start uptime-kuma

echo "Backup complete: $BACKUP_DIR"

# Keep only last 14 days:
find ~/uptime-kuma-backups -maxdepth 1 -type d -mtime +14 -exec rm -rf {} +

chmod +x ~/uptime-kuma/backup.sh
# Test it:
~/uptime-kuma/backup.sh

Restore from backup

# Stop Uptime Kuma:
cd ~/uptime-kuma
docker compose down

# Replace the data directory with the backup:
rm -rf ./data
cp -r ~/uptime-kuma-backups/YYYY-MM-DD_HHMM/data ./data

# Start:
docker compose up -d

Updating Uptime Kuma

Uptime Kuma releases updates frequently. Minor version updates (2.x to 2.y) are safe to apply directly. For the v1 to v2 major upgrade, see the migration warning at the top of this guide.

cd ~/uptime-kuma

# Back up before updating:
~/uptime-kuma/backup.sh

# Pull the latest v2 image:
docker compose pull uptime-kuma

# Restart with the new image:
docker compose up -d uptime-kuma

# Watch logs to confirm successful start (and any migration progress):
docker compose logs -f uptime-kuma

Expected log after a clean update:

Welcome to Uptime Kuma
Uptime Kuma Version: 2.x.y
Listening on 0.0.0.0:3001

Resetting the Admin Password via CLI

If you forget the admin password, Uptime Kuma provides a CLI tool to reset it without losing any data:

# Docker Compose:
docker exec -it uptime-kuma npm run reset-password

You will be prompted to enter a new password. The tool modifies the database directly. Restart Uptime Kuma after resetting:

docker compose restart uptime-kuma

Troubleshooting

Frequently Asked Questions