DUNGEONS-34: simplify external HTTPS proxy setup

Co-authored-by: multica-agent <github@multica.ai>

README.md

@@ -24,15 +24,58 @@ The terminal prints the local URL, LAN URLs when available, and the setup-token
 
 Press **Ctrl+C** to stop the app and any build subprocesses. Accounts remain in `data/`. The first login page creates the administrator account using the token from `data/setup-token`. The administrator cannot be deleted; resetting its password ends its sessions.
 
-For HTTPS behind a reverse proxy, set `WEBKA_ORIGIN` to the exact public origin before launching. This override disables automatic HTTP aliases; optional `WEBKA_ALLOWED_ORIGINS` is a comma-separated list of additional trusted exact origins. Browser capture on another LAN device still requires trusted HTTPS; plain LAN HTTP permits viewing only.
+For an existing HTTPS proxy, use the homepage setting below. Browser capture on another LAN device still requires a trusted HTTPS address.
 
 For frontend hot reload, the separate development workflow remains available: run `cargo run --manifest-path backend/Cargo.toml` and `npm --prefix frontend run dev` in separate terminals, then open `http://localhost:3000`.
 
+## Existing Nginx Proxy Manager on another machine
+
+Set just the address you want to open in a browser (the address served by NPM):
+
+```sh
+npm run dev:all -- --homepage https://camera.example.com --port 3002
+```
+
+Replace `https://camera.example.com` with your actual HTTPS domain or IP, including a public port if needed. A bare hostname/IP is treated as HTTPS. A trailing slash is accepted; hosting under a subpath is not supported.
+
+This mode automatically:
+
+- Listens on `0.0.0.0` so the other machine can reach Webka (unless you explicitly set `--host`).
+- Serves the frontend and API over **HTTP** on the chosen internal port; your existing NPM handles HTTPS.
+- Uses the homepage for QR/share links, secure cookies, and allowed request origins.
+- Disables mDNS, even if `WEBKA_MDNS=1` was previously set. No Caddy, `.local` hostname, or certificates on the Webka computer are needed.
+
+In **Nginx Proxy Manager → Proxy Hosts**, configure:
+
+| Setting | Value |
+|---|---|
+| Domain Names | Your homepage hostname, e.g. `camera.example.com` |
+| Scheme | `http` |
+| Forward Hostname / IP | The LAN IP of the **Webka computer**, e.g. `192.168.1.50` |
+| Forward Port | `3002` (or your `--port`) |
+| Websockets Support | Enabled |
+| SSL | Select your existing trusted certificate; enable Force SSL |
+
+Open the homepage HTTPS address on both the host and viewer. Its hostname must resolve to the **NPM machine**, and NPM must be able to reach the Webka machine's LAN IP/port. The homepage is the browser-facing address, not the internal upstream address. For an HTTPS IP address, the certificate must cover that IP and NPM must route it to Webka. See the [official NPM guide](https://nginxproxymanager.com/guide/) and [WebSocket proxy support](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/develop/backend/templates/proxy_host.conf).
+
+To save the address, create `webka.config.json` in the repository root (or copy `webka.config.example.json`):
+
+```json
+{
+  "homepage": "https://camera.example.com",
+  "port": 3002
+}
+```
+
+Then start with only `npm run dev:all`. `homepage` alone is sufficient if the internal port is the default `3000`. Optional `host` and `port` may also be saved; command-line options override the file. Restart to apply changes. This machine-specific file is ignored by Git. Homepage mode takes priority over legacy `WEBKA_ORIGIN`, `WEBKA_ALLOWED_ORIGINS`, and `WEBKA_MDNS` values.
+
+Legacy manual proxy setup via `WEBKA_ORIGIN` and `WEBKA_ALLOWED_ORIGINS` remains supported when no homepage is configured. The launcher does not configure NPM or provision its certificates. The proxy carries page/API/signaling traffic; WebRTC media remains peer-to-peer on the LAN.
+
 ## Use on your LAN
 
 A webpage **cannot launch a Rust server** on the device running its browser. Start the Rust service once on a computer on your LAN. A phone, tablet, or computer can then sign in as the administrator and act as the capturing host. This repository does not include a native iOS/Android service wrapper. Each service instance owns its account database.
 
-Browser camera/screen APIs require a **secure context**: localhost on the service machine, or trusted HTTPS on a LAN device. LAN HTTP IP addresses cannot capture camera/screen. For LAN use, use the included `Caddyfile.example` with a trusted local certificate:
+Browser camera/screen APIs require a **secure context**: localhost on the service machine, or trusted HTTPS on a LAN device. LAN HTTP IP addresses cannot capture camera/screen. If you already have an HTTPS proxy, use the homepage mode above. If you do not, the included `Caddyfile.example` is an optional alternative with a trusted local certificate:
 
 1. Point `webka.local` at the service computer, through mDNS (`WEBKA_MDNS=1`), your router, or a hosts entry. `.local` resolution and multicast support vary by network/device; a local DNS name or IP with a matching trusted certificate also works.
 2. Configure Caddy with the example below, and install/trust Caddy’s local CA on **every** client device. Keep this CA private.
@@ -93,6 +136,8 @@ cargo build --manifest-path backend/Cargo.toml
 python3 scripts/smoke.py
 # Optional POSIX integration test: reserves port 3002, tests startup/restart/stop.
 python3 scripts/test-launcher.py
+# Optional POSIX HTTPS proxy integration test (requires OpenSSL).
+python3 scripts/test-proxy.py
 ```
 
 `test:install` checks the frontend lockfile from a temporary folder without `node_modules`. When updating dependencies, run it with both npm 10 (bundled with Node 22) and npm 11; root `npm install` only installs the launcher package and does not repair the frontend lockfile.