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	Normally within the 3-second configuration poll interval
Enterprise platform at first boot	bootstrap.yaml for initial workspaces, API keys, and routes	During 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. 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.0-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.

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"
    }
  ]
}

API-key enforcement defaults to off, so this keyless smoke test is anonymous and does not use the operations workspace settings. Before you use the runtime beyond local evaluation, create a DVARA key, add its fingerprint to gateway.yaml, and set DVARA_LLM_GATEWAY_REQUIRE_API_KEY=true. 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, ports, encryption key, actuator keys, licence envelope	Deployment environment, secret store, or Helm values	Yes
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

The LLM governance path runs in the Enterprise platform's unlicensed Development posture. A valid licence activates the MCP and A2A planes and adds production rights and support; it does not change how Flightdeck-managed configuration propagates.

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 one configuration poll interval 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 when a new Enterprise installation with a writable repository needs initial workspaces, API keys, and routes before an operator opens Flightdeck. 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. A Gateway with dvara.data-plane.serve-from-bundle=true does not seed these records and tells you to manage them in the Console. 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

Persisted configuration normally refreshes within dvara.config.poll-interval-ms, which defaults to 3000. A restart is not required. Monitor these Prometheus gauges on every gateway pod:

Metric	What it tells you
gateway_config_poller_up	1 when the pod completed a recent successful poll
gateway_config_poller_polls_total	Number of successful polls
gateway_config_poller_errors_total	Number of failed polls
gateway_config_poller_areas_refreshed_total	Number of changed areas dispatched for refresh

A saved Flightdeck change followed by a rising error count means the database write succeeded but that pod may still be serving its earlier configuration. Alert on gateway_config_poller_up == 0 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 the licence envelope 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.
• 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.