Add PWA support to the LifeTrac v25 base-station operator console

[Copilot]

The base-station web UI lacked a web app manifest and service worker, making it impossible to install as a PWA or operate offline. Addresses the question of whether HTTPS is required and how to achieve it on a LAN device, including a guided cert-distribution flow for phone operators. The base station now auto-generates a self-signed TLS certificate on first boot so no manual openssl command is needed.

New files

• web/manifest.json — Web App Manifest: display: standalone, landscape orientation, shortcuts to /map and /diagnostics
• web/sw.js — Service worker with targeted caching strategy:
  • Pre-caches login page + offline fallback on install
  • Cache-first for static assets (/static/*)
  • Network-first for navigation (preserves server-side session auth)
  • Passthrough for /api/* and /ws/* — never intercepted
• web/offline.html — Fallback page shown on network failure; matches dark console theme
• web/icons/icon.svg — Scalable tractor-silhouette icon (purpose: any maskable)
• web/setup.html — HTTPS bootstrap page (no login required): cert download button, per-OS install instructions (Android, iPhone/iPad, Windows, macOS, Linux), and a direct link to the HTTPS site

Modified files

• web/index.html — <link rel="manifest">, theme-color, Apple PWA metas, SW registration:

  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/sw.js', { scope: '/' });
  }

• web_ui.py — Four new root-level routes plus first-boot cert generation:
  • GET /sw.js — served at / (not /static/) with Service-Worker-Allowed: / and Cache-Control: no-cache so the SW controls all pages
  • GET /manifest.json — application/manifest+json
  • GET /cert.pem — serves the public TLS certificate as a download so phones can install it directly from the base station over plain HTTP; the private key is never exposed; returns 404 with guidance when no cert exists
  • GET /setup — serves web/setup.html with server-injected HTTPS port and cert-availability flag
  • _ensure_self_signed_cert() — called on startup; invokes openssl to generate a self-signed cert+key under /etc/lifetrac/ when neither file exists; sets the private key to chmod 600; no-ops if either file is already present so operator-supplied certs are never overwritten; logs a warning and continues if openssl is not installed
• BASE_STATION.md — Expanded HTTPS / PWA setup section with four options: self-signed cert + /setup page walkthrough, mkcert for automatic OS-trusted certs, HTTPS reverse proxy (nginx/Caddy), and localhost access. Includes a plain-HTTP vs HTTPS feature table.

Configuration

Three env vars control the cert bootstrap endpoints:

Variable	Default	Purpose
LIFETRAC_TLS_CERT	/etc/lifetrac/cert.pem	Path to the public cert served at /cert.pem and generated on first boot
LIFETRAC_TLS_KEY	/etc/lifetrac/key.pem	Path to the private key generated on first boot (never served)
LIFETRAC_HTTPS_PORT	8443	HTTPS port embedded into the /setup page link

HTTPS requirement

Full PWA install and offline caching require HTTPS or localhost. The operator console itself continues to work over plain HTTP; only Add-to-Home-Screen and the service worker are gated on a secure origin.

Quickest phone onboarding path

1. Start the base station — a self-signed cert is auto-generated at /etc/lifetrac/cert.pem and /etc/lifetrac/key.pem on first boot (requires openssl to be installed).

2. Start uvicorn with TLS:

export LIFETRAC_TLS_CERT=/etc/lifetrac/cert.pem
export LIFETRAC_HTTPS_PORT=8443
uvicorn web_ui:app --host 0.0.0.0 --port 8443 \
    --ssl-keyfile /etc/lifetrac/key.pem \
    --ssl-certfile /etc/lifetrac/cert.pem

3. On each phone, navigate to http://<ip>:8080/setup, download the cert, follow the per-OS install steps, then tap Open HTTPS Site and use Add to Home Screen for full-screen landscape PWA mode.

[dorkmo]

@copilot so we can create a self signed cert on the base station and achieve HTTPS on the local Ethernet network? We would like PWA to be used on cell phone browser to take advantage of the full screen mode.

[Copilot]

@copilot so we can create a self signed cert on the base station and achieve HTTPS on the local Ethernet network? We would like PWA to be used on cell phone browser to take advantage of the full scree...

Yes, exactly. Here's the workflow for getting full-screen PWA on a phone over LAN Ethernet:

1. Generate a self-signed cert on the base station (one-time):

openssl req -x509 -newkey rsa:2048 -nodes \
    -keyout /etc/lifetrac/key.pem \
    -out    /etc/lifetrac/cert.pem \
    -days 3650 \
    -subj "/CN=lifetrac-base" \
    -addext "subjectAltName=IP:192.168.1.42,DNS:lifetrac-base.local,DNS:localhost"

Replace 192.168.1.42 with the base station's actual LAN IP. Add more IP: entries if the address can vary.

2. Start uvicorn with TLS:

uvicorn web_ui:app --host 0.0.0.0 --port 8443 \
    --ssl-keyfile /etc/lifetrac/key.pem \
    --ssl-certfile /etc/lifetrac/cert.pem

3. Install cert.pem as a trusted CA on each phone (one-time per device):

• Android: Settings → Security → Install from storage → pick cert.pem → "CA certificate"
• iOS: AirDrop or email the .pem to the phone → Settings → General → VPN & Device Management → install → Settings → General → About → Certificate Trust Settings → toggle on

Once trusted, navigate to https://192.168.1.42:8443, dismiss any remaining warning, then use Add to Home Screen (Android: browser menu; iOS: Share → Add to Home Screen). The app opens in standalone mode (full-screen, no browser chrome) with landscape orientation locked — which is what the manifest already specifies.

The service worker will also activate after HTTPS is in place, enabling offline fallback if the base station goes briefly unreachable. Full details are in the HTTPS / PWA setup section of BASE_STATION.md.

[dorkmo]

@copilot could we add a method to download the cert from the HTTP website, then install the cert, then activate the HTTPS website? what other options are there to make the cert handling path easier for the end user?

[Copilot]

@copilot could we add a method to download the cert from the HTTP website, then install the cert, then activate the HTTPS website? what other options are there to make the cert handling path easier fo...

Added in commit Add cert download endpoint and /setup bootstrap page for phone PWA install.

What's new:

GET /cert.pem — serves the public TLS certificate as a download directly from the base station over plain HTTP. The private key is never exposed; the endpoint returns 404 with an openssl hint if no cert has been generated yet.

GET /setup — a no-login-required bootstrap page at http://<base-station-ip>:8080/setup that walks the operator through the full flow:

1. Download button for lifetrac-cert.pem (active only when the cert exists; shows the openssl generation command otherwise)
2. Per-OS install tabs — Android, iPhone/iPad, Windows, macOS, Linux — each with numbered steps
3. Open HTTPS Site button that links directly to the correct https://<host>:8443/ URL, built from the current browser hostname and the LIFETRAC_HTTPS_PORT env var (default 8443)

Two env vars control the page:

• LIFETRAC_TLS_CERT — path to the cert file (default /etc/lifetrac/cert.pem)
• LIFETRAC_HTTPS_PORT — HTTPS port (default 8443)

Other cert options added to BASE_STATION.md:

• mkcert (new Option B) — if mkcert is installable on the base station, it auto-trusts the CA in the OS cert store; phones only need the rootCA.pem once and then trust all mkcert-signed certs forever.
• Caddy tls internal (Option C) — automatic cert via a reverse proxy.
• localhost (Option D) — no cert needed if the operator tablet is the base-station device itself.

[dorkmo]

@copilot can we have the base station check if there is an existing cert on startup, and if there is no cert, create one? this would only need to happen on first boot after install?

[Copilot]

@copilot can we have the base station check if there is an existing cert on startup, and if there is no cert, create one? this would only need to happen on first boot after install?

Done in commit Auto-generate self-signed TLS cert on first boot if none exists.

On startup, _startup() now calls _ensure_self_signed_cert() (via run_in_executor so it doesn't block the event loop). It generates a cert+key under /etc/lifetrac/ using openssl the first time the server starts with no existing files, then never touches them again so any operator-supplied cert is never overwritten. The private key gets chmod 600.

Key details:

• No-op conditions: skips if either CERT_PATH or KEY_PATH already exists — so upgrading or replacing the cert is as simple as deleting both files and restarting.
• Paths: configurable via LIFETRAC_TLS_KEY / LIFETRAC_TLS_CERT env vars (defaults: /etc/lifetrac/key.pem and /etc/lifetrac/cert.pem).
• openssl absent: logs a warning and continues — the server still starts over plain HTTP.
• Validity: CERT_VALIDITY_DAYS = 3650 (~10 years), appropriate for an embedded device that won't be rotated frequently.

After auto-generation, the operator can point their phone to http://<base-ip>:8080/setup as before, download the cert, install it, and add the HTTPS site to the home screen — no manual openssl command needed.