Configure DVARA safely

A configuration change can alter which models an application reaches and which governance controls apply. Start by choosing the source that owns the setting, then verify the effect on the running gateway.

Which configuration source should you use?

What you run	Use this source	When the change takes effect
Open Source distribution	gateway.yaml for providers, routes, workspaces, keys, policy, and supported local controls	After you restart the gateway
Either runtime	Environment variables or startup arguments for process settings and secrets	After you restart the process
Enterprise platform	DVARA Flightdeck for workspaces, routes, policy, credentials, budgets, and other managed configuration	About 10 seconds at the default settings, when the next signed bundle reaches each gateway
Enterprise platform at first boot	bootstrap.yaml on Flightdeck for initial workspaces, API keys, and routes	During Flightdeck startup; existing entries are skipped
Enterprise fleet under change control	Flightdeck Import / Export for a reviewed configuration snapshot	After preview and apply

The Open Source distribution reads one local file and has no Flightdeck or database. The Enterprise platform stores managed configuration centrally and distributes changes to its gateway pods. From 1.8.2 only Flightdeck connects to PostgreSQL; each gateway receives configuration as a signed bundle from Flightdeck and has no database of its own. Do not use gateway.yaml as a second source of managed fleet configuration.

Configure the Open Source distribution

Put gateway.yaml beside the runnable JAR, or set DVARA_CONFIG_FILE to its path. This small evaluation configuration enables the local Mock provider, creates a route, and applies PII and guardrail actions to the operations workspace:

DVARA_CONFIG_FILE is the canonical variable. The 1.8 runtime also accepts the legacy GATEWAY_CONFIG_FILE name when DVARA_CONFIG_FILE is unset. If both are present, DVARA_CONFIG_FILE wins. Use the canonical name in new deployments and migrate existing manifests while the fallback remains available.

providers:
  - type: mock

workspaces:
  - id: operations
    name: Operations
    status: ACTIVE
    metadata:
      pii.enabled: true
      pii.action: REDACT
      guardrail.enabled: true
      guardrail.action: BLOCK

routes:
  - id: local-smoke-test
    model: "mock*"
    provider: mock

Use ${NAME} for a required environment value or ${NAME:-fallback} when a safe fallback exists. For example, a real provider can keep its secret out of the file:

providers:
  - type: openai
    api_key: ${OPENAI_API_KEY}

Start the gateway with the explicit file path:

DVARA_CONFIG_FILE=/etc/dvara/gateway.yaml \
java -jar dvara-gateway-server-1.8.5-app.jar

The file is read once. If you edit a route, policy, key, or workspace, restart the process. Environment variables, JVM system properties, and command-line arguments override provider and rate-limit values translated from gateway.yaml; the file still owns its workspace, route, policy, and API key records.

Environment placeholders follow shell-style defaults: ${NAME:-fallback} uses the fallback when NAME is unset or set to an empty string. API-key name values must be unique across the file because the name is the key's operational ID. A policy or prompt template with workspace: must name a workspace declared under workspaces or named by an API key; an unknown workspace refuses startup and names the entry.

Verify the Open Source configuration

Check readiness first:

curl --silent --output /dev/null --write-out 'HTTP %{http_code}\n' \
  http://localhost:8080/actuator/health/readiness

HTTP 200

Then send a request that only the configured route can serve:

curl --silent http://localhost:8080/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "mock/gpt-4",
    "messages": [
      {"role": "user", "content": "Confirm the configuration is active."}
    ]
  }'

The identifiers and timestamp vary, but a successful response includes:

{
  "object": "chat.completion",
  "model": "mock/gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "This is a mock response"
      },
      "finish_reason": "stop"
    }
  ]
}

Every /v1 request requires a DVARA key. Create one, add its fingerprint to gateway.yaml, and send the plaintext key in the smoke test. Follow the Open Source distribution quickstart for that complete flow.

Configure the Enterprise platform

Separate process settings from managed product configuration:

Change	Where to make it	Restart required?
Database connection (Flightdeck only), ports, encryption key, actuator keys, enrolment secret	Deployment environment, secret store, or Helm values	Yes
Licence	Flightdeck License page	No
Provider credential	Flightdeck Credentials, a configured vault, or a deployment secret	No for a Flightdeck or vault-backed rotation; yes for an environment change
Workspace, route, policy, budget, pricing, MCP server, or A2A agent	The matching Flightdeck page	No
Per-workspace PII, guardrail, rate, cost, or approval setting	The workspace settings in Flightdeck	No
Fleet snapshot	Flightdeck Import / Export	No after apply

Flightdeck sends licence state to Gateway pods in the same configuration bundle as every other managed setting. See Licensing for rights and capacity limits.

Make one managed change

To change PII handling for one workspace:

1. Open the workspace in DVARA Flightdeck.
2. Set pii.action to LOG, BLOCK, irreversible REDACT, or Enterprise request-side TOKENIZE. The default is LOG; TOKENIZE needs a working token store and key material.
3. Save the workspace.
4. Wait for the next bundle, about 10 seconds at the default settings, before testing every gateway pod.

The action is conditional: LOG records a detection and allows the content, REDACT removes the detected value permanently, TOKENIZE creates a recoverable token for provider-bound input, and BLOCK refuses a matching request. New response PII is removed rather than tokenized under both REDACT and TOKENIZE. Use the PII governance guide for a complete request, response, and audit-verification example.

Put fleet changes through review

Open the user menu in Flightdeck and select Import / Export. An owner can:

1. export the whole fleet or one workspace as JSON;
2. review and version the file outside DVARA;
3. upload or paste the changed file;
4. preview a merge or replace operation; and
5. apply the staged diff.

merge upserts the supplied entries and leaves everything else alone. replace also deletes managed entries missing from the snapshot, so inspect the preview carefully. Apply is atomic: either the complete import succeeds or none of it is written. Secrets are redacted from exports and must be supplied again when a change needs them.

See Export and import configuration for the complete workflow.

Use bootstrap only for initial Enterprise setup

Set DVARA_BOOTSTRAP_FILE on Flightdeck when a new Enterprise installation needs initial workspaces, API keys, and routes before an operator opens Flightdeck. Flightdeck seeds them into its database, and the next bundle carries them to the gateways. On each startup DVARA creates missing entries and skips entries whose identity already exists. It does not overwrite an existing route or workspace.

After bootstrap, manage those records in Flightdeck. Treating the bootstrap file as an ongoing reconciliation source creates false expectations: it is a seed, not a continuous desired-state controller.

An Open Source gateway.yaml store is read-only. It accepts the bootstrap variable only when it names the same active configuration file. From 1.8.2 an Enterprise Gateway given DVARA_BOOTSTRAP_FILE or GATEWAY_BOOTSTRAP_FILE refuses to start and names the setting: the file belongs on Flightdeck. The legacy GATEWAY_BOOTSTRAP_FILE fallback still works in 1.8, but new deployments should use DVARA_BOOTSTRAP_FILE.

bootstrap.yaml and the Open Source distribution's gateway.yaml use different schemas. Do not copy a block from one file into the other. See the complete bootstrap mode table.

Know which credential wins

For an Enterprise request, DVARA resolves a provider credential in this order:

1. an active credential stored through Flightdeck;
2. a configured vault reference; then
3. an environment variable or application property.

The first available credential wins. Revoking a Flightdeck credential can therefore expose a vault or environment fallback. Check that fallback before a rotation if strict workspace-owned credentials are required.

Verify a fleet change reached every pod

From 1.8.2 a saved change reaches a gateway in two steps, and no restart is required. Flightdeck notices the change and publishes a new signed bundle (dvara.config.bundle.republish-interval-ms, 5 seconds), and each gateway fetches it (dvara.data-plane.control-plane.poll-interval-ms, 5 seconds for the bundle). The worst case is about 10 seconds.

Check each side:

• Flightdeck exposes the change-detection gauges on its own /actuator/prometheus. The gateways do not register them.

  Metric	What it tells you
  gateway_config_poller_up	1 when Flightdeck completed a recent successful check for changes
  gateway_config_poller_polls_total	Number of successful checks
  gateway_config_poller_errors_total	Number of failed checks
  gateway_config_poller_areas_refreshed_total	Number of changed areas dispatched for refresh

• Each gateway reports the bundle it holds on /actuator/gateway-status: configBundle.heldVersion, and configBundle.stale once the bundle is older than staleness-warn-seconds (one hour by default). configBundle.everContacted: false means the pod has never reached Flightdeck.

Alert on gateway_config_poller_up == 0 on Flightdeck and on a stale bundle on any gateway, and test the changed behavior through each pod before declaring a sensitive rollout complete.

Protect configuration secrets

• Put provider keys, encryption material, actuator keys, audit signing secrets, database passwords, and any licence envelope you keep outside Flightdeck in a secret store or environment variables, not a committed file.
• Give DVARA_ACTUATOR_API_KEY and DVARA_ACTUATOR_METRICS_API_KEY different values. The first protects operational status; the second protects metrics.
• Actuator protection follows both server.servlet.context-path and a custom management.endpoints.web.base-path. The base discovery path requires the operator key too; only health, liveness, readiness, and info stay anonymous. Keep management endpoints on the application port (the default or the same value as server.port) or disable them with management.server.port=-1. DVARA refuses startup when they are configured on a separate port because that path would bypass the gateway security filter.
• Keep one DVARA_ENCRYPTION_MASTER_PASSWORD across the Enterprise services that read stored credentials. Losing it makes encrypted credentials unreadable.
• Back up the configuration database before a large replace import.

Find an exact key or default

This page explains which source to use and how to operate it. Use the configuration reference for exact property names, types, defaults, and per-workspace metadata keys. Cross-check the selected runtime's capability in capability availability before setting a key: a property name does not prove that its implementation is present in every artifact.