DOCSEARCHbyAlgolia
Submit Docs

Uptime Kuma

repository·master·Indexed 13 days ago

https://github.com/louislam/uptime-kuma

A self-hosted monitoring tool for tracking the uptime of HTTP(s), TCP, DNS, and other services. It features a reactive UI, extensive notification support, and a Push API for status updates. Version 2.5.0 supports installation via Docker, Docker Compose, or direct Node.js deployment using PM2.

Tokens
10.9K
Snippets
39
Records
45
Agent score
100%

What's inside Uptime Kuma

  1. Rules for creating Knex migrations in Uptime Kuma

    master

    When writing database migrations for Uptime Kuma, follow these constraints to ensure compatibility across supported database engines (SQLite and MariaDB):

    1. Primary Keys: Every table must include a primary key named id.
    2. Filename Format: Use the pattern YYYY-MM-DD-HHMM-patch-name.js.
    3. Syntax: Do not use native SQL syntax. Use Knex methods exclusively to maintain cross-database compatibility.
    4. Transactions: By default, migrations run in a transaction. If you need to disable this, you can export a config object with transaction: false.

  3. Install Uptime Kuma without Docker (Non-Docker)

    master

    To run Uptime Kuma directly on your host machine, ensure you meet the requirements and follow the setup steps below.

    Requirements

    • Platforms: Major Linux distros (Debian, Ubuntu, Fedora, ArchLinux, etc.) or Windows 10/Server 2012 R2 (x64).
    • Node.js: version >= 20.4
    • Git: Required for cloning.
    • pm2: Recommended for running the process in the background.

    Setup Steps

    1. Clone the repository.
    2. Run the setup script.
    3. Choose between a temporary test run or a production-ready background process using PM2.
    git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# Option 1: Try it (Foreground)
node server/server.js

# Option 2: Run in background using PM2 (Recommended)
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma

  5. Install Uptime Kuma using Docker Compose

    master

    To install Uptime Kuma using Docker Compose, create a directory, download the official compose.yaml, and start the container. Uptime Kuma will be accessible on port 3001.

    Warning: Do not use file systems like NFS (Network File System) for data mapping; use a local directory or volume instead.

    mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

  6. Manage Uptime Kuma with PM2

    master

    If running in a non-Docker environment, use PM2 to manage the Uptime Kuma process. This allows you to monitor logs and ensure the service starts automatically on system boot.

    # View current console output/logs
pm2 monit

# Configure PM2 to start Uptime Kuma on system startup
pm2 startup && pm2 save

  7. Install Uptime Kuma using Docker CLI

    master

    You can run Uptime Kuma as a standalone Docker container. By default, it maps port 3001 and uses a Docker volume named uptime-kuma for data persistence.

    To limit exposure to localhost only, bind the port to 127.0.0.1.

    # Standard installation
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

# Limit exposure to localhost only
docker run ... -p 127.0.0.1:3001:3001 ...

  8. Run the TypeScript push example

    master

    To execute the TypeScript push example using fetch, you can use one of the following runtimes depending on your environment:

    • Node.js: Requires ts-node installed.
    • Deno: Requires the --allow-net flag to permit network requests.
    • Bun.js: Can run the file directly.
    # Using Node.js (with ts-node)
ts-node index.ts

# Using Deno
deno run --allow-net index.ts

# Using Bun.js
bun index.ts

  9. How to add a new language to the Uptime Kuma dropdown

    master

    To make a new language available in the Uptime Kuma UI dropdown, follow these steps:

    1. Add the language to Weblate: Go to the Weblate project and add your language.
    2. Identify the language code: Note the language code used in the URL (e.g., zh-TW).
    3. Update the source code: Edit src/i18n.js in the Uptime Kuma repository.
    4. Modify languageList: Append your language to the languageList array using the format: "CODE": "Language Name",.
    5. Submit: Commit your changes and open a Pull Request.

    If you are not comfortable editing code, you can request assistance via the GitHub issues section.

    // Example entry for src/i18n.js
"zh-TW": "繁體中文 (台灣)",

  10. Deploy Uptime Kuma using Docker Compose

    master

    You can deploy Uptime Kuma using a compose.yaml file. This configuration uses the louislam/uptime-kuma:2 image and persists data to a local directory.

    Configuration Details

    • Image: louislam/uptime-kuma:2
    • Persistence: The ./data directory on your host machine is mapped to /app/data inside the container. Ensure this directory exists or that the Docker daemon has permissions to create it to prevent data loss.
    • Port Mapping: The service exposes port 3001 on the host. You can change the host port by modifying the left side of the port mapping (e.g., "8080:3001").
    • Restart Policy: Set to unless-stopped to ensure the container restarts automatically unless manually stopped.
    services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"

  11. Example of a multi-table migration

    master

    This example demonstrates creating two tables (user and product) and inserting initial data into the product table using Knex schema builder methods. The down function ensures both tables are dropped during a rollback.

    // Filename: 2023-06-30-1348-create-user-and-product.js

exports.up = function (knex) {
  return knex.schema
    .createTable("user", function (table) {
      table.increments("id");
      table.string("first_name", 255).notNullable();
      table.string("last_name", 255).notNullable();
    })
    .createTable("product", function (table) {
      table.increments("id");
      table.decimal("price").notNullable();
      table.string("name", 1000).notNullable();
    })
    .then(() => {
      knex("products").insert([
        { price: 10, name: "Apple" },
        { price: 20, name: "Orange" },
      ]);
    });
};

exports.down = function (knex) {
  return knex.schema.dropTable("product").dropTable("user");
};

  12. Configure PM2 for Uptime Kuma

    master

    If you are running Uptime Kuma in the background using PM2 (the recommended non-Docker method), you can use an ecosystem.config.js file to manage the process. This file defines the application name and the entry point script required to start the server.

    module.exports = {
    apps: [
        {
            name: "uptime-kuma",
            script: "./server/server.js",
        },
    ],
};