Gateway and Runtime Configuration

This page explains how to configure the optional gateway layer, use external data services, and understand the most relevant runtime settings.

Gateway deployment patterns

The Helm chart supports three practical gateway patterns:

• bundled gateway inside the cluster
• external gateway
• bundled gateway with a custom OpenAI-compatible upstream

Bundled gateway

This is the recommended option when you want the deployment to remain self-contained.

Set:

gateway:
  enabled: true

When enabled:

• the API uses the in-cluster gateway service
• the frontend can call the gateway through the configured ingress host
• the gateway can expose /v1/models, /v1/chat/completions, /health, and /metrics

External gateway

If you already operate a separate gateway, keep the bundled gateway disabled and override the runtime values:

gateway:
  enabled: false

runtime:
  commonEnv:
    LLM_GATEWAY_URL: "https://gateway.example.com"

frontend:
  publicEnv:
    VITE_COMPASS_GATEWAY_BASE: "https://gateway.example.com/v1/chat/completions"

Custom OpenAI-compatible provider

If you enable the bundled gateway, you can configure a buyer-managed OpenAI-compatible upstream behind it:

gateway:
  enabled: true
  env:
    CUSTOM_PROVIDER_ENABLED: "true"
    CUSTOM_PROVIDER_BASE_URL: "https://llm.example.com"
    CUSTOM_PROVIDER_API_SHAPE: "openai"
    CUSTOM_PROVIDER_API_KEY: ""
    CUSTOM_PROVIDER_HEADERS_JSON: '{"x-tenant":"buyer-a"}'
    CUSTOM_PROVIDER_MODELS_JSON: >-
      [{"id":"gpt-4.1","name":"GPT 4.1","context_window":128000,"supports_streaming":true,"supports_function_calling":true,"input_modalities":["text"],"output_modalities":["text"]}]
    CUSTOM_PROVIDER_DEFAULT_MODEL: "gpt-4.1"
    CUSTOM_PROVIDER_LABEL: "Buyer OpenAI-Compatible"

Use this when:

• you want Smart Engineering to call a buyer-managed LLM service
• you still want the product to keep its internal OpenAI-compatible gateway contract

External PostgreSQL

The default install bundles PostgreSQL. To use an external database:

postgres:
  enabled: false

externalDatabase:
  existingSecretName: smart-eng-database
  existingSecretKey: DATABASE_URL

External Valkey or Redis-compatible service

The default install bundles Valkey. To use an external service:

valkey:
  enabled: false

externalValkey:
  host: "valkey.example.internal"
  port: 6379
  tlsEnabled: true
  username: ""
  existingSecretName: smart-eng-valkey
  existingSecretPasswordKey: redis-password

Keep these services private. They are not intended for public ingress exposure.

Important runtime settings

The following settings are the ones most often adjusted in buyer environments.

Setting	What it controls
serviceAccount.name	The Kubernetes service account used by the pods
serviceAccount.annotations	IRSA or other workload identity annotations
runtime.commonEnv.AWS_REGION	AWS region used for Bedrock, S3, Marketplace, and License Manager
runtime.commonEnv.AWS_WORKLOAD_IDENTITY_MODE	Expected workload identity model: default_chain, irsa, or roles_anywhere
runtime.commonEnv.AUTH_MODE	Authentication mode: disabled or oidc
runtime.commonEnv.AUTH_DISABLED	Explicit auth bypass flag used by the API and gateway
runtime.commonEnv.ALLOWED_ORIGINS	CORS allowlist for API callers
runtime.commonEnv.LLM_GATEWAY_URL	Gateway URL used by the backend
runtime.commonEnv.S3_UPLOAD_SERVER_SIDE_ENCRYPTION	Upload encryption mode. AES256 is the default. Use aws:kms only when the buyer buckets are configured for KMS encryption and the runtime IAM role can use that key
s3.sourceBucket	Bucket used for uploaded source archives
s3.outputBucket	Bucket used for generated documentation and outputs
s3.workspaceBucket	Bucket used for runtime workspace artifacts
bedrock.modelId	Primary Bedrock model used for heavier tasks
bedrock.modelIdSmall	Secondary Bedrock model used for lighter tasks
gateway.enabled	Enables the bundled LLM gateway deployment
frontend.publicEnv.VITE_COMPASS_GATEWAY_BASE	Browser-side gateway endpoint for chat completions
ingress.*	Public hostnames and TLS settings
postgres.enabled	Enables the bundled PostgreSQL stateful set
valkey.enabled	Enables the bundled Valkey stateful set
externalDatabase.*	External PostgreSQL secret reference
externalValkey.*	External Valkey connection settings

Operating notes

• The product meters repository analysis usage through AWS Marketplace when metering is enabled.
• The Marketplace profile expects S3-based upload ingestion through the application callback flow.
• Static AWS access keys are not recommended for Marketplace deployments.
• Database schema changes are applied by the migration job during helm upgrade.

Next steps

After the environment is running:

• create a project in Smart Engineering
• upload a source archive
• confirm that the file lands in the source bucket
• run a documentation task
• verify that outputs are written to the output bucket
• review /config/runtime and /health if anything fails during the first run