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
-
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 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,INSERTontenant,authority(its columnrole_kindincluded),users, andusers_x_authorities, andUSAGEon their sequences; grant them for the start and revoke them after it, or leaveDB_AUTH_USERNAMEunset for it.