3.3 KiB

Executable File

Raw Permalink Blame History

Configuration

This tutorial walks through the main configuration surfaces that control Frosty Deno.

1. Understand the configuration layers

The gateway uses two configuration sources:

environment variables parsed at boot
persisted PostgreSQL-backed state loaded during createDefaultContext()

When the same provider id or config field exists in both places, the persisted configuration wins.

2. Configure PostgreSQL first

The production path requires PostgreSQL.

Minimum setting:

FROSTY_PG_URL=postgres://frosty:frosty@localhost:5432/frosty

Add FROSTY_PG_DIRECT_URL when a transaction pooler sits in front of PostgreSQL and you still need a direct LISTEN connection.

3. Configure at least one provider

Choose one provider family and fill in the matching env group.

Example with OpenAI:

OPENAI_API_KEY=sk-your-key
FROSTY_DEFAULT_PROVIDER=openai

Example with Azure OpenAI:

AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-15-preview
AZURE_OPENAI_DEPLOYMENTS=gpt-4o-deployment

Example with a generic compatible endpoint:

OPENAI_COMPAT_BASE_URL=https://your-compatible-host/v1
OPENAI_COMPAT_API_KEY=...
OPENAI_COMPAT_DEFAULT_MODEL=your-default-model

4. Protect the admin surface

For any environment beyond trusted local development, set:

FROSTY_ADMIN_TOKEN=replace-me
FROSTY_ALLOWED_HOSTS=gw.example.com

FROSTY_ADMIN_TOKEN protects /api/* with a bearer token. FROSTY_ALLOWED_HOSTS feeds the admin origin guard.

5. Decide which optional subsystems to enable

Cache

FROSTY_CACHE=exact

Or semantic cache:

FROSTY_CACHE=semantic
FROSTY_VECTOR_STORE=pgvector
FROSTY_CACHE_EMBED_MODEL=text-embedding-3-small

Durable logs and analytics

FROSTY_LOG_STORE=pg
FROSTY_LOG_STORE_MAX=5000

Tracing

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

Pricing sync

FROSTY_PRICING_SYNC=on

Config encryption

FROSTY_ENCRYPTION_KEY=<base64-encoded-32-byte-key>

6. Configure governance if you need enforced admission

Governance configuration is primarily managed through the admin API or control UI after boot, but these env variables change the runtime behavior around it:

FROSTY_SHARED_RATE_LIMIT
FROSTY_WORKERS
FROSTY_CONFIG_RECONCILE_MS

Set FROSTY_SHARED_RATE_LIMIT=on when you run multiple replicas or want the fixed-window authority in PostgreSQL.

7. Persist operator configuration through the UI or `/api/*`

After boot, use:

#/providers
#/virtual-keys
#/teams
#/customers
#/pricing
#/settings

or the equivalent /api/* routes to persist additional configuration.

That is where you manage provider-account details that do not belong in env alone, such as extra headers, proxy settings, and operator-set pricing overrides.

8. Validate the result

Useful checks:

curl http://localhost:8080/healthz
curl http://localhost:8080/v1/models
curl -H "Authorization: Bearer $FROSTY_ADMIN_TOKEN" http://localhost:8080/api/providers

If the admin token is configured, the control UI will prompt for it and store it in browser session storage.

Continue with 03-local-development.md for the day-to-day development workflow.

3.3 KiB Executable File Raw Permalink Blame History