Rename maglev-frontend → maglevd-frontend; v0.9.1; API RX/TX pulse

Rename the web dashboard binary to maglevd-frontend and move it to /usr/sbin (it's a daemon and belongs with maglevd). The systemd unit name stays vpp-maglev-frontend.service since that prefix is the package name. Manpage, README, user-guide, and debian packaging all updated in lockstep; bump to 0.9.1 for the first real release. All frontend env vars are now prefixed MAGLEV_FRONTEND_ so a single /etc/default/vpp-maglev can be shared with maglevd without collisions. Every flag has an env equivalent for Docker use. MAGLEV_FRONTEND_USER and MAGLEV_FRONTEND_PASSWORD still gate the /admin surface. VPPInfoPanel now pulses "API: ↑↓" indicators in the zippy title whenever a vpp-api-send / vpp-api-recv log event arrives on the SSE stream for the scoped maglevd — 250ms blue flash, re-triggerable, with the two arrows tightly kerned via negative letter-spacing.
2026-04-13 00:13:47 +02:00
parent 1191b3d994
commit 35643fd774
20 changed files with 380 additions and 83 deletions
--- a/README.md
+++ b/README.md
@@ -1,52 +1,89 @@
-# maglevd
+# vpp-maglev

-Health checker and gRPC control plane for VPP Maglev load balancing.
+Health checker, gRPC control plane, CLI, and web dashboard for the VPP
+`lb` (load-balancer) plugin. Runs as a set of three binaries under one
+Debian package:

-## Build and Install
+- **`maglevd`** — the long-running health-checker daemon. Probes backends
+  (HTTP, TCP, ICMP), tracks their aggregate state, programs the VPP
+  dataplane via the `lb` plugin binary API, and exposes everything
+  over a gRPC API + Prometheus `/metrics` endpoint.
+- **`maglevc`** — the interactive CLI client. Tab-completing shell with
+  inline help; also runs one-shot commands for scripting.
+- **`maglevd-frontend`** — optional web dashboard. One binary with the
+  SolidJS SPA embedded via `//go:embed`; connects to one or more
+  maglevds over gRPC and serves a live HTTP view (read-only `/view/`
+  and optional basic-auth `/admin/`).
+
+## Build and install

 ```sh
-make          # builds build/<arch>/maglevd and build/<arch>/maglevc
+make          # builds build/<arch>/{maglevd,maglevc,maglevd-frontend}
 make test     # runs all tests
-make pkg-deb  # Creates a debian package for arm64 and amd64
+make pkg-deb  # creates a Debian package for amd64 and arm64
 ```

-Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go` and
-`protoc-gen-go-grpc`.
+Requires Go 1.25+ and (for `make proto`) `protoc` with `protoc-gen-go`
+and `protoc-gen-go-grpc`. The SolidJS bundle under
+`cmd/frontend/web/` is built automatically via `make` through the
+`maglevd-frontend-web` target, which needs `npm`.

-Produces `vpp-maglev_<version>_amd64.deb` and `vpp-maglev_<version>_arm64.deb`
-in the `build/` directory by cross-compiling with `GOOS=linux GOARCH=<arch>`.
-Requires `dpkg-deb` (available on any Debian/Ubuntu host). The installed
-binaries report the exact git commit via `maglevd --version` (and
-similarly for `maglevc` / `maglev-frontend`).
+Produces `vpp-maglev_<version>_amd64.deb` and
+`vpp-maglev_<version>_arm64.deb` in the `build/` directory by
+cross-compiling with `GOOS=linux GOARCH=<arch>`. Requires `dpkg-deb`
+(available on any Debian/Ubuntu host). The installed binaries report
+the exact git commit via `maglevd --version` (and similarly for
+`maglevc` / `maglevd-frontend`).

 ## Running

-After installing, the unit is enabled but not started automatically:
+After installing, `maglevd` is enabled automatically but
+`maglevd-frontend` is **not** — it's opt-in, so the web dashboard
+doesn't surprise anyone who just wanted the daemon:

 ```sh
 # edit /etc/vpp-maglev/maglev.yaml, then:
 systemctl enable --now vpp-maglev
+
+# optional: web dashboard. Edit /etc/default/vpp-maglev to set
+# MAGLEV_FRONTEND_ARGS and (optionally) MAGLEV_FRONTEND_USER /
+# MAGLEV_FRONTEND_PASSWORD for /admin/ access, then:
+systemctl enable --now vpp-maglev-frontend
 ```

-Or run the server and client by hand:
+Or run the components by hand:

 ```sh
 maglevd --config /etc/vpp-maglev/maglev.yaml --grpc-addr :9090
-maglevd --version                        # print version and exit
+maglevd --version                         # print version and exit

-maglevc --server localhost:9090          # interactive shell
-maglevc show frontends                   # one-shot
-maglevc -color=false show backends       # one-shot, no ANSI color
+maglevc --server localhost:9090           # interactive shell
+maglevc show frontends                    # one-shot
+maglevc -color=false show backends        # one-shot, no ANSI color
 maglevc set backend nginx0-ams pause
+
+maglevd-frontend -server localhost:9090 -listen :8080
 ```

 Send `SIGHUP` to `maglevd` to reload config without restarting.
 `maglevd` requires `CAP_NET_RAW` for ICMP health checks.

-Check out a minimal configuration file in [[debian/maglev.yaml](debian/maglev.yaml)].
-See [docs/user-guide.md](docs/user-guide.md) for flags, signals, and `maglevc` usage.
-See [docs/config-guide.md](docs/config-guide.md) for the full configuration reference.
-See [docs/healthchecks.md](docs/healthchecks.md) for health state machine details.
+Every flag on every binary also has an environment-variable
+equivalent (e.g. `MAGLEV_CONFIG`, `MAGLEV_GRPC_ADDR`,
+`MAGLEV_SERVERS`, `MAGLEV_LISTEN`, `MAGLEV_LOG_LEVEL`) so all three
+programs can be driven entirely via env in containerized
+deployments.
+
+## Documentation
+
+- A minimal configuration file in
+  [debian/maglev.yaml](debian/maglev.yaml) shows every knob.
+- [docs/user-guide.md](docs/user-guide.md) — flags, signals, and
+  `maglevc` command reference.
+- [docs/config-guide.md](docs/config-guide.md) — full YAML reference.
+- [docs/healthchecks.md](docs/healthchecks.md) — health state
+  machine, probe scheduling, rise/fall semantics.
+- Manpages: `maglevd(8)`, `maglevc(1)`, `maglevd-frontend(8)`.

 ## Docker