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, an administrator role, 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.
- One role named
Administrator, holding the complete authority tree of the BPMS 3.x administrator by default, so the administrator can grant every authority, processes and documents included, to the roles it creates. - One administrator user with that role and the password you choose.
Steps
-
Load the BPMS 3.x identity schema on the empty database. It is the file
dev/3x/01-identity-schema.sqlof thebpms/bpmsrepository:psql -v ON_ERROR_STOP=1 -f dev/3x/01-identity-schema.sql -
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 withBPMS_MODE=migrate, which migrates, bootstraps, and exits. -
Sign in as the administrator with
BPMS_BOOTSTRAP_ADMIN_PASSWORD, as described in Authentication. The answer carriespasswordChangeRequired: false: the administrator works with that password as it is. -
Set
BPMS_BOOTSTRAP_ENABLEDback tofalseand removeBPMS_BOOTSTRAP_ADMIN_PASSWORDfrom the deployment.
Variables
| Variable | Default | Meaning |
|---|---|---|
BPMS_BOOTSTRAP_ENABLED | false | Runs the bootstrap at startup. |
BPMS_BOOTSTRAP_TENANTNAME | BPMS | Name of the first tenant, at most 50 characters. |
BPMS_BOOTSTRAP_ADMIN_USERNAME | admin | Username of the administrator. |
BPMS_BOOTSTRAP_ADMIN_PASSWORD | none | Initial password; required when the bootstrap is on. Stored as Argon2id. |
BPMS_BOOTSTRAP_ADMIN_IDENTIFICATION | 0 | Identification number, at most 15 characters. |
BPMS_BOOTSTRAP_ADMIN_NAME, BPMS_BOOTSTRAP_ADMIN_LASTNAME, BPMS_BOOTSTRAP_ADMIN_EMAIL | Admin, BPMS, none | Name, last name, and email of the administrator. |
BPMS_BOOTSTRAP_ADMIN_AUTHORITIES | the 3.x administrator tree | The 3.x authority codes of the Administrator role, separated by commas. Unset, they are every code the BPMS 3.x administrator holds. |
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 its role, 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).