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.
Runbook · Updated
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.
Operator deployment checkpoints
How platform and security lanes coordinate before widening binds, proxies, or automation surfaces.
- ScenarioFrames the local-first handoff from developer install to operator-managed deployment.
- Lane APlatform ownership lane for identity freeze and operational handoff.
- handoffTransfers frozen git SHA, Python version, and unit definitions to ops.
- shared outcomeAgreed operational baseline ready for deliberate network widening.
- Lane BSecurity review lane that inspects trust-zone crossings before sign-off.
- inspect / adaptReviews binds, OIDC checkpoints, and allowlists against enterprise controls.
- feedbackReturns findings or approval before access is widened again.
Scenario
Lane A ──► handoff ──► shared outcome
Lane B ──► inspect / adapt ──► feedbackRisks 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.