Deployment Notes

BVE Gateway runs as a single Cloudflare Worker that serves both the API (api.bve.me) and the documentation site (docs.bve.me) via the Workers Assets binding.

Prerequisites

Cloudflare account with Workers and D1 access
bun installed
wrangler (included as a dev dependency — use bunx wrangler)

First-time setup

1. Create Cloudflare resources

# Create the D1 database
bunx wrangler d1 create bve_gateway
# Copy the returned database_id into wrangler.jsonc

# Create the event queue
bunx wrangler queues create bve-gateway-events

2. Update wrangler.jsonc

After creating the D1 database, update wrangler.jsonc with the returned database_id:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "bve_gateway",
      "database_id": "YOUR_DATABASE_ID_HERE"
    }
  ]
}

3. Apply database migrations

bun run db:migrate:remote

4. Set secrets

bunx wrangler secret put FUELIX_API_KEY   # Fuelix upstream API key
bunx wrangler secret put ADMIN_API_KEY    # Admin key for /admin/* routes
bunx wrangler secret put API_KEY_PEPPER   # Random 32+ char string for key hashing

5. Deploy

bun run deploy

This command:

Builds the Astro docs site (docs/dist/)
Deploys the Worker with the built assets

Custom domains

The Worker is configured in wrangler.jsonc to respond on two custom domains:

{
  "routes": [
    { "pattern": "api.bve.me", "custom_domain": true },
    { "pattern": "docs.bve.me", "custom_domain": true }
  ]
}

Add these domains in the Cloudflare dashboard under Workers & Pages > your Worker > Settings > Custom Domains, or they will be attached automatically on the next deploy if already configured as zones in your account.

The Worker routes based on hostname:

docs.bve.me → serves the Astro static site via the ASSETS binding
api.bve.me → runs the API gateway logic

Local development

# Copy example env file
cp .env.example .dev.vars
# Edit .dev.vars with real values (never commit this file)

# Apply migrations locally
bun run db:migrate:local

# Start local dev server
bun run dev

The local server runs at http://localhost:8787.

Environment variables

Configurable via wrangler.jsonc vars (non-secret):

Variable	Default	Description
`FUELIX_BASE_URL`	`https://api.fuelix.ai/v1`	Fuelix upstream base URL
`MONTHLY_WORKER_REQUEST_SOFT_CAP`	`8500000`	Soft cap — returns 429
`MONTHLY_WORKER_REQUEST_HARD_CAP`	`9500000`	Hard cap — returns 503

Secrets (set via wrangler secret put):

Secret	Description
`FUELIX_API_KEY`	Fuelix upstream API key
`ADMIN_API_KEY`	Key for `/admin/*` routes
`API_KEY_PEPPER`	SHA-256 pepper for client key hashing

Update and redeploy

# Pull latest code
git pull

# Run migrations if schema changed
bun run db:generate
bun run db:migrate:remote

# Deploy
bun run deploy

View logs

bunx wrangler tail

Useful commands

Command	Description
`bun run dev`	Local development server
`bun run deploy`	Build docs + deploy Worker
`bun run tail`	Stream live Worker logs
`bun run typecheck`	TypeScript type check
`bun test` — ❌	Use `bun run test` instead (Cloudflare pool)
`bun run test`	Run test suite
`bun run db:generate`	Generate Drizzle migrations
`bun run db:migrate:local`	Apply migrations locally
`bun run db:migrate:remote`	Apply migrations to production D1