openkbs.json reference
Every openkbs.json field explained: projectId, region, postgres engines, storage, mqtt, email, mail, functions, site, spa, redirects, security headers, caching.
openkbs.json at the project root declares which elastic services a project uses, in which AWS region, and which functions and static site to deploy. openkbs deploy provisions everything declared in it.
Example
{
"projectId": "a0ebcf5d1fa5",
"region": "us-east-1",
"postgres": true,
"storage": { "cloudfront": "media" },
"mqtt": true,
"email": true,
"functions": [
{ "name": "api", "runtime": "nodejs24.x", "memory": 512, "timeout": 30 },
{ "name": "cleanup", "schedule": "rate(1 hour)", "timeout": 900 }
],
"site": "./site",
"spa": "/app/index.html"
}Fields
| Field | Description |
|---|---|
projectId | Project short ID. Set automatically when the project is created. |
| (overlay) | openkbs.local.json (gitignored) is merged over openkbs.json, top-level keys only. Use it when one repo serves two projects: the staging id is committed, and the production checkout holds { "projectId": "<prod-id>" } locally. |
region | AWS region: eu-central-1, us-east-1, or ap-southeast-1 |
postgres | true for Neon (default), or { "engine": "aurora" } for Aurora Serverless v2. Aurora accepts optional scaling bounds: { "engine": "aurora", "minACU": 0.5, "maxACU": 8 }. { "engine": "flex" } selects Postgres Flex (beta). See the Elastic services overview for the differences between engines. |
storage | Object with cloudfront prefix for CDN distribution |
mqtt | true to enable real-time WebSocket messaging |
email | true to enable email sending (SES) |
mail | true to enable mail hosting (mailboxes + webmail); mailboxes are managed via the CLI, not this file |
functions | Array of function definitions to deploy (see below) |
site | Path to static site directory |
spa | SPA fallback path (all 404s serve this page with status 200). This is what makes clean-URL client routing work, so SPAs should use a normal path router (BrowserRouter) rather than a hash router. For an app under a sub-path, set it to that app's index ("/admin/index.html") and build the app with an absolute base (/admin/). |
redirects / notFound | Real 301s at the CloudFront edge (www→apex, clean URLs, custom rules) and real-404 error pages — the SEO toolkit for static sites. See Site redirects. |
securityHeaders | Opt-in. true = safe preset (HSTS, nosniff, Referrer-Policy) at the CloudFront edge. An object adds csp, permissionsPolicy, frameOptions for an A grade on securityheaders.com. See Site security headers before enabling; a wrong CSP silently breaks the site. |
cacheControl | Per-path Cache-Control overrides for the static site ({ "/images/**": "public, max-age=86400" }). Defaults are already safe — hashed js/css/fonts immutable, HTML no-store, unhashed js/css/txt/xml/json 1h, everything else 1 day — so only add this when you need something else. _headers files are ignored. See Site Cache-Control. |
backend | "standard" runs the project's functions and Postgres on OpenKBS Cloud instead of AWS Lambda/Neon; absent or "elastic" is the default. See Standard backend. |
Changing the postgres engine in openkbs.json does not switch an existing database; openkbs deploy reports this. Neon → Aurora uses openkbs postgres migrate.
Function definitions
Each entry in functions describes one Lambda function. The function's code lives in ./functions/<name>/ with an index.mjs entry point that exports a handler.
| Field | Description |
|---|---|
name | Function name; must match the folder under ./functions/. |
runtime | Lambda runtime, e.g. nodejs24.x. Functions run on Node.js 24.x. |
memory | Memory in MB. This is the default that openkbs fn deploy -m <mb> overrides. |
timeout | Timeout in seconds (openkbs fn deploy -t <sec> overrides it). |
schedule | Schedule expression for a cron-style function, e.g. "rate(1 hour)" or "cron(0 9 * * ? *)" (openkbs fn deploy -s <expr> sets it too). |
Auto-injected environment variables
Every deployed function receives these environment variables automatically:
DATABASE_URL-- Postgres connection string (ifpostgres: true)STORAGE_BUCKET-- S3 bucket name (ifstorageconfigured)OPENKBS_PROJECT_ID-- Project short IDOPENKBS_API_KEY-- Secret key for calling OpenKBS platform APIs
Custom variables come from a .env file in the function directory or from openkbs fn deploy -e KEY=VALUE flags; see the CLI reference.