Skip to content

OPERATIONS.md

Latest commit

 

History

History
77 lines (57 loc) · 2.13 KB

OPERATIONS.md

File metadata and controls

77 lines (57 loc) · 2.13 KB

Operations Runbook

Deploy checklist

  1. Set signing keys:
    • RECEIPT_SIGNING_PRIVATE_KEY_PEM_B64
    • RECEIPT_SIGNING_PUBLIC_KEY
  2. Set identity metadata:
    • RECEIPT_SIGNER_ID
    • SERVICE_NAME, SERVICE_VERSION
  3. If using ENS verification:
    • ETH_RPC_URL
    • VERIFIER_ENS_NAME
    • ENS_SIGNER_TEXT_KEY
    • ENS_SIG_PUB_TEXT_KEY
    • ENS_SIG_KID_TEXT_KEY
  4. Set safety limits (FETCH_TIMEOUT_MS, FETCH_MAX_BYTES, VERIFY_MAX_MS).
  5. Restrict outbound domains with ALLOW_FETCH_HOSTS where possible.

Post-deploy validation

curl -s "$BASE_URL/health" | jq .
curl -s "$BASE_URL/debug/env" | jq .

Expected:

  • ok=true
  • signer_ok=true
  • expected enabled_verbs
  • expected timeouts/cache settings

Schema prewarm sequence

curl -s -X POST "$BASE_URL/debug/prewarm" \
  -H 'content-type: application/json' \
  -d '{"verbs":["fetch","parse","summarize","classify"]}' | jq .

curl -s "$BASE_URL/debug/validators" | jq .

Repeat validator polling until required verbs appear under cached.

Verification troubleshooting

no public key available

  • Set RECEIPT_SIGNING_PUBLIC_KEY (ed25519:<base64>) or use ENS verification with:
    • ETH_RPC_URL
    • VERIFIER_ENS_NAME
    • valid cl.sig.pub and cl.sig.kid TXT values on signer ENS name.

validator_not_warmed_yet with HTTP 202

  • Expected when VERIFY_SCHEMA_CACHED_ONLY=1 and schema validator is cold.
  • Trigger /debug/prewarm and retry /verify?schema=1.

schema fetch failed

  • Confirm schema host reachability from runtime environment.
  • Check SCHEMA_HOST, SCHEMA_FETCH_TIMEOUT_MS, outbound egress rules.

Recommended observability

At minimum, capture and alert on:

  • HTTP 5xx rate by endpoint and verb.
  • /verify latency and timeout count.
  • fetch timeout/error rates.
  • cold-validator 202 rate after deploy.
  • cache sizes from /debug/validators.

Hardening notes

  • Keep CORS policy constrained if this service is not intended for broad browser access.
  • If internet fetch is not required, disable fetch verb via ENABLED_VERBS.
  • Consider process isolation or egress proxy for stricter SSRF containment.