Create the first operator

Implementation preview: these instructions describe locally verified development work that is not yet included in a published Webdock core release. Use them only with the matching implementation; the currently published main branch does not include all commands and paths below.

Run this once after the offline database installation. The command creates a local operator, its explicit Console identity mapping and a confidential OAuth client. It creates no login session, authenticator secret, backup codes, customer, provider account or Mail instance. This procedure initializes the native Auth foundation in apps/control-plane, served through apps/auth, and the Console client used by apps/console. It also precedes a configured Clerk installation: finish local setup first, then follow authentication adapters for explicit external-subject mappings. This command never links accounts by email or replaces existing identities.

Open the private browser setup

Use the dedicated webdock_offline_migrate database login created by the installer, through DATABASE_URL_UNPOOLED. Keep this credential offline. Remote connections require DATABASE_CA_CERT. Set the exact canonical BETTER_AUTH_URL, WEBDOCK_STUDIO_ORIGIN and WEBDOCK_CONSOLE_ORIGIN in this command’s environment before starting. These three origins must be distinct; use HTTPS except for explicit loopback development with a loopback database. Run the command on the same machine as your browser. Pass the exact host:port/database and a new private output filename:

umask 077
bun run setup:admin db.example.com:5432/webdock /private/initial-operator-secrets.json

Open the private http://127.0.0.1:…/#… link printed in the terminal. Treat the entire link as a setup credential. The random capability stays in the URL fragment, is removed from the address bar when the page loads, and authorizes only this temporary local session. The command always binds to 127.0.0.1; there is no public setup route or configurable public bind address. The session expires after ten minutes. An optional final argument sets an expiry of 60–900 seconds. The form shows the configured origins without allowing changes. Enter your name, email and a unique temporary password of 16–128 characters, and confirm that you have verified ownership of the address. Provisioning marks that address verified without sending a verification email. Unset WEBDOCK_INITIAL_OPERATOR_PASSWORD when using the browser form. The server accepts one submission at a time and stops after success or an uncertain commit. Client credentials never appear in the browser response: they go exclusively to the selected output file, created with mode 0600 without overwriting an existing file or following a symlink. The terminal reports only record IDs and a metadata checksum. After success, continue with application service configuration and real security setup below. If a connection closes during submission, check the terminal and private output before retrying. The following capture shows a successful local test with example origins. Account fields are cleared after creation; credentials remain in the private output file.

Local setup confirmation showing Operator created and instructions to configure services, change the password and enable an authenticator

Use private JSON input instead

Use the dedicated webdock_offline_migrate database login created by the installer, through DATABASE_URL_UNPOOLED. Keep this credential offline. Remote connections require DATABASE_CA_CERT. The command takes the exact host:port/database separately and refuses a different target or a runtime/superuser login. Choose three distinct canonical origins before provisioning: Auth, the Studio compatibility protocol, and Console. The callback stays on the Studio protocol origin. Do not substitute the Console origin in OAuth callbacks, issuer settings or MCP audiences. Set BETTER_AUTH_URL, WEBDOCK_STUDIO_ORIGIN and WEBDOCK_CONSOLE_ORIGIN in the private command environment. They must exactly match the input. HTTPS is required except for explicit loopback development with a loopback database.

umask 077
cat > initial-operator.json <<'JSON'
{
  "email": "operator@example.com",
  "name": "Initial operator",
  "authOrigin": "https://auth.example.com",
  "studioOrigin": "https://studio.example.com",
  "consoleOrigin": "https://console.example.com"
}
JSON

Use an address whose ownership you have verified. Offline provisioning marks that address verified; it does not send a verification email. Supply a unique temporary password of 16–128 characters either as password in this private JSON file or through WEBDOCK_INITIAL_OPERATOR_PASSWORD, never both. For an interactive shell, avoid putting the password in command history:

read -rs WEBDOCK_INITIAL_OPERATOR_PASSWORD
export WEBDOCK_INITIAL_OPERATOR_PASSWORD
bun --no-env-file tools/migrations/operator.ts \
  db.example.com:5432/webdock \
  initial-operator.json \
  initial-operator-secrets.json
unset WEBDOCK_INITIAL_OPERATOR_PASSWORD

To use the migration image instead, first replace the bootstrap administrator URL in migrator.env with the dedicated offline migrator URL, remove the empty-database bootstrap settings, and include the same canonical origins/password configuration. The image’s normal entrypoint runs schema installation, so override it explicitly for this command. Mount a private input/output directory owned by the selected container user:

docker compose -f deploy/compose/compose.yaml --profile migration run --rm \
  --entrypoint bun --user "$(id -u):$(id -g)" \
  --volume "$PWD/private-setup:/setup" migrate \
  tools/migrations/operator.ts db.example.com:5432/webdock \
  /setup/initial-operator.json /setup/initial-operator-secrets.json

The input must be owned by the current OS user and have no group/other permissions. Symlinks are refused. The output is created exclusively with mode 0600; an existing path is never overwritten. Standard output contains only record IDs, a metadata checksum and the setup-required flag. The command refuses existing operators, earlier bootstrap audit records, an existing identity with that email, or existing OAuth applications. It never upgrades an existing user, rebinds a client or repairs a previous installation automatically. Other existing users remain unchanged.

Configure the application services

After a successful command, retain the private output in your secret-management system. Its environment object contains the issuer and canonical origins, matching WEBDOCK_SSO_CLIENT_ID / WEBDOCK_STUDIO_CLIENT_ID, WEBDOCK_SSO_CLIENT_SECRET and a separate WEBDOCK_SSO_COOKIE_SECRET. Apply these to the API runtime configuration. Do not expose this file in public build arguments, browser bundles or source control. Configure the Auth and Console UI origins and their API connection separately, following the deployment configuration. Complete the runtime database roles, context signing key, Auth signing secret, trusted ingress and HTTPS configuration before starting services. The initial-operator command does not create DNS, certificates, reverse-proxy routes or deploy containers. The Console client uses the exact registered paths:

Setting	Value
Issuer	Auth origin plus `/api/auth`
Callback	Studio protocol origin plus `/api/sso/callback`
Logout return	Studio protocol origin plus `/login`
Client authentication	`client_secret_post`
Authorization	Authorization code with PKCE

The private output uses status: "verify-command-result": only the command’s successful exit confirms the database commit. If it reports an uncertain commit, retain the file and inspect the printed/recorded IDs and bootstrap metadata before retrying. Do not delete or replace a possibly active client to repeat setup.

Complete real security setup

Open the Auth origin at /sign-in directly. Sign in with the initial email and temporary password.
On /account, change the temporary password to a unique password only you know.
Enable the authenticator using that password, scan the displayed QR code in your authenticator, save the recovery codes privately and verify a current code.
Open the Console origin. Its normal login flow uses the registered Studio protocol callback. Operator authorization remains unavailable until password setup and MFA enrollment are complete.

No SQL edit to twoFactorEnabled, manual session insertion or synthetic cookie is part of this flow. Existing authorization rechecks the current native user, session and binding. Configure a working system-authentication email transport for password recovery; customer Mail installation is independent of that transport. You can complete setup with all optional product modules disabled. Enabling a product later does not grant its permissions or provision resources.

Verification boundary

The repository’s opt-in disposable PostgreSQL test covers the offline command and real Auth password-change, MFA and OAuth handlers. It does not deploy or certify your DNS, TLS, reverse proxy or browser UI build. Validate those deployment-specific routes before exposing the installation. Review installation modules before enabling products or assigning workers.

Integrations

Mail

Plugins

Operate Webdock

Contribute

Create the first operator

Open the private browser setup

Use private JSON input instead

Configure the application services

Complete real security setup

Verification boundary

​Open the private browser setup

​Use private JSON input instead

​Configure the application services

​Complete real security setup

​Verification boundary

Open the private browser setup

Use private JSON input instead

Configure the application services

Complete real security setup

Verification boundary