How to Deploy Uptime Kuma - Self-Hosted Status Page and Monitoring Tool

Uptime Kuma is a self-hosted monitoring tool that tracks the availability of websites, APIs, TCP ports, DNS records, and other services. It provides a clean dashboard to display uptime metrics and trigger alerts through 90+ notification services, including email, Slack, and Telegram, when a service goes down or recovers.

This article explains how to deploy Uptime Kuma on a Linux server using Docker Compose behind a Traefik reverse proxy.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure a domain A record, such as kuma.example.com, pointing to your server's public IP address.
• Add your user to the docker group to run Docker commands without sudo, then start a new shell session to apply the change.

Set Up the Directory Structure and Environment Variables

The project directory holds the Docker Compose file, the persistent data directory, and the environment variables shared between the Traefik and Uptime Kuma containers.

1. Create the project directory.

   CONSOLE

   Copy

   $ mkdir ~/uptime-kuma

   Explain Code

   Powered by Vultr AgentBeta

2. Enter the project directory.

   CONSOLE

   Copy

   $ cd ~/uptime-kuma

   Explain Code

   Powered by Vultr AgentBeta

3. Create the persistent data directory for Uptime Kuma.

   CONSOLE

   Copy

   $ mkdir -p data

   Explain Code

   Powered by Vultr AgentBeta

4. Create the environment variable file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

5. Add the following variables to the file.

   INI

   Copy

   DOMAIN=kuma.example.com
   LETSENCRYPT_EMAIL=admin@example.com

   Explain Code

   Powered by Vultr AgentBeta

   Replace the following placeholders:

   • kuma.example.com: Your registered domain name pointing to the server's IP address.
   • admin@example.com: Your email address for Let's Encrypt certificate notifications.

   Save and close the file.

Deploy with Docker Compose

Traefik and Uptime Kuma run as separate containers on a shared Docker network. Traefik terminates TLS on the configured domain and forwards requests to Uptime Kuma's internal port, keeping Uptime Kuma off the public internet entirely.

1. Create the Docker Compose file.

   CONSOLE

   Copy

   $ nano docker-compose.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following configuration.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.7.11
       container_name: traefik
       restart: unless-stopped
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.le.acme.httpchallenge=true"
         - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./letsencrypt:/letsencrypt
       networks:
         - kuma-net
   
     uptime-kuma:
       image: louislam/uptime-kuma:2.5.3
       container_name: uptime-kuma
       restart: unless-stopped
       volumes:
         - ./data:/app/data
       networks:
         - kuma-net
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.kuma.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.kuma.entrypoints=websecure"
         - "traefik.http.routers.kuma.tls=true"
         - "traefik.http.routers.kuma.tls.certresolver=le"
         - "traefik.http.services.kuma.loadbalancer.server.port=3001"
   
   networks:
     kuma-net:
       driver: bridge

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   In the above configuration:

   • traefik: The reverse proxy that listens on ports 80 and 443, redirects all HTTP traffic to HTTPS, and automatically provisions TLS certificates from Let's Encrypt using the HTTP challenge method.
   • uptime-kuma: The monitoring service that stores data in the ./data directory. The Traefik labels configure domain routing, enable HTTPS, and forward traffic to the Uptime Kuma application on port 3001.
   • kuma-net: A shared bridge network that allows Traefik and Uptime Kuma to communicate internally without exposing internal ports to the host.

3. Start all services in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that all containers are running.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   The output displays two running containers: Traefik and Uptime Kuma.

Configure Uptime Kuma

Uptime Kuma does not report any status information until you create an administrator account and configure at least one monitor.

1. Open a web browser and navigate to the domain configured in the .env file.

   https://kuma.example.com

2. On the database setup page, select SQLite, then click Next. SQLite requires no extra configuration and works with the single-container deployment in this guide. The MariaDB/MySQL option connects to a separate database server that this deployment does not provision.

3. The account creation page appears. Enter a username, enter a strong password in both the Password and Repeat Password fields, then click Create.

4. After you create the account, the Uptime Kuma dashboard opens. Click + Add New Monitor.

   

5. Configure the monitor settings:

   • Monitor Type: Select the type of service to monitor. Choose HTTP(s) for websites and APIs, TCP Port for port-based services, or DNS for domain records.
   • Friendly Name: Enter a descriptive name for the monitor (for example, My Website).
   • URL: Enter the full URL of the service to monitor (for example, https://example.com).
   • Heartbeat Interval: Set the polling frequency in seconds. The default is 60.

6. Click Save to activate the monitor. The dashboard adds the monitor with an Unknown status. The status updates to Up or Down after the first heartbeat check runs within 60 seconds.

Configure Alert Notifications

Uptime Kuma does not send alerts by default. You must configure a notification channel and assign it to individual monitors before it triggers on a status change.

1. Click the profile avatar in the top-right corner and select Settings.

2. Navigate to the Notifications tab and click Set Up Notification.

3. Select a notification type from the dropdown. Supported channels include email (SMTP), Slack, Telegram, Discord, and PagerDuty, among others.

4. Enter the required credentials or webhook URL of the selected notification channel.

5. Click Test to send a test notification and verify the configuration is working.

6. Click Save to confirm the notification setup.

7. Open the settings for each monitor that should use this notification channel, select the notification from the Notifications list, and click Save.

Create a Status Page

A status page groups one or more monitors into a public view, separate from the administrator dashboard, so you can share it with users or team members without granting them access to the full Uptime Kuma interface.

1. Click Status Pages in the top navigation bar.

2. Click New Status Page.

3. Enter a Name for the status page (for example, Service Status), then enter a Slug using only lowercase letters, numbers, and hyphens (for example, status creates the URL https://kuma.example.com/status/status). Click Next.

4. The status page editor opens. The Title field is pre-filled with the name entered in the previous step. Add a Description if needed, then configure the remaining display settings as needed.

5. Click Add Group to create a section, then use the Add a monitor dropdown to select a monitor and add it to the group.

6. Click Save to publish the status page.

7. Open the status page URL in a browser to verify it loads and displays the monitor statuses.

   https://kuma.example.com/status/status

   Replace the path with the slug configured in step 3.

Conclusion

You have deployed Uptime Kuma on a Linux server using Docker Compose with Traefik providing TLS termination, and configured a monitor, a notification channel, and a public status page. For more information, see the Uptime Kuma documentation.