RAID/R2D2-OPS-Kuma
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 3

docs(readme): rewrite for TFX FMV console + k8s deployment

Browse source 
Replace the stock Uptime Kuma README with one describing the actual
app: the R2D2/Task Force X ops console, its architecture, local dev,
configuration/security model, and the standalone k8s deployment at
ops.r2d2.office.ilab.zone. Drops upstream badges/sponsors/live-demo.
This commit is contained in:
Josh Belke 2026-07-08 05:44:23 -04:00
commit 767421c3b6
1 changed files with 142 additions and 151 deletions
Download patch file Download diff file Expand all files Collapse all files

307
README.md
View file

@ -1,203 +1,194 @@
<div align="center" width="100%">
<img src="./public/icon.svg" width="128" alt="Uptime Kuma Logo" />
<img src="./public/tfx-logo.png" width="120" alt="Task Force X emblem" />
</div>
# Uptime Kuma
# R2D2 Status — Task Force X FMV Console
Uptime Kuma is an easy-to-use self-hosted monitoring tool.
Fleet monitoring and full-motion-video (FMV) operations console for the Task
Force X (TFX) unmanned maritime program. It tracks the health of ~118 assets —
video feeds, restreamer panels, NodeRed pipelines, and core R2D2 services —
across the NATO maritime theatres, and gives operators a single board to see
which platforms are live, watch their streams, and capture evidence.
<a target="_blank" href="https://github.com/louislam/uptime-kuma"><img src="https://img.shields.io/github/stars/louislam/uptime-kuma?style=flat" /></a> <a target="_blank" href="https://hub.docker.com/r/louislam/uptime-kuma"><img src="https://img.shields.io/docker/pulls/louislam/uptime-kuma" /></a> <a target="_blank" href="https://hub.docker.com/r/louislam/uptime-kuma"><img src="https://img.shields.io/docker/v/louislam/uptime-kuma/2?label=docker%20image%20ver." /></a> <a target="_blank" href="https://github.com/louislam/uptime-kuma"><img src="https://img.shields.io/github/last-commit/louislam/uptime-kuma" /></a> <a target="_blank" href="https://opencollective.com/uptime-kuma"><img src="https://opencollective.com/uptime-kuma/total/badge.svg?label=Open%20Collective%20Backers&color=brightgreen" /></a>
[![GitHub Sponsors](https://img.shields.io/github/sponsors/louislam?label=GitHub%20Sponsors)](https://github.com/sponsors/louislam) <a href="https://weblate.kuma.pet/projects/uptime-kuma/uptime-kuma/">
<img src="https://weblate.kuma.pet/widgets/uptime-kuma/-/svg-badge.svg" alt="Translation status" />
</a>
The monitoring engine is [Uptime Kuma](https://github.com/louislam/uptime-kuma)
2.4.0 (unmodified upstream). Everything specific to TFX lives in `.settings/`:
a seed toolchain that builds the monitor topology, and a purpose-built operator
console layered on top of Kuma.
<img src="https://user-images.githubusercontent.com/1336778/212262296-e6205815-ad62-488c-83ec-a5b0d0689f7c.jpg" width="700" alt="Uptime Kuma Dashboard Screenshot" />
Production console: **`https://ops.r2d2.office.ilab.zone`**
## 🥔 Live Demo
---
Try it!
## What it does
Demo Server (Location: Frankfurt - Germany): <https://demo.kuma.pet/start-demo>
- **Monitors ~118 assets** grouped three levels deep — *waterway → country →
asset* — across Central/Eastern Med, Baltic, North Sea and North Atlantic.
- **Video-aware status.** A feed that answers HTTP 200 but whose projector
snapshot has frozen is downgraded to *pending* — so "up" means live video, not
just a reachable port.
- **Operator console** — search/filter the whole fleet, open a native detail
view with an HLS player, and record clips or snapshot sessions to disk.
- **Region-grouped public status pages** (`/status/r2d2`, `videos`, `panels`,
`core`, `nodered`) rebuilt idempotently from the seed plan.
It is a temporary live demo, all data will be deleted after 10 minutes. Sponsored by [Uptime Kuma Sponsors](https://github.com/louislam/uptime-kuma#%EF%B8%8F-sponsors).
---
## ⭐ Features
## Architecture
- Monitoring uptime for HTTP(s) / TCP / HTTP(s) Keyword / HTTP(s) Json Query / Websocket / Ping / DNS Record / Push / Steam Game Server / Docker Containers
- Fancy, Reactive, Fast UI/UX
- Notifications via Telegram, Discord, Gotify, Slack, Pushover, Email (SMTP), and [90+ notification services, click here for the full list](https://github.com/louislam/uptime-kuma/tree/master/src/components/notifications)
- 20-second intervals
- [Multi Languages](https://github.com/louislam/uptime-kuma/tree/master/src/lang)
- Multiple status pages
- Map status pages to specific domains
- Ping chart
- Certificate info
- Proxy support
- 2FA support
```
┌──────────────────────────────────────────────────────────────┐
│ Uptime Kuma 2.4.0 (upstream, unmodified) │
│ · monitoring engine · heartbeats/uptime · CSS-only status │
│ · SQLite (PVC) listens :3001 │
└───────────────▲───────────────────────────────┬──────────────┘
│ socket.io (server-side, admin) │ HTTP status pages
│ ▼
┌───────────────┴──────────────────────────────────────────────┐
│ R2D2 Ops Console (.settings/ops/serve.mjs, :4013) │
│ · logs into Kuma once, holds a live in-memory fleet model │
│ · SPA + JSON snapshot + SSE live stream │
│ · snapshot / HLS media proxy (host-allowlisted) │
│ · liveness poller (snapshot-hash freeze detection) │
│ · recorder (ffmpeg clip + snapshot capture) │
└───────────────────────────────────────────────────────────────┘
```
## 🔧 How to Install
Repository layout (TFX-specific work is isolated in `.settings/`; the rest is
stock Uptime Kuma):
### 🐳 Docker Compose
| Path | Purpose |
|------|---------|
| `.settings/seed/convert.mjs` | Builds `monitors.json` from the legacy endpoint config + holovids CSV exports. |
| `.settings/seed/monitors.json` | Reviewable seed plan — 21 groups · 118 monitors. |
| `.settings/seed/seed.mjs` | Seeds groups, monitors, and all status pages into Kuma. |
| `.settings/seed/statuspage.mjs` | Non-destructive rebuild of the status pages only. |
| `.settings/seed/docker-compose.yml` | Local Kuma on host port **3011**, with TFX branding applied at boot. |
| `.settings/ops/serve.mjs` | Ops console server (:4013). |
| `.settings/ops/index.html` | Operator SPA (search, detail, HLS player, capture controls). |
| `.settings/ops/recorder.mjs` | Clip / snapshot recorder. |
| `.settings/features/` | Feature roadmap (01–11). |
---
## Local development
Prerequisites: Docker (with Compose) and Node.js 18+.
```bash
mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
cd .settings/seed
# 1. Start a local Kuma (SQLite preselected — no setup wizard).
# Host port 3011 (3001 is commonly taken); TFX branding is applied at boot.
docker compose up -d
# 2. (optional) Regenerate the seed plan. monitors.json is committed.
node convert.mjs
# 3. Seed groups, monitors, and status pages. First run creates the admin user.
KUMA_URL=http://localhost:3011 node seed.mjs
# 4. Rebuild only the status pages later, non-destructively.
KUMA_URL=http://localhost:3011 node statuspage.mjs
```
Uptime Kuma is now running on all network interfaces (e.g. http://localhost:3001 or http://your-ip:3001).
- Kuma dashboard: <http://localhost:3011>
- Public status page: <http://localhost:3011/status/r2d2>
> [!WARNING]
> File Systems like **NFS** (Network File System) are **NOT** supported. Please map to a local directory or volume.
### 🐳 Docker Command
Start the operator console against that Kuma:
```bash
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2
cd .settings/ops
KUMA_URL=http://localhost:3011 node serve.mjs
# → http://localhost:4013
```
Uptime Kuma is now running on all network interfaces (e.g. http://localhost:3001 or http://your-ip:3001).
---
If you want to limit exposure to localhost only:
## Configuration
```bash
docker run ... -p 127.0.0.1:3001:3001 ...
```
Both the seeder and the ops server are configured entirely through environment
variables.
### 💪🏻 Non-Docker
| Variable | Default | Used by | Meaning |
|----------|---------|---------|---------|
| `KUMA_URL` | `http://localhost:3011` | seed, ops | Kuma base URL. |
| `ADMIN_USER` / `ADMIN_PASS` | `NATO` / `NATO1949` | seed, ops | Kuma admin credentials. **Override before any non-local deploy** — seeding refuses the defaults against a non-localhost target unless `ALLOW_DEFAULT_CREDS=1`. |
| `FORCE` | unset | seed | Allow re-seeding an already-populated instance. |
| `OPS_PORT` | `4013` | ops | Console listen port. |
| `OPS_BIND` | `127.0.0.1` | ops | Listen interface. Set `0.0.0.0` to expose beyond localhost. |
| `OPS_SECRET` | unset | ops | When set, every state-changing `POST` must send a matching `x-ops-secret` header. Set this before binding beyond localhost. |
| `REC_ROOT` | machine-specific | recorder | Root directory for captured clips/snapshots. |
Requirements:
### Security model
- Platform
- ✅ Major Linux distros such as Debian, Ubuntu, Fedora and ArchLinux etc.
- ✅ Windows 10 (x64), Windows Server 2012 R2 (x64) or higher
- ❌ FreeBSD / OpenBSD / NetBSD
- ❌ Replit / Heroku
- [Node.js](https://nodejs.org/en/download/) >= 20.4
- [Git](https://git-scm.com/downloads)
- [pm2](https://pm2.keymetrics.io/) - For running Uptime Kuma in the background
The Kuma admin password is used **only** on the server. The browser never sees a
credential or a direct Kuma socket. The console is **not** read-only, though — it
exposes mutating endpoints (`delete-monitors`, `set-interval`,
`record/{start,stop,config}`) that act on Kuma as admin. Two controls gate them:
```bash
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
- `OPS_BIND` defaults to localhost, so the console answers nothing on the network
until you opt in.
- `OPS_SECRET`, once set, requires the `x-ops-secret` header on every mutating
request; read endpoints (feed, snapshot, HLS) stay open.
# Option 1. Try it
node server/server.js
**Always set `OPS_SECRET` before setting `OPS_BIND=0.0.0.0`.**
# (Recommended) Option 2. Run in the background using PM2
# Install PM2 if you don't have it:
npm install pm2 -g && pm2 install pm2-logrotate
---
# Start Server
pm2 start server/server.js --name uptime-kuma
```
## Kubernetes deployment
Uptime Kuma is now running on all network interfaces (e.g. http://localhost:3001 or http://your-ip:3001).
The production console is a **standalone** deployment reachable at
`ops.r2d2.office.ilab.zone` — a Kuma pod plus the ops server, with the pod joined
to the mesh so it can actually probe the feeds.
More useful PM2 Commands
Target topology:
```bash
# If you want to see the current console output
pm2 monit
- **Kuma container** — `louislam/uptime-kuma:2`, listening on `:3001`, SQLite
persisted on a **Longhorn PVC** so monitor config and history survive restarts.
- **Ops console container** — runs `.settings/ops/serve.mjs` on `:4013`,
`KUMA_URL` pointing at the Kuma container. `OPS_BIND=0.0.0.0` with
`OPS_SECRET` set; admin credentials injected from a Kubernetes `Secret`.
- **NetBird sidecar** — most feeds live on the mesh and are unreachable from the
cluster's default network. The sidecar puts the pod on the mesh so Kuma's
probes and the ops snapshot/HLS proxies resolve real hosts. Off-mesh, feeds
read as pending/down by design.
- **Ingress** — TLS at `ops.r2d2.office.ilab.zone`, routing to the ops console
(`:4013`), which fronts both the operator SPA and the Kuma status pages.
# If you want to add it to startup
pm2 startup && pm2 save
```
Deployment notes:
### Advanced Installation
- Cluster access uses `.settings/kubeconfig.r2d2` — treat as sensitive.
- Rotate `ADMIN_USER` / `ADMIN_PASS` out of the defaults; source them from the
`Secret`, never from image or compose defaults.
- The packaged Helm chart (Kuma + ops console + NetBird sidecar + Longhorn PVC +
ingress) is the deployment vehicle and is tracked as roadmap item **R-007**;
until it lands, deployment is applied from manifests against the topology above.
If you need more options or need to browse via a reverse proxy, please read:
---
<https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install>
## Roadmap
## 🆙 How to Update
Feature specs live in [`.settings/features/`](.settings/features/) and the
umbrella plan in [`.settings/ops/PLAN.md`](.settings/ops/PLAN.md):
Please read:
| # | Feature | State |
|---|---------|-------|
| 01 | Ops Feed (search / filter) | Done |
| 02 | Holovids feed enrichment | Done |
| 05 | Deep probes / liveness | Partial |
| 06 | Native media detail + HLS player | Building |
| 07 | Live recording (clips + snapshots) | Building |
| 08 | KLV telemetry discovery | Discovery |
| 09 | C2 map / common operating picture | Planned |
| 10 | ReductStore media archive (FIFO) | Planned |
| 11 | Drone MQTT discovery & video↔node association | Planned |
<https://github.com/louislam/uptime-kuma/wiki/%F0%9F%86%99-How-to-Update>
---
## 🆕 What's Next?
## Upstream
I will assign requests/issues to the next milestone.
<https://github.com/louislam/uptime-kuma/milestones>
## ❤️ Sponsors
Thank you so much! (GitHub Sponsors will be updated manually. OpenCollective sponsors will be updated automatically, the list will be cached by GitHub though. It may need some time to be updated)
<img src="https://uptime.kuma.pet/sponsors?v=6" alt="Uptime Kuma Sponsors" />
## 🖼 More Screenshots
Light Mode:
<img src="https://uptime.kuma.pet/img/light.jpg" width="512" alt="Uptime Kuma Light Mode Screenshot of how the Dashboard looks" />
Status Page:
<img src="https://user-images.githubusercontent.com/1336778/134628766-a3fe0981-0926-4285-ab46-891a21c3e4cb.png" width="512" alt="Uptime Kuma Status Page Screenshot" />
Settings Page:
<img src="https://louislam.net/uptimekuma/2.jpg" width="400" alt="Uptime Kuma Settings Page Screenshot" />
Telegram Notification Sample:
<img src="https://louislam.net/uptimekuma/3.jpg" width="400" alt="Uptime Kuma Telegram Notification Sample Screenshot" />
## Motivation
- I was looking for a self-hosted monitoring tool like "Uptime Robot", but it is hard to find a suitable one. One of the closest ones is statping. Unfortunately, it is not stable and no longer maintained.
- Wanted to build a fancy UI.
- Learn Vue 3 and vite.js.
- Show the power of Bootstrap 5.
- Try to use WebSocket with SPA instead of a REST API.
- Deploy my first Docker image to Docker Hub.
If you love this project, please consider giving it a ⭐.
## 🗣️ Discussion / Ask for Help
⚠️ For any general or technical questions, please don't send me an email, as I am unable to provide support in that manner. I will not respond if you ask questions there.
I recommend using Google, GitHub Issues, or Uptime Kuma's subreddit for finding answers to your question. If you cannot find the information you need, feel free to ask:
- [GitHub Issues](https://github.com/louislam/uptime-kuma/issues)
- [Subreddit (r/UptimeKuma)](https://www.reddit.com/r/UptimeKuma/)
My Reddit account: [u/louislamlam](https://reddit.com/u/louislamlam)
You can mention me if you ask a question on the subreddit.
## Contributions
### Create Pull Requests
Pull requests are awesome.
To keep reviews fast and effective, please make sure you’ve [read our pull request guidelines](https://github.com/louislam/uptime-kuma/blob/master/CONTRIBUTING.md#can-i-create-a-pull-request-for-uptime-kuma).
### Test Pull Requests
There are a lot of pull requests right now, but I don't have time to test them all.
If you want to help, you can check this:
<https://github.com/louislam/uptime-kuma/wiki/Test-Pull-Requests>
### Test Beta Version
Check out the latest beta release here: <https://github.com/louislam/uptime-kuma/releases>
### Bug Reports / Feature Requests
If you want to report a bug or request a new feature, feel free to open a [new issue](https://github.com/louislam/uptime-kuma/issues).
### Translations
If you want to translate Uptime Kuma into your language, please visit [Weblate Readme](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md).
### Spelling & Grammar
Feel free to correct the grammar in the documentation or code.
My mother language is not English and my grammar is not that great.
Built on [Uptime Kuma](https://github.com/louislam/uptime-kuma) by Louis Lam,
licensed under the MIT License. The `server/` and `src/` trees are stock upstream
and are intentionally left unmodified — all TFX customisation is confined to
`.settings/`. See [`LICENSE`](LICENSE) for terms.
</content>