Uptime Kotlin is another useful entry in the current wave of self-hosted monitoring tools.
Uptime Kotlin is a self-hosted uptime monitoring platform built with Kotlin, Quarkus, React, and PostgreSQL. It monitors HTTP/HTTPS, TCP, DNS, ping, PostgreSQL, Microsoft SQL Server, MySQL/MariaDB, Redis, SMTP, Kafka, and RabbitMQ, while also providing public status pages and multi-channel notifications.
That makes it more infrastructure-protocol-heavy than Statup, more app-like than Gatus, and closer to Uptime Kuma in the “self-hosted monitoring dashboard” category.
Uptime Kotlin = Quarkus API + React UI + PostgreSQL + scheduler/worker checks
What is Uptime Kotlin?
The repository I checked was:
Repository: https://github.com/TheoMeunier/uptime-kotlin
Checked commit: 787b0f9e6787baf1344dc2c0173c3ce16d03e2ac
Commit date: 2026-10-09
Latest checked tag: v1.3.0
License: MIT
Backend: Kotlin, Quarkus, Hibernate/Panache, Flyway
Frontend: React, Vite, TypeScript, Tailwind
Database: PostgreSQL
Container image tested: ghcr.io/theomeunier/uptime-kotlin:1.3.0
The standard image is all-in-one: web interface, API, and monitoring checks. For larger installations, the same project also publishes a worker image that can run checks separately while the API runs with scheduling disabled.
Why It Is Interesting
Most lightweight uptime tools start with HTTP checks and add a few extras.
Uptime Kotlin starts with a broader set of infrastructure protocols:
| Category | Supported Checks |
|---|---|
| Web/network | HTTP/HTTPS, TCP, ping, DNS |
| Databases | PostgreSQL, Microsoft SQL Server, MySQL/MariaDB, Redis |
| Messaging | Kafka producer, RabbitMQ |
| SMTP |
That makes it useful when you want one dashboard that can check more than “does this web page return 200?”
Features
The README highlights:
- real-time dashboard with historical data;
- public status pages;
- multi-channel notifications;
- encrypted secrets;
- JWT authentication;
- single Docker image for amd64 and ARM64;
- optional worker-based cluster mode;
- periodic resend while a monitor stays down, configured per monitor and disabled by default.
Notification channels in the source include:
- Email;
- Slack;
- Discord;
- Microsoft Teams;
- Telegram;
- ntfy;
- Gotify;
- generic webhook.
Self-Hosting Uptime Kotlin with Docker
I added a Home-Lab compose folder here:
Home-Lab Uptime Kotlin composeThe compose pins the 1.3.0 image and publishes the app on port 3812:
services:
uptime-kotlin:
image: ${UPTIME_KOTLIN_IMAGE:-ghcr.io/theomeunier/uptime-kotlin:1.3.0}
container_name: uptime-kotlin
restart: unless-stopped
mem_limit: ${UPTIME_KOTLIN_MEM_LIMIT:-512m}
ports:
- "${UPTIME_KOTLIN_BIND:-0.0.0.0}:${UPTIME_KOTLIN_PORT:-3812}:8080"
environment:
TZ: ${TZ:-Europe/Warsaw}
QUARKUS_DATASOURCE_USERNAME: ${POSTGRES_USER:-uptime-kotlin}
QUARKUS_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB:-uptime-kotlin}
ENCRYPTION_MASTER_KEY: ${ENCRYPTION_MASTER_KEY:?Set ENCRYPTION_MASTER_KEY in .env}
ENCRYPTION_PREVIOUS_MASTER_KEYS: ${ENCRYPTION_PREVIOUS_MASTER_KEYS:-}
MP_JWT_VERIFY_ISSUER: ${MP_JWT_VERIFY_ISSUER:-http://192.168.1.2:3812}
SCHEDULER_STRATEGY: ${SCHEDULER_STRATEGY:-database}
SCHEDULER_WORKER_CONCURRENCY: ${SCHEDULER_WORKER_CONCURRENCY:-4}
MAINTENANCE_HORIZON_DAYS: ${MAINTENANCE_HORIZON_DAYS:-90}
MAINTENANCE_MAX_DURATION_HOURS: ${MAINTENANCE_MAX_DURATION_HOURS:-24}
NOTIFICATIONS_DISPLAY_TIMEZONE: ${NOTIFICATIONS_DISPLAY_TIMEZONE:-Europe/Warsaw}
depends_on:
postgres:
condition: service_healthy
networks:
- uptime-kotlin
postgres:
image: ${POSTGRES_IMAGE:-postgres:17.4-alpine}
container_name: uptime-kotlin-postgres
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB:-uptime-kotlin}
POSTGRES_USER: ${POSTGRES_USER:-uptime-kotlin}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
PGDATA: /var/lib/postgresql/data/pgdata
volumes:
- uptime-kotlin-postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-uptime-kotlin} -d ${POSTGRES_DB:-uptime-kotlin}"]
interval: 10s
timeout: 5s
retries: 10
networks:
- uptime-kotlin
volumes:
uptime-kotlin-postgres:
networks:
uptime-kotlin:
driver: bridge
ipam:
config:
- subnet: ${UPTIME_KOTLIN_SUBNET:-10.89.12.0/24}
Start it:
cd uptime-kotlin
cp .env.sample .env
openssl rand -base64 32
nano .env
docker compose up -d
Open:
http://192.168.1.2:3812
Health check:
curl http://127.0.0.1:3812/q/health
Field Note: Local Trial
For the local trial I used:
ghcr.io/theomeunier/uptime-kotlin:1.3.0
postgres:17.4-alpine
The compose uses a 512 MB memory limit for the app container. The README specifically recommends setting a memory limit because the native Quarkus heap is sized from the memory the container sees.
The local URL is:
http://192.168.1.2:3812
The health endpoint returned UP with database, scheduler, worker loop, and reactive messaging checks:
curl http://127.0.0.1:3812/q/health
The setup status endpoint returned:
{"status":"false"}
That means no first user exists yet. Create the initial account through the UI.
One infrastructure note from this host: Docker refused to create another default Compose network because too many existing networks had already consumed the default address pools. The Home-Lab compose now assigns an explicit subnet:
UPTIME_KOTLIN_SUBNET=10.89.12.0/24
That is not an Uptime Kotlin problem; it is a practical homelab side effect after many local app trials.
Uptime Kotlin has an onboarding/setup API for the first user. There is no default admin password in the compose; create the first account through the UI.
Where It Fits Beside Uptime Kuma, Statup, Maintenant, and Beszel
| Tool | Best Fit |
|---|---|
| Uptime Kotlin | Broad protocol monitoring, status pages, notification routing, PostgreSQL-backed history, optional worker scaling |
| Uptime Kuma | Mature, easy uptime checks and push monitors with many notification integrations |
| Statup | Human-readable incident, maintenance, announcement, and status communication |
| Maintenant | Docker/Kubernetes runtime monitoring, logs, updates, certs, security insights, status pages |
| Beszel | Lightweight host/container resource metrics |
Uptime Kotlin is closer to Uptime Kuma than Statup. The main difference is its Kotlin/Quarkus/PostgreSQL architecture and the breadth of built-in protocol checks.
FAQ
Where can I see the UI in this homelab?
For this local compose:
http://192.168.1.2:3812
There is no default username or password. Create the first user through the setup/onboarding flow.
The setup status API showed {"status":"false"} on the first run, which indicates a fresh instance without an initial user.
Why does the compose define a custom Docker subnet?
This homelab has many existing Compose networks from app reviews. Docker eventually refused to create a new default network with:
all predefined address pools have been fully subnetted
To avoid pruning unrelated networks, the Home-Lab compose defines:
UPTIME_KOTLIN_SUBNET=10.89.12.0/24
If your Docker host has plenty of free address pools, you can remove the custom network block. If you run many test stacks, keeping an explicit subnet makes the compose more predictable.
Does it need PostgreSQL?
Yes.
Unlike Uptime Kuma, Statup, or many SQLite-first homelab tools, Uptime Kotlin is designed around PostgreSQL. It stores users, monitors, logs, status pages, notifications, scheduler jobs, workers, and encrypted secrets there.
That makes it heavier than a single-container SQLite app, but it also gives it a stronger base for history, queues, and worker mode.
Why is ENCRYPTION_MASTER_KEY so important?
ENCRYPTION_MASTER_KEY encrypts stored secrets and the JWT signing key.
Generate it once:
openssl rand -base64 32
Then keep it permanently in .env. If you lose it, encrypted notification credentials and monitor secrets cannot be recovered and must be re-entered.
To rotate it, set the new key in ENCRYPTION_MASTER_KEY and the old key in ENCRYPTION_PREVIOUS_MASTER_KEYS, restart, let the app re-encrypt stored secrets, then remove the old value on a later deployment.
What can it monitor?
The source defines checks for:
- HTTP/HTTPS;
- TCP;
- ping;
- DNS;
- PostgreSQL;
- Microsoft SQL Server;
- MySQL/MariaDB;
- Redis;
- SMTP;
- Kafka producer;
- RabbitMQ.
That is broader than many simple web uptime tools.
What is worker or cluster mode?
The all-in-one image can run the UI/API and checks together.
For larger deployments, run the main app with:
SCHEDULER_STRATEGY=none
Then add one or more ghcr.io/theomeunier/uptime-kotlin/worker containers with:
SCHEDULER_STRATEGY=database
SCHEDULER_WORKER_NAME=worker-primary
The workers share a job queue in PostgreSQL, so no Redis or RabbitMQ queue is required just for scheduling.
How does it compare with Uptime Kuma?
Uptime Kuma is easier and more mature for many homelab setups. It is also lighter to understand operationally.
Uptime Kotlin is more backend-engineered: PostgreSQL, encrypted secrets, JWT auth, broader protocol checks, and optional worker scaling.
If you want the simplest uptime dashboard, start with Uptime Kuma. If you want a Kotlin/Quarkus stack with broad protocol checks and a database-backed worker model, Uptime Kotlin is worth testing.
How does it compare with Statup?
Statup is communication-first: incidents, maintenance, announcements, and clear status updates for people.
Uptime Kotlin is monitoring-first: probes, logs, status pages, notifications, and worker scheduling.
They overlap on status pages and basic availability checks, but they serve different center-of-gravity use cases.
Can it replace Maintenant?
Not directly.
Maintenant knows about your Docker/Kubernetes runtime: containers, logs, image updates, security insights, heartbeats, certs, and status pages.
Uptime Kotlin knows about monitored services and protocols. It does not inspect the Docker host in the same runtime-aware way.
Use Uptime Kotlin for protocol-level checks. Use Maintenant when container/runtime visibility matters.
What should I back up?
Back up PostgreSQL and keep your .env securely backed up.
The critical pieces are:
- PostgreSQL data volume;
ENCRYPTION_MASTER_KEY;- any previous keys needed during rotation;
- external notification credentials you may need to re-enter.
Without the database you lose history/configuration. Without the encryption key, stored secrets become unreadable.
Can I expose it behind a reverse proxy?
Yes.
Forward all paths to port 8080. The README notes that exports may need a 300 second read timeout behind the proxy.
Set MP_JWT_VERIFY_ISSUER to the public URL you actually use, for example:
MP_JWT_VERIFY_ISSUER=https://uptime.example.com
Conclusion
Uptime Kotlin is a serious self-hosted monitoring app with a modern JVM-native backend, React dashboard, PostgreSQL storage, broad protocol support, notifications, and status pages.
It is heavier than Uptime Kuma or Statup, but that is partly the point: it is designed more like an application platform for monitoring checks, with encrypted secrets and optional workers.
For a homelab, I would test it beside Uptime Kuma rather than replace anything immediately. The interesting part is whether the broader protocol list and worker model solve checks that your current uptime dashboard does not handle cleanly.
Comments