Configuration reference

All configuration is environment variables. Locally they come from .env; in production from your platform’s secret and variable mechanisms.

General

Variable	Default	Notes
CAVS_ENV	development	production hardens several defaults — see the notes below
LOG_LEVEL	info	debug, info, warn, error

HTTP and URLs

Variable	Default	Notes
API_ADDR	:8080	Listen address
API_BASE_URL	http://localhost:8080	The API’s own public URL. Used to build LFS endpoints and instructions.
APP_BASE_URL	http://localhost:5173	The dashboard’s public origin. Used in every outbound email link.
CORS_ORIGINS	http://localhost:5173,http://localhost:3000	Comma-separated allowlist
RATE_LIMIT_RPS	30	Sustained requests/second, per token → user → IP
RATE_LIMIT_BURST	60	Burst allowance

APP_BASE_URL must be the origin users sign in on

Firebase persists authentication per origin. If an invitation link points at a different host than the one people sign in on — a *.run.app URL instead of your custom domain, say — the link reads as logged-out and bounces to /login.

Set APP_BASE_URL to the exact canonical origin, and make sure your deploy tooling doesn’t overwrite it with a platform-generated URL.

Raise the rate limit if you host many-pack repositories

The transfer agent HEAD-guards every tree file before uploading. On a repository with many packs that burst can exceed 30 req/s, and the agent does not back off on 429 — the mirror fails silently. Size RATE_LIMIT_RPS for your largest repository, or accept that very large pushes may need retrying.

MongoDB

Variable	Default	Notes
MONGODB_URI	mongodb://localhost:27017	Use a replica set (or Atlas) in production — enables transactions and read scaling
MONGODB_DB	cavs	Database name
DB_MAX_POOL_SIZE	100
DB_MIN_POOL_SIZE	5
DB_SEED_ON_BOOT	true	Creates indexes and seeds plans, idempotently

Firebase Authentication

Variable	Default	Notes
FIREBASE_PROJECT_ID	—	Required. Must match the web app’s project.
AUTH_DEV_BYPASS	false	Accepts unsigned tokens. Backend-only. Forced off when CAVS_ENV=production.

Caution

With bypass off, the API verifies signatures against Google’s JWKS and checks the issuer and audience. An empty or mismatched FIREBASE_PROJECT_ID rejects every real token — so the API refuses to boot in that state rather than failing later.

Pub/Sub

Variable	Default	Notes
PUBSUB_PROJECT_ID	cavs-local	GCP project
PUBSUB_EMULATOR_HOST	localhost:8085	Unset in production, and provide GOOGLE_APPLICATION_CREDENTIALS instead
PUBSUB_TOPIC_PREFIX	cavs	Topic namespace

With no broker reachable in development the API falls back to a no-op bus: events aren’t delivered, everything else works.

Object storage (managed)

Variable	Default	Notes
S3_ACCOUNT_ID	—	Cloudflare account id; the R2 endpoint is derived from it
S3_ENDPOINT	http://localhost:9000	Set explicitly only to override the derived endpoint
S3_REGION	us-east-1	auto for R2
S3_BUCKET	cavs-cloud-dev
S3_ACCESS_KEY / S3_SECRET_KEY	dev MinIO creds
S3_FORCE_PATH_STYLE	true	Required by MinIO and R2
S3_SIGN_TTL	15m	Presigned URL lifetime
S3_PUBLIC_BASE_URL	—	Optional CDN or public R2 bucket URL for downloads
STORAGE_ENCRYPTION_KEY	dev placeholder	Required in production. AES-256-GCM master key for BYOS credentials.

Production — Cloudflare R2

S3_ACCOUNT_ID=<cloudflare-account-id>
S3_REGION=auto
S3_BUCKET=<your-r2-bucket>
S3_ACCESS_KEY=<r2-access-key-id>
S3_SECRET_KEY=<r2-secret-access-key>
S3_FORCE_PATH_STYLE=true
S3_PUBLIC_BASE_URL=https://pub-<hash>.r2.dev   # optional

Generate the encryption key

openssl rand -base64 32

Danger

STORAGE_ENCRYPTION_KEY encrypts every stored BYOS credential. Lose it and every BYOS connection becomes unusable — customers would have to re-enter their credentials. Back it up in your secret manager, and understand that rotating it requires re-encrypting every stored connection.

Caution

The API refuses to boot in production without S3 configured. If a deploy fails at startup, check S3_ACCOUNT_ID and the access keys first.

Billing

Variable	Default	Notes
BILLING_PROVIDER	mock	mock applies plan changes instantly; stripe charges for real
STRIPE_SECRET_KEY	—	A restricted key is enough: products, prices, webhooks, checkout
STRIPE_WEBHOOK_SECRET	—	Verifies incoming event signatures
STRIPE_PRICE_DEVELOPER	—	Recurring price id for the Developer plan
STRIPE_PRICE_TEAM	—	Recurring price id for the Team plan

Point a provider webhook at /api/v1/billing/webhook.

Note

The boot seed copies STRIPE_PRICE_<PLAN> onto the plan documents, and plans are read per request — so price changes need no redeploy. A paid plan without a price fails checkout with “plan X has no Stripe price configured”. free and business need none.

Email

Variable	Default	Notes
EMAIL_PROVIDER	log	log, mailgun, smtp
EMAIL_FROM_NAME	CAVS Node
EMAIL_FROM_EMAIL	[email protected]	Must be on the verified sending domain
MAILGUN_DOMAIN	—	Verified sending domain
MAILGUN_API_KEY	—	Private API key
MAILGUN_BASE_URL	https://api.mailgun.net	EU domains: https://api.eu.mailgun.net
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS	— / 587	Any relay, including SES SMTP

A misconfigured provider falls back to the log sender in development so the stack always runs; in production it fails fast at boot instead.

Redis

Variable	Default
REDIS_URL	redis://localhost:6379

Optional cache. Nothing depends on it.

Security

Variable	Default	Notes
SESSION_TOKEN_SECRET	dev placeholder	Change in production
SESSION_TOKEN_TTL	10m

Observability

Variable	Default	Notes
CAVS_REGION	local	Low-cardinality metric label
METRICS_ENABLED	true
METRICS_ADDR	:9464	Never expose publicly
TRACING_ENABLED	false
OTEL_EXPORTER_OTLP_ENDPOINT	—	OTLP/gRPC collector
OTEL_EXPORTER_OTLP_INSECURE	true
OTEL_TRACES_SAMPLER_RATIO	0.1	10% sampling

R2 exporter (cmd/r2exporter)

Variable	Default	Notes
CF_ACCOUNT_ID	—	Cloudflare account
CF_API_TOKEN	—	Needs Account Analytics:Read + Workers R2 Storage:Read
R2_BUCKETS	cavs-cloud-dev	Comma-separated
R2_SCRAPE_INTERVAL	5m
R2_RECONCILE	true	Cross-check provider figures against CAVS’s own

Web build (Vite)

Read at build time and baked into the bundle.

Variable	Default	Notes
VITE_API_BASE	/api/v1	Same-origin by default
VITE_API_PROXY	http://localhost:8080	Dev-server proxy target
VITE_FIREBASE_API_KEY	—
VITE_FIREBASE_AUTH_DOMAIN	—
VITE_FIREBASE_PROJECT_ID	—	Must equal FIREBASE_PROJECT_ID
VITE_FIREBASE_STORAGE_BUCKET	—
VITE_FIREBASE_MESSAGING_SENDER_ID	—
VITE_FIREBASE_APP_ID	—
VITE_FIREBASE_MEASUREMENT_ID	—

Note

Firebase web config values are public by design — they identify the project, they don’t authorize anything. Security comes from Firebase rules and the API’s own verification, not from hiding these.

Production checklist

• CAVS_ENV=production
• MONGODB_URI points at a replica set; connectivity verified via /readyz
• FIREBASE_PROJECT_ID set and matching VITE_FIREBASE_PROJECT_ID
• AUTH_DEV_BYPASS=false (forced, but set it explicitly)
• S3_* configured; bucket versioning enabled
• STORAGE_ENCRYPTION_KEY generated, backed up in a secret manager
• SESSION_TOKEN_SECRET changed from the placeholder
• APP_BASE_URL = the exact origin users sign in on
• API_BASE_URL = the API’s public URL
• CORS_ORIGINS = only your dashboard origin(s)
• PUBSUB_EMULATOR_HOST unset; GCP credentials provided
• EMAIL_PROVIDER real, sending domain verified, a test email delivered
• BILLING_PROVIDER=stripe with both keys and the price ids, webhook registered
• METRICS_ADDR reachable only from your monitoring network
• RATE_LIMIT_RPS sized for your largest repository
• All secrets in a secret manager, none in .env files or images

Next

• Deploying — Cloud Run and Terraform.
• Observability — metrics and dashboards.
• Run it locally — the development stack.