Configuration

How configuration is read#

src/runtime/config.ts reads the environment once at startup and validates it as a whole. It reports every problem in one message that starts with the environment is invalid:, and any value it cannot understand stops the process. The behavioral rules are in spec §14.

packages/data/.env.example lists the process variables with development values that are not secrets. Getting started copies it to .env, which Bun loads at startup.

The Required column uses these values: always means every process role; api means roles api and all; worker means roles worker and all.

Process#

Database#

The registry and delivery pools hold five connections each; their size is not configurable.

Deployment artifacts#

Manifests and policies are immutable for the life of a process, and their version is their content digest.

Access#

Budgets#

None of these variables is required. A request's effective timeout is the smallest applicable budget. A local timer alone never cancels a statement: the statement and transaction timeouts do.

Worker#

Observability#

The log level is DATA_LOG_LEVEL (Process).

Production checks#

With DATA_ENVIRONMENT=production, startup also refuses:

1. a DATA_DATABASE_URL or DATA_REGISTRY_DATABASE_URL on a remote host without an sslmode= parameter (use sslmode=require); the hosts 127.0.0.1, localhost, ::1 and postgres count as local,
2. a DATA_ACCESS_URL that does not start with https://,
3. a credential that the repository publishes: the file of the access context or the file of the cursor key that holds a value of deploy/fixtures/secrets is refused, and so is a password of a role that the repository publishes. The repository is public, and a deployment that mounts the fixtures holds a credential that everybody knows.

Role privileges, schema drift and the access context version are checked by readiness in every environment (Operations).

Operator commands#

Operator credentials never appear in the API's environment; each command reads only what it needs.

The procedures that use them are in Operations.

Bindings file#

DATA_GATEWAY_BINDINGS_FILE is JSON of the form {"version": 2, "bindings": [...]}, with at most 100 bindings. The matching and verification rules are in spec §4.1.

{
  "version": 2,
  "bindings": [
    {
      "id": "data-api",
      "host": "api.gateway.test",
      "upstreamPathPattern": "/ws/{workspaceId}/v1/*",
      "routeId": "data-api",
      "identity": {
        "version": "v5",
        "algorithm": "ES256",
        "publicKeyFile": "./secrets/identity.public.pem"
      }
    }
  ]
}

A legacy route names its format explicitly, and DATA_LEGACY_IDENTITY must permit it:

"identity": {
  "version": "v4",
  "algorithm": "HS256",
  "identityKeyFile": "./secrets/identity.key"
}

Moving a deployment off the legacy format is a procedure in Operations.

Collection manifest#

DATA_SCHEMA_BUNDLE_FILE is UTF-8 JSON, at most 1 MiB, validated against a strict schema that refuses unknown properties. How to design a collection is in Modeling.

{
  "version": 1,
  "schemaVersion": "articles-v1",
  "collections": [
    {
      "key": "articles",
      "table": "data.articles",
      "versions": { "table": "data.article_versions" },
      "label": "Articles",
      "fields": {
        "title": {
          "type": "string",
          "required": true,
          "nullable": false,
          "maxLength": 240
        }
      },
      "search": { "fields": ["title"], "config": "english" },
      "relations": {
        "category": {
          "target": "categories",
          "type": "many-to-one",
          "field": "category_id"
        }
      }
    }
  ]
}

Policy bundle#

DATA_POLICY_BUNDLE_FILE is UTF-8 JSON, at most 1 MiB, with at most 1000 policies. The same format is published per workspace with bun run policy -- publish (Modeling).

{
  "version": 1,
  "policies": [
    {
      "id": "edit-own-articles",
      "permission": "content.editor",
      "collection": "articles",
      "action": "update",
      "where": { "created_by": { "_eq": "$principalId" } },
      "check": { "created_by": { "_eq": "$principalId" } },
      "fields": ["title", "body"]
    }
  ]
}

Predicates use the filter grammar and may use $principalId, $tenantId and $workspaceId. How policies combine is in spec §8.