Setup

Everything the gateway needs before you deploy. To just see it running, the Quickstart is faster; come here to configure a real environment, then pick a target under Deployment.

Requirements

• Bun 1.3+ — the gateway runtime (runs TypeScript directly; no build step) and the package manager / task runner.
• Postgres 18+
• Redis 8+

Bifrost runs on Bun, not Node. If you plan to reach a database or Redis over TLS with a self-signed certificate, read Troubleshooting first — Bun's TLS may not accept those, and the fix is a configuration choice you make here.

Environment

Create apps/gateway/.env (copy apps/gateway/.env.example). The minimum:

PORT=4000
NODE_ENV=production
MASTER_KEY=replace-with-at-least-32-random-characters
ENCRYPTION_KEYRING={"primary":"64_hex_chars_32_bytes"}
ACTIVE_ENCRYPTION_KEY_ID=primary
DATABASE_URL=postgres://user:pass@host:5432/bifrost
REDIS_URL=redis://host:6379

Everything else ships with production-ready defaults — override only what you need. The most common:

Full list of every variable, including OpenTelemetry and response-state retention: Environment variables.

Secrets

Store the root credential and encryption keyring in your secret manager — never in git or the image:

openssl rand -base64 48   # MASTER_KEY
openssl rand -hex 32      # one ENCRYPTION_KEYRING value

Rotation procedures live in Operations → Secrets.

Database and Redis

The gateway needs a Postgres 18+ database and a Redis 8+ instance. How you connect matters because of the Bun TLS constraint:

• Self-hosted on the same private network (Compose / Coolify / Portainer / Dokploy): connect over plaintext — postgres://… and redis://…. Safe by network isolation, and it sidesteps the self-signed TLS issue. This is the default in every Deployment recipe.
• Managed provider (recommended for development, or when the database lives off-network): pick one that presents a public-CA certificate, which Bun connects to cleanly.

Managed database and Redis

Good free-tier options that work with Bun's TLS out of the box:

Avoid pointing the gateway at a self-signed database over a public port (the default for a raw Coolify/Dokploy database exposed publicly) — see Troubleshooting.