Uptime Kuma is a sleek and powerful uptime monitoring tool designed for self-hosters. In this guide, I’ll show you how to deploy Uptime Kuma using Docker and Docker Compose.

Prerequisites

Before diving in, ensure you have the following:

  1. Docker and Docker Compose installed on your system.
  2. Familiarity with creating and editing files in a terminal.
  3. A reverse proxy (e.g., Traefik or Nginx Proxy Manager) if you plan to make the service available externally.

Docker Compose Configuration

Here’s the docker-compose.yml file you can use to deploy Uptime Kuma:

---
services:
  status:
    image: louislam/uptime-kuma:latest
    restart: always
    depends_on:
      db:
        condition: service_healthy
      mail:
        condition: service_started    
    ports:
      - '3001:3001'
    environment:
      - 'UPTIME_KUMA_DB_TYPE=mariadb'
      - 'UPTIME_KUMA_DB_HOSTNAME=db'
      - 'UPTIME_KUMA_DB_PORT=3306'
      - 'UPTIME_KUMA_DB_NAME=${MARIADB_DATABASE}'
      - 'UPTIME_KUMA_DB_USERNAME=${MARIADB_USER}'
      - 'UPTIME_KUMA_DB_PASSWORD=${MARIADB_PASSWORD}'
    networks:
      - status      
    volumes:
      - uk-data:/app/data
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  db:
    image: mariadb:11.6
    restart: always
    environment:
      - MARIADB_DATABASE
      - MARIADB_PASSWORD
      - MARIADB_ROOT_PASSWORD
      - MARIADB_USER
      - MARIADB_AUTO_UPGRADE
    networks:
      - status
    volumes:
      - db-data:/var/lib/mysql
      - db-backup:/backup
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3      
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"    

  mail:
    image: bytemark/smtp:latest
    restart: always
    networks:
      - status
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  uk-data:
  db-data:
  db-backup:

networks:
  status:

Setting Up Environment Variables

Create a .env file in the same directory as your docker-compose.yml file with the following variables:

MARIADB_DATABASE=status
MARIADB_USER=status
MARIADB_PASSWORD=<your-generated-password>
MARIADB_ROOT_PASSWORD=<your-generated-password>
MARIADB_AUTO_UPGRADE=true

Replace <your-generated-password> with secure values. You can use openssl rand -hex 32 to generate random passwords.

Deploying the Stack

Run the following command to start the services:

docker compose up -d

The first time you run this command, you may encounter an error like this:

Started
Container status-db-1  Waiting
Container status-db-1  Error
dependency failed to start: container status-db-1 is unhealthy

This usually happens because the health check timeout for MariaDB is too short on the first deployment. Simply run the command again:

docker compose up -d

This second attempt should bring the stack up successfully.

Accessing Uptime Kuma

Navigate to http://<your-server-ip>:3001 in your browser. The first time you visit, you’ll be prompted to create an admin account.

Optional: Reverse Proxy Setup

For external access, it’s best to place Uptime Kuma behind a reverse proxy. While this guide doesn’t cover reverse proxy setup in detail, I recommend using Traefik if you’re still deciding on a solution.

Conclusion

Congratulations! You’ve successfully deployed Uptime Kuma. This lightweight yet powerful tool is now ready to help you monitor the uptime of your services. If you have any questions or run into issues, feel free to share your experiences in the comments section below.