--- title: "Uptime Kuma in Practice — Saving Money by Upgrading from SQLite to MariaDB and Enabling the RESTful API" description: "Commercial monitoring tools can cost tens of thousands per year. Self-hosting Uptime Kuma is free and works really well. This post walks through upgrading the database, enabling the API, and the gotchas I hit along the way." canonical_url: "https://blog.markkulab.net/en/post/uptime-kuma-mariadb-restful-api" author: "Mark Ku" author_url: "https://blog.markkulab.net/en/author/mark-ku" site: "Mark Ku's Tech Notes" date_published: "2025-07-29 10:00:00 +0800" category: "DevOps" tags: ["uptime kuma", "mariadb", "restful api", "docker", "monitoring", "devops"] language: "en" license: "CC BY 4.0" license_url: "https://creativecommons.org/licenses/by/4.0/" attribution: "when reusing or quoting, credit the author and link back to the original" --- # Uptime Kuma in Practice — Saving Money by Upgrading from SQLite to MariaDB and Enabling the RESTful API ## Intro: A Cheap, Practical Monitoring Setup This post documents my hands-on experience deploying Uptime Kuma, upgrading it to MariaDB, and integrating with the Uptime Kuma Admin API — so you can self-host with confidence and cut your monitoring costs. ## Why Choose Uptime Kuma (Cheap and Open Source) - Commercial monitoring software easily runs into tens of thousands per year - Uptime Kuma is fully open source, free, and feature-rich enough for most needs - Setup is dead simple — just run it with Docker - The community is active, so finding answers to issues is easy - Highly flexible — easy to customize and extend --- ## Uptime Kuma Architecture in Brief - **Backend**: Node.js + SQLite, using Sequelize ORM (you can also swap in MariaDB for better performance) - **Frontend**: A web UI built with Vue.js - **Communication**: WebSocket for real-time monitor status updates - **Highlights**: Self-hosting is trivial, lightweight, and very flexible — you can do whatever you want with it --- ## Performance Bottlenecks We Hit (Deep Dive) ### Early Performance Issues - The default SQLite database starts choking once you accumulate a lot of monitors (around 800 monitors) - Switching to MariaDB gave a clear performance boost and much better stability ### Challenges with Large-Scale Monitoring After digging into Uptime Kuma's source code, we found a few interesting things. We initially assumed the bottleneck was high-frequency I/O against SQLite, but in actual testing, even after upgrading to MariaDB, the admin UI still struggled to load once the monitor count exceeded 1,000 APIs. Reading through the code, we realized the bottleneck wasn't really the database layer. The frontend simply wasn't designed with large-scale monitoring in mind, so once you had a lot of monitors, frontend rendering and data handling became the actual bottleneck. ### Performance Tuning Suggestions If you need to monitor a large number of APIs, consider the following: - Group your monitors logically - Run multiple Uptime Kuma instances to spread the load - Periodically purge historical data to keep the database lean --- ## Why Do We Need an Uptime Kuma RESTful API? Sometimes you want to customize the public status page or programmatically add and manage monitors. That's where a RESTful API comes in handy. ### Choosing Active Monitoring When planning out our monitoring stack, we picked the open-source Uptime Kuma as our active monitoring solution. The catch is that Uptime Kuma doesn't expose a RESTful API out of the box, which limits your ability to automate things. I eventually found the open-source `medaziz11/uptimekuma_restapi` package, which solves this elegantly. Under the hood, it simulates a user logging in via WebSocket and wraps those operations as RESTful APIs. This design lets us automate monitor creation when we ship the second phase next year, which dramatically improves operational efficiency. --- ## How to Enable the RESTful API Uptime Kuma itself doesn't ship a RESTful API — only a web UI and WebSocket. But you can drop in the third-party `medaziz11/uptimekuma_restapi` container (already included in the docker-compose.yml above) and manage monitors over plain HTTP. ### How does this API package work? - It logs into the Uptime Kuma web admin using the credentials you provide - It "simulates user actions" via the internal WebSocket API and exposes those features as a RESTful API - You just send HTTP requests to this container (like the curl examples below) and it translates them into commands Uptime Kuma understands - You don't have to write WebSocket code yourself or reverse-engineer Uptime Kuma's internal API ### Implementation Details The clever part of this package is its "user simulation" approach. Specifically: 1. **WebSocket-based login**: The package uses your admin credentials to log into the Uptime Kuma backend over WebSocket 2. **API wrapping**: It wraps operations that would normally go over WebSocket into a clean RESTful API surface 3. **Automation-friendly**: This makes it easy to plug Uptime Kuma into existing automation pipelines It looks roundabout at first glance, but it's actually a really practical solution — especially when you need to integrate with existing systems. --- ## Docker Compose Example ```yaml services: kuma: image: louislam/uptime-kuma:2.0.0-beta.3 ports: - "3001:3001" environment: - UPTIME_KUMA_DB_TYPE=mariadb - UPTIME_KUMA_DB_HOSTNAME=mariadb - UPTIME_KUMA_DB_PORT=3306 - UPTIME_KUMA_DB_NAME=kuma - UPTIME_KUMA_DB_USERNAME=kuma - UPTIME_KUMA_DB_PASSWORD=G7p9x2Qw!s depends_on: mariadb: condition: service_healthy volumes: - uptime-kuma:/app/data mariadb: image: mariadb:10.11 environment: - MYSQL_ROOT_PASSWORD=R4t8z1Lm@v - MYSQL_DATABASE=kuma - MYSQL_USER=kuma - MYSQL_PASSWORD=G7p9x2Qw!s volumes: - mariadb-data:/var/lib/mysql ports: - "3307:3306" healthcheck: test: ["CMD", "mariadb-admin", "ping", "-h", "localhost", "-u", "root", "-pR4t8z1Lm@v"] timeout: 10s retries: 10 interval: 10s start_period: 30s api: image: medaziz11/uptimekuma_restapi environment: - KUMA_SERVER=http://kuma:3001 - KUMA_USERNAME=admin - KUMA_PASSWORD=G7p9x2Qw!s - ADMIN_PASSWORD=F5n3c7Vb$e depends_on: - kuma ports: - "8000:8000" volumes: - api:/db volumes: uptime-kuma: mariadb-data: api: ``` > Make sure the credentials match across docker-compose, otherwise the API service won't be able to connect properly! --- ## Most Useful RESTful API Calls ### 1. List All Monitors ```bash curl -X GET 'http://localhost:8000/api/monitors' -H 'Content-Type: application/json' ``` ### 2. Create a New Monitor ```bash curl -X POST 'http://localhost:8000/api/monitors' \ -H 'Content-Type: application/json' \ -d '{ "friendly_name": "My Site", "type": "http", "url": "https://example.com", "interval": 300 }' ``` ## Verify the Migration to MariaDB Worked ![verify db](https://blog.markkulab.net/content/markku/posts/uptime-kuma-mariadb-restful-api/images/verify-db.png) --- ## Conclusion Uptime Kuma is a real money-saver, easy to self-host, performs well after switching to MariaDB, and can be automated through the API. Highly recommended for anyone who wants to stay in control of their monitoring without paying a fortune. > Heads up: once you cross 1,000 monitors, the dashboard starts to lag. You may want to spread the load across multiple Uptime Kuma instances, or wait for the upstream project to improve large-scale performance in future releases. ### Roadmap Based on our hands-on experience and performance analysis, here's what we plan for phase two next year: 1. **Automated monitor creation**: Use the RESTful API to automate creating and managing monitors 2. **Performance tuning**: Look into a multi-instance architecture to handle large-scale monitoring needs 3. **Monitoring strategy refinement**: Adjust monitoring intervals and data retention based on real usage This gives us a stable, reliable monitoring service while keeping costs in check. --- ## About this article and its author Originally published on [Mark Ku's Tech Notes](https://blog.markkulab.net/en/post/uptime-kuma-mariadb-restful-api) License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — when reusing or quoting, credit the author and link back to the original ### About the author **[Mark Ku](https://blog.markkulab.net/en/author/mark-ku)** — Software Solution Provider - 10+ years senior software engineer, now an AI Builder - Focused on large-platform architecture — North-American e-commerce, AI SaaS subscription billing - Combining AI Agents and automation to build evolvable product foundations ### Free tools built by the author All of these are free to use: - [Free PDF Sign Tool](https://blog.markkulab.net/en/tools/pdf-sign): Online PDF sign tool — draw, type, or upload a signature, then drag, resize, and download. Everything runs in your browser; nothing is uploaded. - [VS Code Refactory](https://blog.markkulab.net/en/tools/refactory): Refactory is a VS Code refactoring extension: 34 actions plus a 37-rule code-smell inspection layer with a Code Health dashboard, across 18 languages, backed by 534 tests. It learns your repo's conventions: where interfaces live, where DI is registered, whether 'use client' belongs. It ranks files by git churn × complexity so you know what to fix first, and hands any smell to the Claude Code already on your machine. Free to use, and your source never leaves your computer. - [DB-Kit Database Manager](https://blog.markkulab.net/en/tools/db-kit): DB-Kit is a lightweight, cross-platform database manager built with Tauri + Rust + React. Manage MySQL, MariaDB, PostgreSQL, SQL Server, Oracle, SQLite, MongoDB, Redis, Kafka, Elasticsearch and RabbitMQ from one consistent interface: passwords encrypted in the OS keychain, SSH tunnels, full CRUD, a visual query builder, stacked multi-statement result sets, cross-connection data transfer and compare/sync, Excel / CSV import & export, visualized execution plans, ER diagrams, scheduled backups, SQL stress testing with p50–p99 latency percentiles, a 15-rule SQL review engine, Kafka message browsing with monitoring & alerts, a bilingual UI (Traditional Chinese / English), a built-in AI assistant (natural-language SQL, AI review and tuning advice) and the dbk CLI. Free and open source (MIT), with installers for Windows, macOS and Linux. - [VS Code Super Mermaid](https://blog.markkulab.net/en/tools/super-mermaid): Super Mermaid is a VS Code extension for beautiful Mermaid diagrams out of the box: auto-colored live preview, mouse pan & zoom, high-res PNG / SVG export, 21 templates and multiple themes. Free and open source (MIT). - [React Super Mermaid](https://blog.markkulab.net/en/tools/react-super-mermaid): react-super-mermaid is an open-source React component library: render beautiful Mermaid diagrams with a single , with built-in colorful / sketch themes, pan & zoom, in-diagram search, and high-res SVG / PNG export. Lightweight, SSR-safe, fully typed. Free and open source (MIT). - [Jira / Confluence Super Mermaid](https://blog.markkulab.net/en/tools/jira-super-mermaid): An Atlassian Forge app: write Mermaid syntax directly inside a Jira issue or a Confluence page and get flowcharts, sequence diagrams, state machines and Gantt charts. 11 diagram types, SVG / PNG export, light and dark themes, full CJK support. Runs on Atlassian: your diagrams live in your own site and the app calls no third-party service. Free, coming soon to the Atlassian Marketplace. - [Mermaid Live Preview](https://blog.markkulab.net/en/tools/mermaid-preview): Write Mermaid in your browser, see it render instantly, and share the whole diagram as a single link. No sign-up, nothing uploaded to a server, and mermaid.live share links work as-is. - [React Intl Phone Number](https://blog.markkulab.net/en/tools/react-intl-phone-number): react-intl-phone-number is an open-source React component: framework-agnostic and antd-free, with E.164 in/out, a searchable flag / country-code dropdown, configurable validation levels (strict / mobile-strict / loose), themeable CSS, and i18n — phone logic powered by google-libphonenumber. Lightweight and fully typed. Free and open source (MIT). - [Uptime Kuma Cluster](https://blog.markkulab.net/en/tools/uptime-kuma-cluster): Turn single-node Uptime Kuma into a highly available cluster: OpenResty + Lua smart load balancing, shared MariaDB state, health checks and automatic failover, plus cluster-management REST APIs. One Docker Compose command to start. Free and open source (MIT). - [Special Education](https://blog.markkulab.net/en/education): Learning materials crafted for special education students ### Daily podcasts - [Mark's Tech Insights — Daily AI News](https://blog.markkulab.net/en/category/tech-news): Daily curated AI and tech trends. Catch the latest developments via audio summaries — covering AI applications, software architecture, DevOps, and engineering practice. — RSS: https://blog.markkulab.net/feed.xml - [AI股市蝦聊](https://blog.markkulab.net/en/category/ai-stock-chat): Every trading day, an AI-analyzed take on the Taiwan stock market, delivered as a two-host conversation covering the session and the next-day outlook. — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml - [開源好物週報](https://blog.markkulab.net/en/category/open-source-weekly): A weekly two-host pick of free open-source tools surfaced from real Hacker News, GitHub, and Reddit buzz — what pain they solve and the fastest way to get started. — RSS: https://blog.markkulab.net/open-source-weekly/feed.xml ### Newsletter [Subscribe to the newsletter](https://blog.markkulab.net/en/subscribe) — Be the first to know about new posts. No spam, unsubscribe anytime.