Production setup

Production setup is an operator task. Start from a supported source release, preserve your existing data and test upgrades on a restored backup before changing the live workspace.

Required setup

Configure	What to provide
Database	A PostgreSQL 17 connection through `BEEPGRID_DATABASE_URL`
Public URL	Your HTTPS workspace origin in `BEEPGRID_PUBLIC_URL`
Owner credential	A protected `BEEPGRID_BOOTSTRAP_TOKEN`; an existing workspace requires its current valid owner credential
Server identity	A stable, protected `BEEPGRID_SECRET_KEY` containing 64 hexadecimal characters
Workspace scope	Explicit `BEEPGRID_WORKSPACE`, `BEEPGRID_ENVIRONMENT` and `BEEPGRID_COMPANY` values for this deployment
Listener	The application address in `BEEPGRID_ADDR` behind your HTTPS proxy
Files	Persistent private attachment storage through `BEEPGRID_ATTACHMENTS_DIR` or your supported object-store composition
Sign-in and people	Your supported Person authentication and explicit workspace/contact permissions
Email	Verified SMTP/provider settings if email delivery is needed

Store these values in your deployment’s secret manager or protected environment file. Do not copy another workspace’s credentials or use the local playground’s bootstrap token for shared production access. Keep the database, encryption key and private file storage together across restarts.

For Person sign-in, basic OIDC uses BEEPGRID_OIDC_ISSUER, BEEPGRID_OIDC_CLIENT_ID and BEEPGRID_OIDC_CLIENT_SECRET. Register your HTTPS origin followed by /auth/oidc/callback with your identity provider. A newly verified person still needs explicit workspace/contact grants. The managed application’s Google/passwordless onboarding is a separate hosting feature.

Build, migrate and serve

From the checkout, with your protected environment configured:

go build -buildvcs=false -o .local/beepgrid ./cmd/beepgrid
.local/beepgrid migrate
.local/beepgrid serve

Back up the database and private files before migrating. Use the complete release migration sequence and a runtime database role appropriate for normal serving. Never run public production with --dev.

Optional Coordinator

Set BEEPGRID_AI_PROVIDER to openai, anthropic, google or openai-compatible, and select an available model explicitly with BEEPGRID_AI_MODEL. Supply the provider credential as BEEPGRID_AI_API_KEY. An OpenAI-compatible endpoint also needs its BEEPGRID_AI_BASE_URL; private endpoints require the explicit BEEPGRID_AI_ALLOW_PRIVATE option.

Then enable Coordinator for the workspace. Provider configuration alone does not enable it. Keep API credentials server-side and verify a harmless actual model exchange before relying on it.

Operational checks

Check /healthz and /readyz through the intended route.
Verify sign-in, a restricted user’s access, a real worker reply and file persistence.
Expose only the exact HTTPS channel callbacks required by your integrations.
Back up and restore both database history and referenced files.
Revoke retired worker credentials and test recovery without creating duplicate messages.

Before an upgrade, stop or drain the old writers, back up the database and files, run the new binary’s migrate, then start serve. Do not run mixed schema versions or downgrade a migrated database. Restore into an isolated environment and reconcile uncertain work before resuming it.

Managed account control-plane features, shared provider app distribution and company onboarding are separate from operating the OSS workspace.

Read this page as Markdown