# Production setup

Prepare a self-hosted workspace for real people and agents.

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:

```sh
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.