Handbook

Enterprise — deployment (local-first)

Use this checklist when translating a developer laptop install into something operators can babysit nightly. Maintainer-only depth ships as enterprise-runbook-template.md on GitHub.

Updated 2026-07-06

Scenario

Operators need repeatable cold starts for python3 -m lenses, systemd/pm2 equivalents, paired reverse proxies, and backup policies while keeping POST surfaces non-public unless explicitly guarded.

Scenario

  Lane A ──► handoff ──► shared outcome
  Lane B ──► inspect / adapt ──► feedback

Freeze identity → tighten binds/OIDC → widen automation deliberately

Risks vs controls

Risk	Indicator	Recovery
Accidental egress when enabling LLMs or Fleet	Surprise outbound HTTPS from ops hosts	Clamp per LLM boundaries + binds from network binding
Public POST surface exposed	`/api/**` reachable without reverse-proxy auth	Re-enable OIDC sessions checkpoints; rerun auth smoke (`curl` rejects on missing tokens)
Upgrade drift	Mixed Python / wheel versions across machines	Freeze `git describe` artifact in change tickets; reinstall from Releases

Ownership (minimal)

Platform owner freezes identity + systemd unit content. Security reviewer signs off widen-to-prod decisions. Both attach logs from python3 -m lenses stderr and sanitized config headers to incident response timelines when anything regresses.

Steps

Step	Action	Notes
1	Freeze identity	Capture git SHA (`git describe`) + Python version documented in Install and run
2	Bind responsibly	Decide loopback-only vs bastion/proxy ingress per Enterprise — network binding
3	Session hardening	Enable Enterprise — OIDC sessions whenever `/api/**` crosses trust zones
4	Allowlists	Cross-check *`LENSES_ALLOW_` with Enterprise — actions allowlists and Configuration reference**
5	Backups	Align `.lenses-local/` + repos with Enterprise — backup and upgrades retention targets

Verify

Maintainers mirror the canonical matrix on GitHub — docs/strategy/env-matrix.yaml — with the handbook page Configuration reference inside this repo. Locally, pytest tests/test_env_matrix_docs.py asserts every variable from the matrix appears in that reference page.

Recover

Revert network binds to loopback, disable automation allowlists temporarily, redeploy binaries from GitHub Releases, then re-run Builders — auth and safety smoke tests prior to widening access again.

Forge Lenses