Runbook: Form Engine

Runbook: Form Engine

Last updated: 2026-03-30 Service owner: ODS Platform Team Pipeline status: STAGING_VERIFIED

1. Service Overview

Form Engine provides dynamic form schema definition, form instance management, and submission handling for the ODS Platform. It supports JSON schema-based form definitions, per-tenant isolation, and publishes events to Redpanda. Supports both RS256 (production) and HS256 (dev) JWT modes.

Property Value
Language Rust (Actix-web)
Container port 8084
DB schema forms on ods database
Event bus Redpanda (redpanda:9092)
Coolify app UUID ng0gg8wgksccsg4coksow0gg

2. Health Check

Endpoint: GET /health Expected response: HTTP 200

curl -sf https://form-engine.staging.orbusdigital.com/health

3. Staging URL

https://form-engine.staging.orbusdigital.com

4. Environment Variables

Variable Required Description
DATABASE_URL Yes postgres://ods:***@ods-postgres:5432/ods?search_path=forms
SERVICE_PORT No Listen port (default 8084)
REDPANDA_BROKERS No Kafka broker address
OID_JWKS_URL Prod https://oid.staging.orbusdigital.com/.well-known/jwks.json
LOG_LEVEL No Log level (default info)
CORS_ALLOWED_ORIGINS No Comma-separated allowed origins
MAX_BODY_SIZE_BYTES No Max request body (default 1MB)
JWT_RSA_PUBLIC_KEY Prod RSA public key for RS256
JWT_ISSUER Prod https://oid.staging.orbusdigital.com
JWT_AUDIENCE Prod ods-platform
JWT_ALLOW_HS256 Dev only Enable HS256 mode (NEVER in production)
JWT_SECRET Dev only HS256 secret

Note: Form Engine requires a GITHUB_TOKEN build arg in the Dockerfile if it fetches private Rust crate dependencies (e.g., ods-common).

5. How to Deploy

Via Coolify API

source ~/.env.adlc 2>/dev/null
curl -sf -X POST "https://app.coolify.io/api/v1/applications/ng0gg8wgksccsg4coksow0gg/restart" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

Git-based deploy

Push to the staging branch of jniox/form-engine. Coolify source: app-jniox-ods (source_id: 2).

6. How to Check Logs

# On srv-staging (35.195.54.220):
docker logs --tail 200 -f $(docker ps -qf "label=coolify.applicationId=ng0gg8wgksccsg4coksow0gg")

7. Common Issues and Fixes

Issue: Build fails with “could not find ods-common crate”

Symptom: Docker build fails fetching private dependency.

Fix: Ensure GITHUB_TOKEN build argument is set in Coolify with a valid GitHub PAT that has repo scope.

Issue: Security concerns flagged in review

Context: Security review noted concerns. Check ~/dev/ops/reviews/form-engine/ for details. Key areas: input validation on form schemas, CORS configuration.

Issue: HS256 mode accidentally enabled in staging

Symptom: Security review flags weak JWT mode.

Fix: Remove JWT_ALLOW_HS256 and JWT_SECRET from Coolify env vars. Set JWT_RSA_PUBLIC_KEY, JWT_ISSUER, and JWT_AUDIENCE instead.

8. How to Restart

docker restart $(docker ps -qf "label=coolify.applicationId=ng0gg8wgksccsg4coksow0gg")

9. Dependencies

Dependency Type Details
PostgreSQL 17 Database ods-postgres:5432, schema forms
Redpanda Event bus redpanda:9092
OID Auth JWKS endpoint for JWT verification
ods-common Build dep Shared Rust library crate (requires GitHub token at build time)

10. Monitoring / Alerting