ponfw/web/README.md

# PON Fleet — web server

A multi-user, browser-based front end for the same tooling as the Electron
**PON Fleet Upgrader** (Dashboard / ONU firmware upgrades / OLT PON
flooding mode). Built to sit behind a TLS-terminating reverse proxy so
several operators can use it at once, **each with their own MCMS login**.

## How it relates to the Electron app

It does **not** duplicate the app — it reuses it:

- **Core logic** comes straight from `../src/` (`mcms-api.js`,
  `bank-strategy.js`, `dashboard.js`). One source of truth for every MCMS
  quirk.
- **The UI is the same files.** The server serves `../renderer/app.js` and
  `../renderer/app.css` as-is and rewrites `../renderer/index.html` on the
  fly (adds a mobile viewport, swaps in the browser API shim + a small
  responsive overlay). So the Electron app and the web app never drift.
- The only web-specific code is `server.js`, `public/api-web.js` (a
  `window.api` shim: Electron IPC → `fetch` + NDJSON streaming, Electron
  file dialogs → browser file pickers, CSV-to-Downloads → Blob download),
  and `public/web.css` (responsive overlay).

Because of the `../` references this folder **must** live inside
`pon-fleet-upgrader/` (it borrows the already-installed `tough-cookie` from
`../node_modules`). No separate `npm install` is needed.

## Run

```bash
cd pon-fleet-upgrader/web
npm start            # node server.js — listens on 127.0.0.1:8080
npm run check        # node --check on server.js + api-web.js
```

Then browse to <http://127.0.0.1:8080>. Each browser logs in with its own
MCMS host + credentials; the server keeps a separate `McmsClient` (separate
cookie jar) per session.

### Configuration (env)

| Var | Default | Meaning |
|---|---|---|
| `PORT` | `8080` | listen port |
| `HOST` | `127.0.0.1` | bind address — `0.0.0.0` if the proxy is on another host |
| `PFW_CACHE_TTL_SECONDS` | `60` | shared upstream cache TTL; `0` disables (see Caching) |
| `PFW_IDLE_MINUTES` | `30` | idle-session expiry (logs the MCMS session out) |
| `PFW_SECURE_COOKIE` | off | force the `Secure` cookie flag (else inferred from `X-Forwarded-Proto: https`) |
| `PFW_VERBOSE` | off | verbose MCMS request logging (very noisy with many users) |

## Caching (fewer MCMS requests)

The server keeps a small in-memory cache so multiple operators don't each
hammer MCMS. The heavy bulk **reads** — ONU configs, ONU states, OLT states,
OLT configs, controller configs, firmware inventory — are cached with a TTL
(`PFW_CACHE_TTL_SECONDS`, default 60s) and **keyed by MCMS host**, so:

- Everyone pointed at the same MCMS shares one snapshot. Ten operators
  loading the fleet within a minute trigger **one** upstream fetch, not ten.
- A **single-flight** guard means even simultaneous cold loads collapse into
  one upstream request (the rest await it).
- Different MCMS hosts never share, and the dashboard's light path reuses the
  same OLT-STATE snapshot the fleet view already fetched.

What is **not** cached (always live, by design):

- Per-ONU `getOnuConfig` used right before a firmware PUT (read-modify-write
  must see the current bank state).
- The FEC pre-flight and verify per-ONU `getOnuState` (operators want the
  reading at decision time).

**Writes invalidate** the affected datasets for that MCMS host, so a delete /
firmware push / flood-mode change is reflected on the next load instead of
waiting out the TTL. Tune the TTL up to cut MCMS load further, or set
`PFW_CACHE_TTL_SECONDS=0` to disable caching entirely. `POST /api/_cacheStats`
(authenticated) shows hits/misses/coalesced; `POST /api/_cacheClear` drops the
caller's MCMS-host snapshots.

## Deploy on a Debian 13 LXC (clone-to-run)

Files in `web/deploy/`: a systemd unit, an env template, and `update.sh`.

```bash
# --- as root on the LXC, once ---
apt update && apt install -y nodejs npm git      # Node 18+; or use NodeSource
adduser --system --group --no-create-home ponfw

git clone ssh://forgejo@int.git.vanvikinternet.no/Svorka/ponfw.git /opt/ponfw
cd /opt/ponfw
npm install --omit=dev --no-audit --no-fund      # installs tough-cookie, skips Electron

install -m 0644 web/deploy/pon-fleet-web.service /etc/systemd/system/
install -m 0640 web/deploy/pon-fleet-web.env.example /etc/pon-fleet-web.env
$EDITOR /etc/pon-fleet-web.env                    # set HOST / PFW_SECURE_COOKIE etc.

systemctl daemon-reload
systemctl enable --now pon-fleet-web
systemctl status pon-fleet-web
journalctl -u pon-fleet-web -f                    # logs
```

The repo lives at `/opt/ponfw` (root-owned, read-only to the service); the
service runs as the unprivileged `ponfw` user and writes nothing to disk.

**To update:** just re-pull and restart —

```bash
sudo /opt/ponfw/web/deploy/update.sh             # git pull + npm install + restart
```

## Behind Nginx Proxy Manager

Point an NPM **Proxy Host** at the server:

- Forward Hostname/IP: the LXC's address · Forward Port: `8080`
- Scheme: `http` (NPM terminates TLS; request an SSL cert in NPM)
- Enable **Block Common Exploits**; add your **Access List** for auth/IP
  allow-listing (this is your access control — the app itself has no user
  directory beyond MCMS login).
- **Websockets Support** on is harmless. The progress streams (bulk delete,
  FEC pre-flight, flood change) are plain NDJSON over HTTP and already send
  `X-Accel-Buffering: no`, which nginx/NPM honour, so they stream live with
  no extra config. If you ever see progress arrive only at the end, add to
  the host's **Advanced** tab:

  ```nginx
  proxy_buffering off;
  proxy_read_timeout 300s;
  ```

If NPM runs on a different host than this LXC, set `HOST=0.0.0.0` in
`/etc/pon-fleet-web.env` and restrict reachability to the NPM host via the
LXC firewall + the NPM access list.

## Security notes

- The server holds each logged-in user's **live MCMS session cookie in
  memory**. Run it behind HTTPS, keep `HOST=127.0.0.1`, and rely on the
  idle timeout. The session cookie is `HttpOnly`, `SameSite=Lax`, and
  `Secure` behind TLS.
- "Accept self-signed TLS certificate" disables verification **to MCMS**
  for that session only (same as the desktop app).
- There's no app-level user directory — anyone who can reach the page and
  has valid MCMS credentials can log in. Restrict network access at the
  proxy (mTLS / SSO / IP allow-list) if you need more than MCMS auth.
- Several operators running bulk operations at once multiply load on MCMS;
  the page-size-100 / timeout mitigations from the main `CLAUDE.md` §5
  still apply per session.

## What differs from the desktop app

- **CSV files download through the browser** instead of auto-saving to
  `~/Downloads` (a server can't write to each user's machine). Same
  filenames, same BOM/CRLF/quoted format.
- Firmware `.bin` and plan-CSV selection use the browser file picker.
- Everything else — views, filters, FEC logic, flood-mode rules, the
  dashboard and its drill-downs — is the shared renderer code.