Skip to main content
A private deployment should start with public signup disabled. Configuring an email in the owner or platform-admin allowlist authorizes that identity after authentication; it does not create an account, choose a password, or generate a default administrator password. Releases that include initial-administrator bootstrap provide a dedicated setup page at:
Chart and image versions without /setup do not support this private bootstrap flow. Upgrade before attempting first-user setup. Entering an allowlisted email on the normal sign-in page cannot create a missing account.

​
Before installing

  1. Configure the initial administrator email as an eligible singleton-organization owner (DEN_SINGLE_ORG_OWNER_EMAILS on Den API).
  2. Add the same email to the platform-admin allowlist only if that person also needs deployment-wide /admin access.
  3. Generate a unique one-time setup code.
  4. Inject the code through a Kubernetes Secret or your platform’s secret store as DEN_INITIAL_ADMIN_BOOTSTRAP_CODE, or mount it from a file and set DEN_INITIAL_ADMIN_BOOTSTRAP_CODE_FILE.
  5. Keep public signup disabled.
The setup code is a plain secret string, not a hash or token generated by OpenWork. Never place the real setup code in a committed Helm values file, ConfigMap, container image, source-control file, support ticket, screenshot, logs, or PR.

​
Docker Compose evaluation stack

The evaluation stack passes the same two Den API variables through OPENWORK_OWNER_EMAILS and OPENWORK_SETUP_CODE. Set them in the .env file beside docker-compose.eval.yml, together with OPENWORK_ALLOW_SIGNUP=false, before the first docker compose up:
Then open http://localhost:3005/setup and continue with Complete setup. The .env file holds the real setup code, so keep it private and do not commit it.

​
Complete setup

  1. Wait until Den web, Den API, and the migration Job are healthy.
  2. Open /setup on the Den web hostname.
  3. Enter the configured administrator email and the one-time setup code.
  4. Choose the administrator’s name and password.
  5. Confirm that OpenWork signs the administrator in and opens the singleton organization.
The setup flow uses the existing Better Auth password and session protections. Successful setup creates the first account, creates or claims the singleton organization, grants the configured owner and platform-admin roles, and makes setup unavailable because the deployment now has a user.

​
Verify the boundary

After setup:
  • revisiting /setup reports that setup is complete or unavailable;
  • the one-time code cannot create another administrator;
  • unknown users still cannot sign up;
  • the administrator can sign out and use normal password sign-in;
  • restarting or scaling Den API does not re-enable setup.
If the deployment already contains a user, bootstrap remains unavailable even if its setup Secret still exists. Rotating or restoring the Secret does not reopen setup unless an operator deliberately changes the database outside OpenWork.

​
Configure SSO next

Use the first owner as a break-glass account, then configure SAML or OIDC SSO and SCIM for normal workforce access. Protect the break-glass identity and recovery material according to your organization’s access-control policy.