How to Self-Host Uptime Kuma and Remote Access

Understand the architecture before exposing anything

Uptime Kuma periodically checks services and records their availability. Because it is self-hosted, you control the machine, application data, update schedule, and network path. You are also responsible for keeping the monitoring server available, protecting its administrator account, and maintaining recoverable backups.

The default web application listens on port 3001. In the Docker Compose configuration below, that port is published only on the host loopback address:

ports:
  - "127.0.0.1:3001:3001"

This prevents other computers from connecting directly to the host's LAN address on port 3001. It does not make the application universally secure. Other processes on the host can still reach it, and any reverse proxy or tunnel connected to 127.0.0.1:3001 can intentionally make it reachable elsewhere. Host firewall rules, account security, software updates, and access policy remain important.

A typical remote request follows this path: the browser connects to the assigned Localtonet public address, the Localtonet relay sends the request through the outbound connection maintained by the Localtonet client, and that client forwards it to Uptime Kuma at 127.0.0.1:3001. The tunnel is available only while the selected device is connected and the tunnel is running.

Prerequisites and deployment assumptions

This tutorial assumes an Ubuntu or Debian-family Linux host with a 64-bit operating system, a user that can run administrative commands, and local storage for Uptime Kuma data. Docker publishes multi-platform images, but compatibility depends on the architecture and operating system supported by the selected image. Check the current Uptime Kuma release notes before deploying on older or unusual hardware.

No universal CPU, memory, storage, or Raspberry Pi monitor-count guarantee is appropriate. Resource consumption depends on monitor types, check intervals, response sizes, retention, database size, notification activity, and other workloads on the host. A Raspberry Pi or another ARM64 computer can be suitable when its operating system and Docker installation are supported, but measure your own workload with docker stats rather than relying on a fixed benchmark.

Install Docker using a supported method

For a production host, follow Docker's supported repository installation process for your distribution rather than automatically piping a downloaded script into a privileged shell. The commands below show the Docker apt repository workflow for Debian-family systems. Confirm that your distribution is supported and review Docker's current instructions if package names or repository requirements have changed.

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

. /etc/os-release
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  ${UBUNTU_CODENAME:-$VERSION_CODENAME} stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world
sudo docker compose version

On Debian, use Docker's Debian repository instructions rather than substituting an Ubuntu repository. Other Linux distributions have different package commands. Docker also publishes a convenience script at get.docker.com, but Docker describes that route as convenient for development and testing scenarios. A script fetched from the network should be inspected before execution, and it is not a substitute for understanding the packages and repository changes being applied to a production server.

The remaining commands use sudo docker. You can grant a user access to the Docker group, but membership in that group effectively grants extensive control over the host. Treat it as privileged access rather than as a harmless convenience.

Install Uptime Kuma with Docker Compose

The project publishes versioned container images. This tutorial uses the v2 major tag shown in the current article scope. Before a new deployment or upgrade, compare the image tag with the current project documentation and release notes. Do not assume that a future major release is a drop-in replacement.

mkdir -p "$HOME/uptime-kuma/data"
cd "$HOME/uptime-kuma"

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: UTC

cd "$HOME/uptime-kuma"
sudo docker compose config
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 uptime-kuma

curl --fail --show-error --silent \
  --output /dev/null \
  http://127.0.0.1:3001/

echo "HTTP request succeeded"

ssh -L 3001:127.0.0.1:3001 your-user@your-server

cd "$HOME/uptime-kuma"
sudo docker compose restart uptime-kuma
sudo docker compose ps
curl --retry 12 --retry-delay 5 \
  --retry-connrefused \
  --fail --show-error --silent \
  --output /dev/null \
  http://127.0.0.1:3001/

The Uptime Kuma project maintains installation and release information in its official GitHub repository. Review the release notes before changing major versions. Database support, migration behavior, Node.js requirements for non-Docker installations, image variants, and removed features are version-specific and should not be inferred from an older tutorial.

Choose and configure monitors

Uptime Kuma offers multiple monitor types, and the available list can change between releases. The table below focuses on common workflows rather than claiming to enumerate every type. Always use the fields and help text shown by your installed version when configuring protocol-specific behavior.

Create a useful HTTP monitor

In the Uptime Kuma dashboard, choose the option to add a monitor, select the HTTP monitor type available in your version, enter the target URL, and configure an interval appropriate for the service. Use a URL that represents meaningful application health. For example, an authenticated application may provide a dedicated health endpoint, while a static website may need a keyword check to distinguish the expected page from a generic proxy error.

Test reachability from the same network context as Uptime Kuma. Remember that 127.0.0.1 inside the Uptime Kuma container refers to that container, not to the Docker host and not to another container. For services in the same Compose project, connect them to a shared Docker network and use their Compose service names. For a service on the host, use an address that is actually available from containers in your Docker configuration.

Configure a Push monitor

A Push monitor reverses the normal check direction. A job or service sends a request to the URL generated for that monitor. This works well for scheduled backups, batch imports, sensor collection, and systems that cannot accept an incoming active check.

#!/usr/bin/env bash
set -Eeuo pipefail

run_the_real_backup
curl --fail --show-error --silent \
  --retry 3 \
  "PASTE_THE_PUSH_URL_FROM_YOUR_OWN_MONITOR"

Configure Docker container monitoring deliberately

The basic Compose file does not give Uptime Kuma access to the Docker daemon. Consequently, installing it does not automatically enable Docker container monitoring. Uptime Kuma must be given a configured Docker host connection before it can inspect container state.

A commonly used local connection mounts the Docker Unix socket into the monitoring container and configures the corresponding Docker host in Uptime Kuma. However, access to /var/run/docker.sock can provide extensive control over the Docker host. A read-only filesystem mount flag does not reliably reduce the Docker API to harmless read operations. An application with daemon access may be able to start privileged containers, mount host paths, or otherwise affect the host.

Docker distinguishes a container's running state from its health state. A container without a Docker HEALTHCHECK can still be running, but it does not produce the same health result as one with a configured check. It is therefore too broad to say that every container without a health check remains in a starting state indefinitely. Confirm how the selected Uptime Kuma monitor evaluates your container, and use an application-level HTTP or TCP monitor when that gives a more meaningful result.

Set up and test notifications

Notification integrations vary by Uptime Kuma release and by provider. Start with one channel, use its Test function, attach it to a noncritical monitor, and deliberately trigger a failure and recovery. A successful configuration test does not always prove that real monitor events will be delivered, so test the full path.

Telegram bot notifications

SMTP and Gmail

For SMTP, enter the hostname, port, transport-security mode, username, password, sender, and recipient required by your email provider. Do not assume that port 465 and port 587 use interchangeable security settings. Port 465 commonly uses implicit TLS, while port 587 commonly begins with SMTP and upgrades using STARTTLS, but the provider's current documentation is authoritative.

Google accounts may offer App Passwords when the account meets Google's eligibility and security requirements, including applicable 2-Step Verification settings. Availability can also depend on account type, organization policy, and security configuration. If App Passwords are available, generate one through the Google Account App Passwords page and store it as a secret. Do not use or publish the normal Google account password. If the option is absent, consult the current Google account or Workspace policy rather than weakening account security.

Discord webhooks

For Discord, create an incoming webhook for the intended channel through the server's current integration settings, copy its URL, and paste it into Uptime Kuma's Discord notification form. Menu labels and permissions can change, and the user creating the webhook needs suitable server permissions. Treat the webhook URL as a credential because anyone possessing it may be able to post to the channel. Send a test, then remove the test message if appropriate.

Create a status page without oversharing

A status page presents selected monitor information to viewers without giving them monitor-editing access. It can be useful for customers, household members, or an internal operations team. The fact that a status page is intended to be public does not mean every monitor name, tag, hostname, incident message, or response detail is safe to publish.

Publish Uptime Kuma through Localtonet

With Localtonet, the client on the Uptime Kuma host establishes an outbound connection to one of our relay servers. You do not need inbound router port forwarding, firewall changes, VPN setup, or a public IP address for this tunnel workflow. The result is a public HTTPS address that forwards to the local Uptime Kuma service.

Use remote access for a specific reason:

• Administrators need to reach the dashboard from outside the local network.
• Approved viewers need a public status page.
• A Push monitor sender needs a reachable heartbeat endpoint and no private route exists.

A single Uptime Kuma origin can serve all three, but their security requirements differ. Publishing only a status-page URL does not necessarily make the rest of the origin unreachable. If the public-status and private-administration requirements cannot coexist safely on one origin, use an additional access-control architecture rather than relying on obscurity.

Configure Push URLs after remote access is working

If a Push sender needs the Localtonet route, configure Uptime Kuma's public or primary base URL field only if that field exists in your installed version and is required for generated links. Enter the exact HTTPS address assigned by the dashboard. Then copy the Push URL again from Uptime Kuma and test it from the sender's network.

The Push URL itself should be treated like a secret. A person who obtains it may be able to submit false heartbeats or status information for that monitor. Do not place it in public source code. If it leaks, replace the monitor or otherwise rotate the generated endpoint using the controls supported by your version.

Back up and restore the complete data directory

A reliable backup procedure must stop on errors, preserve ownership and permissions, avoid deleting unrelated files, restart the service after a failed copy, and be tested through an actual restore. Back up the complete persistent data directory rather than selecting only one database file.

The following script briefly stops Uptime Kuma and archives the complete data directory. It writes the archive to a temporary filename and renames it only after successful completion, so an interrupted run does not look like a valid backup.

#!/usr/bin/env bash
set -Eeuo pipefail
umask 077

PROJECT_DIR="${HOME}/uptime-kuma"
BACKUP_ROOT="${HOME}/uptime-kuma-backups"
STAMP="$(date -u +%Y-%m-%dT%H%M%SZ)"
FINAL="${BACKUP_ROOT}/uptime-kuma-${STAMP}.tar.gz"
TEMP="${FINAL}.partial"
SERVICE_STOPPED=0

restart_if_needed() {
  if [[ "${SERVICE_STOPPED}" -eq 1 ]]; then
    cd "${PROJECT_DIR}"
    sudo docker compose start uptime-kuma
  fi
  rm -f "${TEMP}"
}
trap restart_if_needed EXIT

mkdir -p "${BACKUP_ROOT}"
cd "${PROJECT_DIR}"

sudo docker compose stop uptime-kuma
SERVICE_STOPPED=1

sudo tar \
  --numeric-owner \
  --xattrs \
  --acls \
  -czf "${TEMP}" \
  data compose.yaml

sudo chown "$(id -u):$(id -g)" "${TEMP}"
mv "${TEMP}" "${FINAL}"

sudo docker compose start uptime-kuma
SERVICE_STOPPED=0

curl --retry 12 \
  --retry-delay 5 \
  --retry-connrefused \
  --fail --show-error --silent \
  --output /dev/null \
  http://127.0.0.1:3001/

find "${BACKUP_ROOT}" \
  -maxdepth 1 \
  -type f \
  -name 'uptime-kuma-*.tar.gz' \
  -mtime +14 \
  -print \
  -delete

printf 'Verified backup created: %s\n' "${FINAL}"

Save the script as $HOME/uptime-kuma/backup.sh, review every path, make it executable, and run it manually:

chmod 700 "$HOME/uptime-kuma/backup.sh"
"$HOME/uptime-kuma/backup.sh"
tar -tzf "$HOME"/uptime-kuma-backups/uptime-kuma-*.tar.gz | head

Perform a tested restore with rollback

Test the following process on a nonproduction host first. Use a backup created from a compatible Uptime Kuma version. Keep the current data directory until the restored application passes verification.

#!/usr/bin/env bash
set -Eeuo pipefail

PROJECT_DIR="${HOME}/uptime-kuma"
ARCHIVE="${1:?Usage: restore.sh /path/to/uptime-kuma-backup.tar.gz}"
ROLLBACK="${PROJECT_DIR}/data.before-restore.$(date -u +%Y%m%dT%H%M%SZ)"

test -r "${ARCHIVE}"
tar -tzf "${ARCHIVE}" > /dev/null

cd "${PROJECT_DIR}"
sudo docker compose down

test -d data
sudo mv data "${ROLLBACK}"

if ! sudo tar \
  --numeric-owner \
  --xattrs \
  --acls \
  -xzf "${ARCHIVE}" \
  -C "${PROJECT_DIR}"; then
  sudo rm -rf "${PROJECT_DIR}/data"
  sudo mv "${ROLLBACK}" "${PROJECT_DIR}/data"
  sudo docker compose up -d
  exit 1
fi

sudo docker compose up -d

if ! curl --retry 12 \
  --retry-delay 5 \
  --retry-connrefused \
  --fail --show-error --silent \
  --output /dev/null \
  http://127.0.0.1:3001/; then
  sudo docker compose down
  sudo rm -rf "${PROJECT_DIR}/data"
  sudo mv "${ROLLBACK}" "${PROJECT_DIR}/data"
  sudo docker compose up -d
  exit 1
fi

printf 'HTTP verification passed. Keep rollback data until manual checks pass: %s\n' \
  "${ROLLBACK}"

After the HTTP check passes, log in and verify the administrator account, monitor list, status pages, notification configurations, recent history, and a test alert. Trigger one Push monitor from a test sender. Only remove the rollback directory after these manual checks pass and after another valid backup exists.

Update, verify, and roll back safely

No update should be described as categorically safe. Patch and minor releases can contain migrations, changed defaults, regressions, or integration changes. Major upgrades require particular care. Read the official release notes, verify compatibility, take a tested backup, and schedule enough time to observe startup and application behavior.

cd "$HOME/uptime-kuma"
sudo docker compose ps
sudo docker inspect uptime-kuma \
  --format '{{.Config.Image}} {{.Image}}'
sudo docker compose logs --tail=100 uptime-kuma

"$HOME/uptime-kuma/backup.sh"

cd "$HOME/uptime-kuma"
sudo docker compose pull uptime-kuma
sudo docker compose up -d uptime-kuma
sudo docker compose logs -f uptime-kuma

curl --fail --show-error --silent \
  --output /dev/null \
  http://127.0.0.1:3001/

sudo docker compose ps
sudo docker compose logs --tail=200 uptime-kuma

If verification fails, preserve the failed logs and data before attempting recovery. Rollback may require restoring both the previous container image and the pre-update data directory because a database migration can make new data incompatible with an older image. Do not repeatedly start different versions against the same only copy of the data.

Routine operational checks

• Review container state and recent logs after host reboots.
• Watch disk capacity and the growth of the persistent data directory.
• Run backups on a schedule and inspect failed-job notifications.
• Perform periodic restores on another host rather than assuming archives are usable.
• Review administrator access, notification secrets, Push URLs, and Localtonet device tokens.
• Stop unused tunnels and delete obsolete configurations.
• Confirm that the public status page still contains only approved monitor information.
• Monitor Uptime Kuma itself from an independent system when missed alerts would be consequential.

Troubleshooting common failures

Frequently asked questions