End-to-end process for creating platform database schemas, installing shared system catalogs, bootstrapping the Realm, registering runtime components, activating the platform, and preparing product package deployment.
This page defines the complete operational process for provisioning a new Dream Consistency product environment. It covers database schema deployment, system catalog installation, Realm bootstrap, runtime registration, platform activation, and preparation for Hestino or Legislator product packages.
DreamConsistency.SystemCatalogInstaller.Cnsl artifact or Docker image
for shared Realm, Management, and Billing catalogs. Catalog files are embedded in the installer dependencies;
Jenkins does not download loose JSON files.
The self Realm row requires an environment reference and an operational status reference.
Therefore INF_Environments and INF_RealmOperationalStatuses must exist before
DreamConsistency.RealmBootstrap.Cnsl can create the self Realm.
SystemCatalogInstaller.Cnsl persists Realm.Foundation.
RealmBootstrap.Cnsl verifies it and then creates the self Realm and first Core operator.
TargetDatabase is an explicit required input. A normal installer execution opens only the
corresponding TransactionContext and uses only that database connection.
| Target Database | Transaction Context | Catalog Content |
|---|---|---|
| Realm | RealmTransactionContext |
Realm shared system catalog packages. |
| Management | ManagementTransactionContext |
Management shared system catalog packages. |
| Billing | BillingTransactionContext |
Billing shared system catalog packages. |
All mode may orchestrate the databases sequentially,
but Realm, Management, and Billing remain independent transactions.
All mode creates a separate result for Realm, Management, and Billing. A successful Realm or Management commit is not rolled back if a later Billing operation fails.
The official DEV, QA, Staging, and Production path is a controlled Jenkins job that runs a versioned installer release or immutable Docker image. The installer release represents a tested compatibility set of Catalogs, Tables, EntityManager, and installer code versions.
| Parameter | Example | Rule |
|---|---|---|
APPLICATION_SCOPE |
Hestino / Legislator | Determines target deployment and Vault path. |
TARGET_ENVIRONMENT |
Development / Testing / Staging / Production | Choice parameter, never unrestricted free text. |
TARGET_DATABASE |
Realm / Management / Billing / All | All orchestrates independent database transactions. |
INSTALLER_VERSION |
1.2.0 | QA and PROD use an explicitly promoted immutable version. |
INSTALLATION_MODE |
All / Package / Validate / DryRun | Controls execution behavior. |
PACKAGE_NAME |
DreamConsistency.Realm.Foundation | Required only in Package mode. |
EXPECTED_DATABASE_NAME |
realmdb | Additional database identity guard. |
| Environment | Version Selection |
|---|---|
| Development | May use the newest published release or an explicit version. |
| Testing / QA | Uses a specific version already executed successfully in Development. |
| Staging | Uses the exact release candidate intended for Production. |
| Production | Uses an explicit immutable version tag or image digest; never blindly uses latest. |
Production installation is manual and approval-controlled. It has no SCM webhook, schedule,
blind automatic retry, or unrestricted latest resolution.
Jenkins archives a machine-readable result and a human-readable sanitized report. The ephemeral process or container is removed after execution.
Connection strings and database credentials are retrieved from HashiCorp Vault by Jenkins and exist only
during execution. They are not stored in Git, tracked appsettings.json, CLI arguments,
Docker images, installation history, or logs.
Before the first write, the installer runs SELECT DATABASE() and compares the result with
EXPECTED_DATABASE_NAME. A mismatch causes immediate rejection.
The Jenkins execution job must disable concurrent builds. The installer must also acquire a database-specific named or advisory lock on the same physical connection used for the target transaction.
Dry-run is the required visibility step before Production installation. It calculates the same dependency order, UUID comparisons, update rules, and conflicts without committing writes.
| Scenario | Behavior |
|---|---|
| Invalid embedded package. | Reject before opening the database connection. |
| Schema incompatible. | Reject without database writes. |
| Dependency missing. | Reject or include the dependency according to command mode. |
| Catalog name / UUID conflict. | Rollback the entire target-database transaction. |
| Database write failure. | Rollback and return a sanitized database failure exit code. |
| Lock unavailable. | Reject as concurrent installation. |
| Realm succeeded, Billing failed in All mode. | Realm remains committed; Billing is retried separately. |
| Installed version newer than available. | Reject downgrade. |
| Manual database drift. | Dry-run reports the conflict; no automatic destructive repair. |
Retry is safe because comparison is UUID-based and does not create duplicate catalog rows. Jenkins does not blindly retry Production. The operator first reviews status and failure code, corrects the cause, and runs the same immutable installer version again.
--force:
Reactivating a soft-deleted system item, replacing a wrong legacy UUID, or performing a controlled
downgrade requires a separate explicit recovery operation with dedicated validation and audit.
The installer version changes whenever a Catalogs dependency, database mapping, update rule, schema compatibility matrix, command, lock, history, security, or logging behavior changes.
DreamConsistency.ManagementCatalogs.DreamConsistency.BillingCatalogs.DreamConsistency.SystemCatalogInstaller.Cnsl as a .NET 10 console application.DreamConsistency.RealmCatalogs provider and validator.DreamConsistency.RealmBootstrap.Cnsl to validate Foundation instead of installing it.| Date | Change | Author |
|---|---|---|
| 2026-08-01 | Initial end-to-end Dream Consistency environment provisioning process documented. | Branko |