Skip to Content
bpms.ai

New installation

Create the first tenant and administrator of a BPMS installation that starts without BPMS 3.x data.

An installation that starts from an empty database has nobody who can sign in, and so nobody who can create users. BPMS solves this with a one-time bootstrap: on its first start, it creates the first tenant, its initial roles, and the administrator user. An installation that runs on an existing BPMS 3.x database already has its users and never needs it.

What the bootstrap creates

In one transaction, so either all of it is created or nothing is:

  • One tenant, the company or business group of the installation.
  • The roles every tenant starts with: Administrador, with every tenant-level code, and, because this is the installation's tenant, Superadministrador, with every code, tenant management included. Both are protected roles, and both come from one definition of the initial roles in BPMS, so they need no configuration.
  • One administrator user holding only the Superadministrador, with the password you choose.

Steps

  1. Load the BPMS 3.x identity schema on the empty database. It is the file dev/3x/01-identity-schema.sql of the bpms/bpms repository:

    psql -v ON_ERROR_STOP=1 -f dev/3x/01-identity-schema.sql
  2. Start BPMS once with the database migrations and the bootstrap turned on: BPMS_MIGRATE_ON_START=true, BPMS_BOOTSTRAP_ENABLED=true, and the variables in the table below. Alternatively, run it with BPMS_MODE=migrate, which migrates, bootstraps, and exits.

  3. Sign in as the administrator with BPMS_BOOTSTRAP_ADMIN_PASSWORD, as described in Authentication. The answer carries passwordChangeRequired: false: the administrator works with that password as it is.

  4. Set BPMS_BOOTSTRAP_ENABLED back to false and remove BPMS_BOOTSTRAP_ADMIN_PASSWORD from the deployment.

Variables

VariableDefaultMeaning
BPMS_BOOTSTRAP_ENABLEDfalseRuns the bootstrap at startup.
BPMS_BOOTSTRAP_TENANTNAMEBPMSName of the first tenant, at most 50 characters.
BPMS_BOOTSTRAP_ADMIN_USERNAMEadminUsername of the administrator.
BPMS_BOOTSTRAP_ADMIN_PASSWORDnoneInitial password; required when the bootstrap is on. Stored as Argon2id.
BPMS_BOOTSTRAP_ADMIN_IDENTIFICATION0Identification number, at most 15 characters.
BPMS_BOOTSTRAP_ADMIN_NAME, BPMS_BOOTSTRAP_ADMIN_LASTNAME, BPMS_BOOTSTRAP_ADMIN_EMAILAdmin, BPMS, noneName, last name, and email of the administrator.

BPMS_BOOTSTRAP_ADMIN_AUTHORITIES no longer exists: when it is set, the start stops with an explanation and writes nothing, so remove it from the deployment.

Pass the password through the secret store of your deployment, never in a file kept in version control. BPMS never logs, echoes, or writes it.

Safeguards

  • It runs once. When the administrator it created already holds the live Superadministrador, or the role an earlier version of the bootstrap created, a new start changes nothing, even after more users are added. Several instances starting at the same time wait for each other.
  • It never touches existing data. It refuses any database that already holds tenants, users, or roles, and stops the startup with what it found, for example the database already holds 1 tenants, 2 users, and 1 roles.
  • It needs the identity schema. It also refuses to run when the BPMS 3.x identity tables are missing, so load them first (step 1).
  • It writes through the authentication connection. When the deployment sets a dedicated DB_AUTH_USERNAME, that role needs, for this start only, INSERT on tenant, authority (its column role_kind included), users, and users_x_authorities, and USAGE on their sequences; grant them for the start and revoke them after it, or leave DB_AUTH_USERNAME unset for it.

On this page