Deployment

EdgeBase supports three runtime deployment environments plus a packaged local distribution path. The same code runs identically in every runtime environment, and pack turns that same app bundle into a portable local artifact.

Cloud Edge

Global serverless deployment on 300+ edge locations.

npx edgebase deploy

On first deploy, EdgeBase automatically handles Cloudflare authentication:

1. Checks if you're logged in via wrangler whoami
2. Opens browser login if needed (no manual wrangler login required)
3. Detects your account ID and configures wrangler.toml automatically

For release: true deployments, the CLI also asks for a bootstrap admin email. If the deployed instance does not have any admin accounts yet, the CLI prompts for the first admin password and creates that account through a Service Key protected admin path instead of exposing a public browser setup form.

Feature	Detail
Cold start	~0ms
Scaling	Automatic, global
Cost	Free to start (paid plan $5/mo for higher limits)
Storage egress	$0
Backup	30-day PITR

Requirements: Cloudflare account. Core EdgeBase services can start on the Cloudflare Free plan. For higher resource limits, upgrade to the Workers Paid plan ($5/month, account-level — covers all projects).

R2 Storage

Free PlanBilling Setup

If your app uses storage in edgebase.config.ts, you must enable R2 in the Cloudflare Dashboard first: R2 Object Storage → Get Started. R2 includes 10 GB of free usage, but Cloudflare still requires a one-time R2 subscription / billing activation before first use.

CI/CD

For non-interactive environments, set CLOUDFLARE_API_TOKEN as an environment variable instead.

Docker

Container-based self-hosting. Runs the same runtime as edge deployment — identical behavior, full data sovereignty.

npx edgebase docker build
npx edgebase docker run

docker run automatically creates .env.release with secure random JWT secrets and a root SERVICE_KEY if the file doesn't exist yet. It also asks for the bootstrap admin email before starting the container, then creates the first admin account over the protected admin API if none exist yet. To customize secrets or use an existing file:

npx edgebase docker run --env-file .env.release

.env.release Reference

Variable	Required	Description
JWT_USER_SECRET	Yes	Signs user authentication tokens (auto-generated)
JWT_ADMIN_SECRET	Yes	Signs admin dashboard tokens (auto-generated)
SERVICE_KEY	Yes	Root server-side API key used for admin bootstrap, recovery, and Admin SDKs
DB_POSTGRES_*_URL	Optional	PostgreSQL connection string (used by DB blocks or auth configured with provider: 'postgres'; legacy provider: 'neon' configs still work)

tip

JWT_USER_SECRET, JWT_ADMIN_SECRET, and SERVICE_KEY are auto-generated when you first run npx edgebase docker run. You only need to set them manually if you want to keep existing tokens valid or preserve an existing Service Key across re-deployments.

Or run the equivalent container command yourself:

docker run -v edgebase-data:/data -p 8787:8787 --env-file .env.release edgebase

Or with Docker Compose:

version: '3.8'
services:
  edgebase:
    image: edgebase
    ports:
      - '8787:8787'
    volumes:
      - edgebase-data:/data
    environment:
      - JWT_USER_SECRET=your-secret-key
      - JWT_ADMIN_SECRET=your-admin-secret-key
      - SERVICE_KEY=your-service-key
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:8787/api/health']
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  edgebase-data:

The same SERVICE_KEY is what all Admin SDKs use for server-side access.

Feature	Detail
Cold start	N/A (always running)
Scaling	Manual (container orchestration)
Cost	VPS cost only (~$5–20/month)
Data	Local SQLite files in Docker volume

Requirements: Docker installed.

Direct Run

Run directly with Node.js — no Docker, no cloud account needed.

npx edgebase dev

Feature	Detail
Best for	Development, testing, lightweight production
Data	Local filesystem
Requirements	Node.js 20.19+ (24.x recommended)

Packed Local Distribution

Create a runnable local artifact from the same app bundle used by deploy, docker build, and dev.

npx edgebase pack --format portable
npx edgebase pack --format archive

Use pack when you want to hand off a local launcher instead of deploying to Cloudflare or running Docker/Node.js directly.

For the full packaging flow, output formats, and launcher behavior, see Packaging Guide.

Feature	Detail
Best for	QA handoff, demos, local installs, offline distribution
Runtime	Local packaged launcher built from the Direct/runtime bundle
Formats	Portable directory/app bundle, or archive
Requirements	Build machine for the target platform

If your app config defines frontend, deployed runtimes can also serve that prebuilt bundle.

For directory, mountPath, spaFallback, and route behavior, see Static Frontend Guide.

Comparison

	Edge	Docker	Direct	Pack
Command	npx edgebase deploy	npx edgebase docker run	npx edgebase dev	npx edgebase pack --format portable
Requires	Cloudflare account	Docker	Node.js only	Target-platform build machine
Scaling	Auto global	Manual	Single instance	Single local launcher
Best for	Production	Self-hosted prod	Dev / lightweight	Handoff / portable local distribution
Cost	~$5–30/month	VPS cost	Free	Free

Environment Variables

EdgeBase uses separate files for development and production secrets:

File	Purpose	Used by
.env.development	Local dev secrets	npx edgebase dev
.env.release	Production secrets	npx edgebase deploy

Edge (Cloudflare Workers)

The simplest approach — put your production secrets in .env.release and deploy:

# Copy the example template and fill in your production keys
cp .env.release.example .env.release

# Deploy — secrets are auto-uploaded to Cloudflare
npx edgebase deploy

Or set secrets manually one at a time:

npx edgebase secret set JWT_USER_SECRET
npx edgebase secret set JWT_ADMIN_SECRET

info

SERVICE_KEY is auto-generated on first deploy — you don't need to set it manually. The deploy command uses that same key to create the first admin account if the project does not already have one.

Docker / Direct

# Use the env file directly
npx edgebase docker run --env-file .env.release

# Or pass variables inline
JWT_USER_SECRET=your-secret npx edgebase dev