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

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 — keep on localhost behind a proxy
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)

Reverse proxy

Terminate TLS at the proxy and forward to 127.0.0.1:8080. Disable response buffering so the NDJSON progress streams (bulk delete, FEC pre-flight, flood change, …) arrive live.

Caddy:

mcms-tools.example.net {
    reverse_proxy 127.0.0.1:8080 {
        flush_interval -1          # don't buffer streamed responses
    }
}

nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;           # stream NDJSON progress live
    proxy_read_timeout 300s;       # bulk ops can run a while
}

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.