Skip to main content

Docker Compose Setup

All DVARA Docker Compose stacks live in the public dvara-examples repo. Each variant is a self-contained directory — cd in, set your .env, and run docker compose up -d. For the 5-minute first-run experience, see Quickstart.

All stacks include PostgreSQL. DVARA requires it — there is no in-memory fallback.

Pre-built images​

ImageDescription
ghcr.io/dvarahq/dvara/dvara-llm-gateway:latestGateway server (port 8080)
ghcr.io/dvarahq/dvara/dvara-flightdeck:latestDVARA Flightdeck (port 8090)
ghcr.io/dvarahq/dvara/dvara-mcp-gateway:latestMCP Proxy server (port 8070)

Tags: latest (current release) or a version tag (e.g. 1.0.0).

Topologies​

StackServicesUse for
quick-start/postgres + gateway-server + gateway-uiFastest path to a running gateway. OpenAI only.
multi-provider/postgres + gateway-server + gateway-uiOpenAI + Anthropic out of the box. Add more providers (Gemini, Mistral, Cohere, Groq, Azure, Bedrock, Ollama) by uncommenting env vars.
ollama/postgres + gateway-server + gateway-ui + ollamaLocal models, no external LLM calls.
full/postgres + gateway-server + gateway-ui + mcp-proxy-serverEvery DVARA component running together — adds the MCP Proxy for agent tool governance.

Clone once, then switch between stacks by cd-ing into a different directory:

git clone https://github.com/dvarahq/dvara-examples.git
cd dvara-examples/docker-compose

Quick-start stack​

The fastest path to a running gateway — PostgreSQL + gateway-server + DVARA Flightdeck with OpenAI as the only provider. This is what Quickstart walks through.

cd quick-start
cp .env.example .env
# edit .env — every uncommented variable is required; the file's
# inline comments explain each one and how to generate the random
# secrets (openssl rand -base64 32)
docker compose up -d

Want more than one provider? Use multi-provider/ below.

:::info Two kinds of credentials DVARA uses two separate credential layers:

  • Provider keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) — infrastructure secrets the gateway uses to call upstream LLM providers. Set as env vars, or manage them through the DVARA Flightdeck's BYOK credential store, or integrate with vault.
  • Tenant API keys (gw_...) — application credentials your SDK uses to authenticate with the gateway. Create them in the DVARA Flightdeck after setting up a tenant.

In production, provider keys are managed by your ops/security team; tenant API keys are managed by platform admins through the dashboard or by tenant admins via the self-service portal. :::

Multi-provider stack​

Same topology as quick-start/ but with OpenAI + Anthropic wired up out of the box, plus commented-out slots for every other supported provider. Providers register automatically at startup whenever their API key env var is set and non-empty — so adding Gemini, Mistral, Cohere, Groq, Azure OpenAI, Bedrock, or Ollama is just a matter of uncommenting a line in docker-compose.yml and setting the matching value in .env.

cd multi-provider
cp .env.example .env
# set OPENAI_API_KEY and/or ANTHROPIC_API_KEY
docker compose up -d

curl -s http://localhost:8080/v1/models | jq '.data[].id'

To enable additional providers, open docker-compose.yml and uncomment the env vars under dvara-gateway.environment:

  dvara-gateway:
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
      GEMINI_API_KEY: ${GEMINI_API_KEY:-}
      MISTRAL_API_KEY: ${MISTRAL_API_KEY:-}
      COHERE_API_KEY: ${COHERE_API_KEY:-}
      GROQ_API_KEY: ${GROQ_API_KEY:-}
      AZURE_OPENAI_API_KEY: ${AZURE_OPENAI_API_KEY:-}
      AZURE_OPENAI_BASE_URL: ${AZURE_OPENAI_BASE_URL:-}

Then set the matching values in .env. For Azure OpenAI you must set both AZURE_OPENAI_API_KEY and AZURE_OPENAI_BASE_URL. See Providers for the complete list and per-provider setup.

Local models with Ollama​

Run entirely local — no provider API keys, no outbound LLM calls. A DVARA license key is still required.

cd ollama
cp .env.example .env   # fill in every uncommented variable per the inline comments
docker compose up -d

# Pull a model
docker compose exec ollama ollama pull llama3.2

# Use it
curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ollama/llama3.2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }' | jq .

The stack includes a GPU-passthrough block commented out at the top of docker-compose.yml — uncomment it if you have an NVIDIA GPU and the NVIDIA Container Toolkit installed.

Full stack (with MCP Proxy)​

The complete DVARA deployment — every component running together. Adds the MCP Proxy server on port 8070 for AI agent tool governance: approval gates, loop detection, session tracking, and PII scanning on tool calls. Use this when you want the whole platform exercised end-to-end.

cd full
cp .env.example .env   # fill in every uncommented variable per the inline comments
docker compose up -d

docker compose ps
curl http://localhost:8080/actuator/health
curl http://localhost:8070/actuator/health/liveness

See Agentic Governance for MCP Proxy details.

First-run setup​

Open the DVARA Flightdeck at http://localhost:8090 — you'll be redirected to /setup to create the initial owner account. Full walkthrough in Setup & Login. For self-service portal access (tenant admin / developer / viewer roles), see Tenant Portal.

:::tip Disable authentication for local development If you prefer to skip authentication entirely during local development, add this to the dvara-flightdeck service environment section of any stack:

  dvara-flightdeck:
    environment:
      DVARA_FLIGHTDECK_SECURITY_ENABLED: "false"
      # ... other env vars

Never use this in production. :::

What the platform secrets do​

The .env.example in each stack carries five DVARA-specific secrets in addition to provider keys + DB_PASSWORD. The stacks already wire each one into the right service — .env.example lists what to set; the compose files reference them. The summary below is for understanding what each one is for, not for hand-editing your compose YAML.

Env varWhat it doesFailure mode if unset
DVARA_LICENSE_KEYSigned DVARA envelope validated at startupGateway refuses to boot (LicenseValidationException: No license key configured)
DVARA_ENCRYPTION_MASTER_PASSWORDAES-256-GCM key for ENCRYPTED-mode credentials stored per-tenant in PostgreSQL (the BYOK Credentials store in the Flightdeck)ENCRYPTED-mode credential persistence fails; REFERENCE-mode (vault pointer) still works
DVARA_ACTUATOR_API_KEYOperator Bearer for /actuator/gateway-status + every authenticated /actuator/* path EXCEPT prometheusLicense page in Flightdeck stays empty; every authenticated actuator probe 401s
DVARA_ACTUATOR_METRICS_API_KEYDistinct Bearer for /actuator/prometheus onlyPrometheus scrape 401s on every poll; dashboard's live-metrics card stays empty. Must differ from DVARA_ACTUATOR_API_KEY — principle of least privilege
DVARA_AUDIT_HMAC_SECRETHMAC-SHA256 key for the tamper-evident audit chainProduction-class Spring profiles refuse to start on the default placeholder

The probe paths (/actuator/health, /actuator/health/liveness, /actuator/health/readiness, /actuator/info) stay anonymous so container health checks don't need credentials.

BYOK: credentials via the DVARA Flightdeck​

Provider credentials can be managed through the DVARA Flightdeck under Credentials instead of (or in addition to) env vars. Keys are encrypted with AES-256-GCM and stored per-tenant in PostgreSQL — recommended for multi-tenant setups where each tenant brings their own provider keys (BYOK). The stacks already wire DVARA_ENCRYPTION_MASTER_PASSWORD into the gateway service; setting a non-default value in .env is all that's required.

Authentication modes​

By default, the DVARA Flightdeck uses built-in email/password authentication. For production, DVARA supports three modes:

ModeWhen to useConfig required
Built-in (default)Local dev, small teams, no existing IdPNone — works out of the box
OIDCExisting Keycloak, Okta, or Azure ADDVARA_FLIGHTDECK_OIDC_ISSUER_URI
SAML 2.0Enterprise SSO (ADFS, Okta SAML, Azure AD)DVARA_FLIGHTDECK_SAML_METADATA_URL

Example — enabling OIDC on the DVARA Flightdeck by adding env vars to the dvara-flightdeck service:

  dvara-flightdeck:
    environment:
      DVARA_FLIGHTDECK_OIDC_ISSUER_URI: https://keycloak.example.com/realms/dvara
      DVARA_FLIGHTDECK_OIDC_AUDIENCE: dvara-admin
      DVARA_FLIGHTDECK_OIDC_ROLE_CLAIM: realm_access.roles
      # ... other env vars

OIDC and SAML are mutually exclusive — configuring both causes a startup error. The full property reference for OIDC + SAML lives in Setup & Login and Configuration.

Viewing logs​

docker compose logs -f                  # all services
docker compose logs -f gateway-server   # single service

Logs use structured JSON format by default. Switch to plain-text with SPRING_PROFILES_ACTIVE=log-plain.

Health probes​

The DVARA Flightdeck exposes standard health endpoints for Docker health checks:

curl http://localhost:8090/actuator/health/liveness    # liveness
curl http://localhost:8090/actuator/health/readiness   # readiness (includes gateway-server connectivity)

See the DVARA Flightdeck Guide for full documentation.

Stopping​

docker compose down        # stop, keep data
docker compose down -v     # stop and delete the postgres volume

Troubleshooting​

Port already in use​

Override the host port by adding a ports override in a docker-compose.override.yml alongside the stack, or edit the stack's docker-compose.yml directly:

ports:
  - "9080:8080"  # maps host 9080 → container 8080

Gateway starts but providers are not registered​

Check that environment variables are being passed through:

docker compose exec gateway-server env | grep -i api_key

Keys must be non-empty for providers to register.

STARTUP FAILED: PostgreSQL is required​

All stacks in dvara-examples include PostgreSQL. If you see this error, you're likely running a stripped-down custom compose file without the postgres service or without the SPRING_DATASOURCE_* env vars on the gateway. Use one of the examples as a starting point.

Health check keeps failing​

docker compose logs gateway-server | head -50

The gateway needs ~20-30 seconds to start (database migrations run on first boot). If it consistently fails, check for port conflicts and that your license key is valid.

Cannot log in to the DVARA Flightdeck​

First-time users must create the initial owner account at http://localhost:8090/setup. If you've set up an account and forgotten the password, use Forgot password? on the login page — by default the reset link is printed to gateway-ui logs (docker compose logs gateway-ui). Configure SMTP with dvara.flightdeck.security.builtin.email.transport=smtp for email delivery.

Last updated on