Operator runbook

Day-to-day operations for an edssa-server-ce deployment.

Deployment topologies

Sidecar (recommended)

┌──────────── Pod / VM ────────────┐
│  edssa-server-ce :8080  ──▶ app   │
│                                   │
└─── Ingress :80 / :443 ────────────┘

edssa-server-ce listens on :8080; your app listens on something the sidecar reaches over loopback. An external load balancer terminates TLS and forwards :443 → :8080.

This is the samples/nginx-quickstart

samples/k8s-helm pattern. CE supports nothing else by design — multi-tenant gateway patterns are Enterprise.

Behind a TLS edge

edssa-server-ce speaks plain HTTP. Put Caddy / nginx / a managed load balancer in front for TLS:

client ──TLS──▶ Caddy ──HTTP──▶ edssa-server-ce ──HTTP──▶ app

The CE binary does not verify TLS itself — it relies on the trust boundary at the TLS-terminating proxy. If you need mTLS or a cryptographic edge channel, layer it at the edge.

Phase 8 ships the same seed-provisioning bridge as Phase 1 (ADR-003): the operator generates seeds locally, encrypts at rest with age, and copies to the box. Phase 6 (Enterprise-only) adds ML-KEM onboarding (F-07) and makes seeds ephemeral.

# 1. Generate
LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom \
  | head -c 1024 > seeds/fleet-demo.seed

# 2. Encrypt at rest against the box's age recipient
age -R seeds/box.age-pub \
    -o seeds/fleet-demo.seed.age seeds/fleet-demo.seed

# 3. scp to the box
scp seeds/fleet-demo.seed.age ops@box:/opt/edssa/secrets/

# 4. Operator decrypts at container start; plaintext stays on tmpfs

For the CE Helm chart, the seed lives in a Kubernetes Secret the chart references by name (not value) — operators provision it out-of-band so it never appears in helm get values.

Rotating the seed

CE first cut does not run a ratchet — ActiveEdssaState is derived from the seed at boot and never advances. Rotating the seed therefore means rotating clients in lockstep:

Stop accepting new sessions (out-of-band signal, e.g. set a feature flag in your app).
Provision the new seed everywhere.
Restart edssa-server-ce.
Restart clients with the new seed.

Enterprise’s ratchet driver lets you publish new state under a running verifier without disrupting in-flight requests. CE sidesteps the complexity at the cost of a brief restart window.

Observability

CE intentionally ships minimal observability — no Prometheus endpoint, no transparency log, no F-20 ring buffer. What you get:

Tracing logs to stdout in JSON. Filter via RUST_LOG. Audit emissions follow the tier:
- silent → no per-request emission.
- errors → info-level emission on every reject.
- result → info-level emission on every accept AND reject.
/healthz for liveness / readiness.

If you need metrics + traces + Tier-4 Merkle audit, run the Enterprise binary.

Common operations

“How do I add a fleet?”

You don’t. CE is one fleet per process. Spin up another CE binary for the second fleet, or upgrade to the Enterprise build for multi-fleet routing.

“How do I tighten the security posture?”

Switch the manifest preset:

preset = "high-security" → T = 44 (no margin; every secret byte must match).
Drop sub_id_range to a tight band, e.g. [1, 8], so a compromised sub-ID claim from one client can’t pose as another.

Per-byte tightening:

Set chaff_C higher → smaller R_eff but smaller observable attack surface.
Set threshold_T close to R_eff → less resilience, more bits of effective secrecy.

“How do I temporarily disable enforcement?”

Don’t. If you need a bypass, put a feature flag in your app and route the bypassed traffic to the upstream directly — never wave the sidecar through.

“What happens if the seed file disappears?”

edssa-server-ce fails to start with seed_path does not exist. The previous binary keeps running; the next restart fails. Tie the restart loop into your platform’s “stop accepting new connections” behaviour so a missing seed = service degraded, not service down.

Patent advisory

EdSSA is patent-pending. The Community Edition ships under BSL 1.1 with an explicit non-revocable patent grant for permitted use (non-commercial OR commercial ≤ $1M ARR). See Patent advisory.

EdSSA Community Edition