From 9c3afb31af814ddcc2bba8215b340421dce810d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Kr=C3=BCger?= Date: Tue, 18 Aug 2026 10:05:45 +0200 Subject: [PATCH] docs: update README for combined docker+API service widgets The dedicated traefik widget type was folded into the generic service type; document the resulting service variants (gitea, coolify, immich, n8n, umami, headscale, traefik) and the secret redaction that ships alongside it. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01WpxhtQY3CExQdMs4j7MmJe --- README.md | 52 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0fa1140..8b904de 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,25 @@ # PulseNode A self-hosted infrastructure dashboard: system stats, Docker containers, -databases, and HTTP/Traefik health, configured entirely through a YAML file -and pushed to the browser live over WebSockets. No database of its own - -`config.yml` is the source of truth, metrics are ephemeral. +databases, HTTP checks, and combined docker+API service widgets, configured +entirely through a YAML file and pushed to the browser live over WebSockets. +No database of its own - `config.yml` is the source of truth, metrics are +ephemeral. ## Features - **YAML-configured** widgets and layout, hot-reloaded - edit `config.yml` and connected browsers update without a page refresh - **Secrets via `.env`**, interpolated into `config.yml` at load time - (`${VAR}` / `${VAR:-default}`), never sent to the browser + (`${VAR}` / `${VAR:-default}`). Widget fields named `apiToken`/`apiKey`/ + `password` are stripped before the config ever reaches the browser + (`lib/config/public.ts`) - collectors run server-side and use the real + values, the client never sees them - **Live updates over WebSocket** - each widget subscribes to its own topic; the server only serializes results for widgets someone is actually viewing - **Widget types**: Docker containers, Postgres/Redis instances, system - resources, HTTP health checks, Traefik router status, bookmarks, search + resources, HTTP health checks, combined docker+API service widgets + (Gitea, Coolify, Immich, n8n, Umami, Headscale, Traefik), bookmarks, search - **Optional label-based auto-discovery** - containers carrying `traefik.enable=true` can be turned into dashboard widgets automatically; manual `config.yml` entries always take precedence @@ -64,13 +69,20 @@ discovery: network: falcon_network # only include containers on this docker network groups: - - name: Core Infra + - name: Infra widgets: - - type: docker + - type: system + interval: 5s + + - name: Services + widgets: + - type: service + service: traefik name: Traefik containerName: traefik + icon: traefik href: https://traefik.example.com - interval: 10s + interval: 15s ``` Config errors are **non-destructive**: if `config.yml` fails validation @@ -93,10 +105,26 @@ reload; never exposed to the client. See `config/.env.example`. | `database` | `name`, `containerName`, `engine` | Thin skin over the same Docker collector - `engine` is `postgres` or `redis`, used for icon/label only. `interval` default `10s`. | | `system` | - | Host CPU/mem/disk/network via `systeminformation`. Optional `name` (default `System`), `interval` (default `5s`). | | `http` | `name`, `url` | HTTP health check with latency and consecutive-failure tracking. Optional `method` (default `GET`), `timeout` (default `5s`), `interval` (default `30s`), `expect.status` (default `200`). | -| `traefik` | `apiUrl` | Router/entrypoint/middleware status from Traefik's own API (`--api.dashboard=true` must be enabled). Optional `name` (default `Traefik`), `interval` (default `15s`). | +| `service` | `name`, `containerName`, `service` | Docker health/CPU/mem (same collector as `docker`) merged with a stat pulled from the service's own API. `service` picks the variant (see below) and its extra fields. A failed API call surfaces as a non-fatal `statError` on the card without hiding docker health. Optional `href`, `icon`, `showStats` (default `true`), `interval` (default `15s`). | `interval`/`timeout` values are duration strings: `500ms`, `5s`, `1m`, `1h`. +#### `service` variants + +Each `service` widget calls its target container directly by name on the +docker network (`http://:`), not through Traefik/TLS - +no `apiUrl` field needed. + +| `service` | Extra fields | Stat shown | +|-------------|--------------------------------------------|------------| +| `gitea` | `username` (default `Valknar`), `apiToken` | Repository count | +| `coolify` | `apiToken` | Project count, resource count | +| `immich` | `apiKey` | Photo count, video count | +| `n8n` | `apiKey` | Workflow count | +| `umami` | `username`, `password`, `websiteId` | Active visitors (login-and-cache, self-hosted has no static API key) | +| `headscale` | `apiToken` | User count, node count | +| `traefik` | - | HTTP router count (needs `--api.insecure=true` or a dashboard entrypoint reachable on the docker network) | + `icon` on `docker`/`bookmark` widgets is a key into `lib/brand-icons.ts` (currently `traefik`, `coolify`, `gitea`, `docker`, `immich`, `n8n`, `passbolt`, `umami`, `postgresql`, `redis`, `headscale`), rendered monochrome so it doesn't compete @@ -147,8 +175,10 @@ server.ts custom server: http + WebSocket (/ws) + collector schedul app/ Next.js App Router pages and API routes components/widgets/ one folder per widget type (Widget.tsx + shared Skeleton/StatusDot) components/layout/ Dashboard shell, theme toggle, brand mark -lib/config/ schema (zod), loader (parse/interpolate/watch), effective (+ discovery merge) -lib/collectors/ docker, system, http, traefik collectors + the scheduler +lib/config/ schema (zod), loader (parse/interpolate/watch), effective (+ discovery merge), + public.ts (strips secrets before the config reaches the browser) +lib/collectors/ docker, system, http collectors, service.ts (docker+API merge) with + one collector per service under services/, + the scheduler lib/discovery/ traefik-label auto-discovery lib/ws/ WebSocket server (topics) and the browser-side subscription hooks ```