theta-suite/docs/screenshots.md

title

title
Updating gitpages screenshots

Updating gitpages screenshots

How to refresh the docs/images/*.png screenshots across sso-manager-node, proxy, jump-host, and theta-env's own docs. This comes up periodically as the UI changes — this doc + docs/fixtures.md + bootstrap/seed-demo-users.sh exist so it doesn't have to be re-figured-out from scratch each time. Once fixtures match docs/fixtures.md, you only need to re-screenshot pages whose UI actually changed since the last pass.

1. Seed realistic demo data

Screenshots should show a believable homelab/small-business setup, not empty tables or test/vaulttest accounts, and the same cast every time — see docs/fixtures.md for the canonical list (exact users, groups, hosts, passwords) and keep it in sync with what's actually seeded. Seed users + groups with:

docker cp bootstrap/seed-demo-users.sh sso-manager:/tmp/seed-demo-users.sh
docker compose exec -T sso-manager bash /tmp/seed-demo-users.sh

Idempotent — safe to re-run, existing entries are skipped. Proxy hosts have no equivalent script yet — add them by hand through the Proxy UI (Hosts → Add host), following docs/fixtures.md's host table exactly (same hostnames, targets, auth config every time).

2. Logging in without fighting SSO/TLS

The SSO's own domain goes through real DNS + a production reverse proxy in front of this dev stack (see docs/fixtures.md → Domain) — logging in via "Log in with SSO" from Proxy/Jump-host round-trips through that whole path and can hit stale-cookie/redirect-loop artifacts in an automation browser profile that a real browser wouldn't. Don't fight this — every app ships a local anti-lockout admin for exactly this situation. Read the password straight out of the mounted secrets:

# SSO Manager admin (bootstrap account, uid "admin")
node -e "console.log(require('./config/sso-secrets.js').bootstrap.adminPass)"

# Proxy — username proxyadmin2
node -e "console.log(require('./config/proxy-secrets.js').auth.localAdminPass)"

# Jump-host — username jumpadmin
node -e "console.log(require('./config/jump-secrets.js').auth.localAdminPass)"

Log in at http://localhost:<port>/login for each app — plain HTTP on the mapped port, no cert/cookie issues at all. Ports come from setup.env (operator-configurable) — check it rather than assuming defaults; e.g. this deployment maps the Proxy UI to 3010 (MGMT_PORT), not the usual 3000.

Don't touch the login form if it autofills a real saved username/password (Chrome profile password manager) — clear the fields and type the local admin credentials above instead. Never submit a real saved credential on the user's behalf.

A freshly-bootstrapped admin account hits the onboarding flow (accept ToS, enter a DOB) before the rest of the UI is usable — expect that right after a from-scratch rebuild.

3. Known gotcha: stale app.modal.js in the browser cache

If "Add host" (or any app.modal-based modal) opens with tabs/fields but no Save/Cancel footer, check the console for TypeError: app.modal.on is not a function. That means the browser has an HTTP-cached copy of @simpleworkjs/frontend/lib/app.modal.js from before a method (on, showTab, etc.) was added — curl-ing the same URL returns the current file, so it's a caching artifact, not a real app bug. Fix it in-page without a full hard-reload cycle:

// via the browser automation JS tool, in the page context
const res = await fetch('/static-modules/@simpleworkjs/frontend/lib/app.modal.js', {cache: 'reload'});
await res.text(); // {cache:'reload'} both bypasses AND refreshes the cache entry

Then reload the page normally — the fresh file sticks for the rest of the session.

4. Capture screenshots

Use save_to_disk: true on the browser screenshot action so files land on disk instead of just being viewed inline. One screenshot per doc image:

File	Page
sso-manager-node/docs/images/dashboard.png	SSO Catalog (/)
sso-manager-node/docs/images/users.png	SSO Users → People (/users)
sso-manager-node/docs/images/directory.png	SSO Directory (/directory)
sso-manager-node/docs/images/groups.png	A user's profile → "My Groups" tab
sso-manager-node/docs/images/oauth-clients.png	Directory → an oauth resource → Edit → Details tab
proxy/docs/images/hosts.png	Proxy Hosts list (/hosts)
proxy/docs/images/host-auth-basic.png	Edit a basic-auth host → Authentication tab
proxy/docs/images/host-auth-sso.png	Edit an SSO-auth host → Authentication tab
proxy/docs/images/load-balancing.png	Edit a host with "Additional Targets" filled in → General tab
jump-host/docs/images/login.png	Jump-host login page
jump-host/docs/images/dashboard.png	Jump-host dashboard, logged in as a real fixture user (e.g. dkim via SSO) with an actual access grant — not the jumpadmin local admin, whose host list isn't representative. See docs/fixtures.md → Jump-host access.
jump-host/docs/images/sessions.png	Jump-host active sessions
jump-host/docs/images/audit.png	Jump-host audit log
theta-env/docs/images/sso-dashboard.png	same as SSO Catalog above
theta-env/docs/images/proxy-hosts.png	same as Proxy Hosts above
theta-env/docs/images/jump-dashboard.png	same as Jump-host dashboard above

5. Where to save them

Only update the top-level active clones — /home/william/dev/theta42/{sso-manager-node,proxy,jump-host,theta-env} (all on master). The copies nested under theta-env/sso-manager-node, theta-env/proxy, theta-env/jump-host are git submodules pinned to a release tag (HEAD detached at vX.Y.Z) — those update automatically the next time theta-env's release/tag-bump workflow rolls the submodule pointer forward, not by hand-editing the pinned checkout.

convert screenshot.jpg /home/william/dev/theta42/<repo>/docs/images/<name>.png

(convert from ImageMagick — the browser tool saves JPEGs, but the repos track PNGs.)

Commit each repo separately, same as any other change to that component.