pulsenode/README.md

# 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.

## 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
- **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
- **Optional label-based auto-discovery** - containers carrying
  `traefik.enable=true` can be turned into dashboard widgets automatically;
  manual `config.yml` entries always take precedence
- **CSS-variable theming**, light/dark toggle, `theme.customCssPath` for a
  fully custom stylesheet
- **Ships as a single Docker image**, designed to run non-root with a
  read-only root filesystem

## Quick start (local development)

```bash
pnpm install
cp config/.env.example config/.env   # fill in real values
cp .env.example .env                 # only needed for docker compose
pnpm dev
```

Open `http://localhost:3000`. `pnpm dev` runs the custom server
(`server.ts`) via `tsx watch`, which boots Next.js, the WebSocket server, and
the collector scheduler together, and restarts on server-side code changes.
Editing `config.yml` itself does **not** restart the process - it's picked
up live via the config watcher.

Other scripts: `pnpm build` (production build), `pnpm start` (run the
production build via the same custom server), `pnpm lint`, `pnpm exec tsc
--noEmit`.

## Configuration

### `config/config.yml`

Everything is organized into `groups`, each a list of `widgets`:

```yaml
settings:
  title: PulseNode

theme:
  mode: dark              # dark | light | auto
  variables:
    --pn-accent: "#38bdf8"
  # customCssPath: custom.css   # relative to config/, served at /api/theme/custom-css

discovery:
  docker:
    enabled: false          # set true to auto-discover traefik-labeled containers
    network: falcon_network # only include containers on this docker network

groups:
  - name: Core Infra
    widgets:
      - type: docker
        name: Traefik
        containerName: traefik
        href: https://traefik.example.com
        interval: 10s
```

Config errors are **non-destructive**: if `config.yml` fails validation
after a live edit, PulseNode logs the error and keeps serving the last
valid config instead of crashing.

### `config/.env`

Secrets and per-deployment values referenced from `config.yml` via
`${VAR}` or `${VAR:-default}`. Loaded once at startup and on every config
reload; never exposed to the client. See `config/.env.example`.

### Widget types

| `type`     | Required fields                    | Notes |
|------------|-------------------------------------|-------|
| `bookmark` | `name`, `href`                      | Static link card. Optional `description`. |
| `search`   | -                                    | Client-side search box. Optional `engines` (`duckduckgo`/`google`/`bing`, default `[duckduckgo]`), `defaultEngine`. |
| `docker`   | `name`, `containerName`             | Status, uptime, CPU/mem, restart count via `dockerode`. Optional `href`, `showStats` (default `true`), `interval` (default `5s`). |
| `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`). |

`interval`/`timeout` values are duration strings: `500ms`, `5s`, `1m`, `1h`.

### Auto-discovery

With `discovery.docker.enabled: true`, PulseNode scans running containers
every 60s (and immediately on any `config.yml` change) for
`traefik.enable=true` labels, parses the router's `Host(...)` rule for a
link, and adds anything not already listed manually to a synthetic
"Discovered" group. `discovery.docker.excludeLabels` and `.network` narrow
what qualifies; `.labelPrefix` (default `traefik`) controls which label
namespace is read.

## Deployment

```bash
cp .env.example .env
cp config/.env.example config/.env
# edit both, then:
docker compose up -d --build
```

- `.env` (repo root) holds `TRAEFIK_HOST`, `NETWORK_NAME`, and `DOCKER_GID` -
  compose-level values, interpolated into `docker-compose.yml`'s Traefik
  labels and used to join the container to the docker group. Find your
  host's docker group id with `getent group docker | cut -d: -f3`; without
  it the non-root container gets `EACCES` on `/var/run/docker.sock`.
- `config/.env` holds values referenced from `config.yml` (see above).
- The compose file joins the container to an **external** `falcon_network`
  so collectors can reach services directly by container name
  (`http://umami:3000/...`) instead of only through Traefik.
- `/var/run/docker.sock` is mounted read-only; `/app/config` is mounted
  read-only from `./config`.
- The container runs as a non-root user with a read-only root filesystem,
  dropped capabilities, and `tini` as PID 1.
- `/api/health` backs the container `HEALTHCHECK`.

## Project structure

```
config/                config.yml + .env (gitignored) live here
server.ts              custom server: http + WebSocket (/ws) + collector scheduler
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/discovery/         traefik-label auto-discovery
lib/ws/                WebSocket server (topics) and the browser-side subscription hooks
```

## Known limitations

- **No authentication yet.** PulseNode assumes it's reachable only on a
  private network (e.g. behind Traefik with no public route, or on a VPN).
  A minimal session-based auth gate is a planned follow-up, not yet built.
- `system` widget metrics reflect whatever cgroup/namespace the container
  runs in - for true host-level stats rather than the container's own view,
  mount `/proc` and `/sys` from the host and run with `pid: host` (not
  configured by default).