Skip to content
Developer docs

Operations

Run Promptsheon responsibly: configure production, verify readiness, observe behaviour, and recover from failure.

Production baseline

Run the API behind TLS termination and keep the database, CAS directory, and deployment secrets on persistent storage. Production refuses unsafe defaults for authentication, CORS, webhook signing, and SCIM.

PROMPTSHEON_NODE_ENV=production
PROMPTSHEON_AUTH=true
PROMPTSHEON_JWT_SECRET=<at-least-32-characters>
PROMPTSHEON_CORS_ORIGIN=https://console.example.com
PROMPTSHEON_WEBHOOK_SECRET=<random-secret>
PROMPTSHEON_SCIM_TOKEN=<random-secret>
PROMPTSHEON_DB_PATH=/var/lib/promptsheon/promptsheon.db
PROMPTSHEON_CAS_PATH=/var/lib/promptsheon/cas

Health, readiness, and shutdown

Use /api/health for liveness and /api/ready for traffic admission. A failed database probe returns 503 rather than presenting a false healthy response. Send SIGTERM during deploys so schedulers, SSE connections, and the database close cleanly.

What to monitor

  • Readiness failures and database quick-check latency.
  • Request duration and error rate grouped by route and request ID.
  • LLM provider latency, retries, failures, token cost, and fallback usage.
  • Evaluation score movement before and after release promotion.
  • Audit-chain verification and webhook replay/rejection events.
  • CAS and SQLite disk usage, backup freshness, and migration status.

Backup and recovery

Back up the SQLite database and CAS directory together. Test restoration into an isolated instance, run migrations, verify readiness, and compare a known content hash before routing traffic. A backup that has never been restored is an assumption, not a recovery plan.

Troubleshooting

  1. Check /api/ready and capture the X-Request-Id.
  2. Inspect structured server logs for that request ID.
  3. Verify the provider secret, model, endpoint, timeout, and allowed outbound host policy.
  4. Check the release audit trail before retrying a promotion.
  5. Roll back to the last verified content hash if user impact is ongoing.