Setup
Configure the gateway: requirements, environment, secrets, and choosing a database and Redis.
Configure the gateway process, secrets, and storage connections before deploying it. Use Quickstart for a local example or Deployment to choose a hosting platform.
Requirements
- Bun 1.4+ — 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:6379The optional dashboard has a separate environment file:
# apps/dashboard/.env — copy apps/dashboard/.env.example
GATEWAY_URL=http://localhost:4000For optional settings, defaults, and limits, use the Environment variables reference. Review proxy trust, shutdown timeout, and observability settings for your deployment.
Secrets
Store the root credential and encryption keyring in your secret manager — never in git or the image:
| Secret | Purpose | Format |
|---|---|---|
MASTER_KEY | Operator credential; full access to /admin/*. | Strong random string, at least 32 characters. |
ENCRYPTION_KEYRING | Encrypts credentials, extension source, compaction capsules, and forensic samples. | JSON key-id to 64-hex-key map. |
ACTIVE_ENCRYPTION_KEY_ID | Selects the key used for new envelopes. | An id present in the keyring. |
openssl rand -base64 48 # MASTER_KEY
openssl rand -hex 32 # one ENCRYPTION_KEYRING valueRotation 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://…andredis://…. 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
Choose services that meet the required Postgres and Redis versions and present a certificate trusted by Bun. Use the provider's documented connection string and connect by hostname. Check version support, connection limits, and persistence before choosing a plan.
Avoid exposing a database with a self-signed certificate on a public port. Use a private network or a certificate from a public CA; see Troubleshooting.