Instance Bootstrap

Hegemony can bootstrap a fresh application database from mounted Configuration Exchange single-YAML bundles. This is a generic instance provisioning mechanism: demo data, private GitOps bundles, CI-generated onboarding bundles, Helm-mounted ConfigMaps, and Terraform-rendered files can all use the same API-side path.

When HEGEMONY_BOOTSTRAP_ENABLED=true, the API scans HEGEMONY_BOOTSTRAP_DIR during startup after database init, migrations, and internal backend provisioning. If the directory is missing or empty, startup continues without importing anything — and no marker is recorded, so mounting data and restarting the API still bootstraps.

Contract

• Mount one or more *.yaml or *.yml files into the API container.
• Files are loaded from HEGEMONY_BOOTSTRAP_DIR, default /bootstrap.
• Files must be non-empty: an empty bundle file fails bootstrap (and aborts API startup) instead of being silently skipped, so truncated or misconfigured mounts are caught early.
• Files are imported in lexical order using the existing Configuration Exchange single_yaml import service.
• After each bundle, every enabled inventory provider it declared is synced once so a later bundle's flows can target the provider's devices. A provider whose sync did not finish ok is tried once more after the last bundle, since the secret or backend it needs may be defined by a later bundle; a sync that still fails is a warning, never a bootstrap failure.
• A flow's device-target fields name their default devices, and import turns each name into a device id. A name with no device yet is left out of the default, and the import warning names the flow, the field, and the missing devices. Because a provider syncs only after its bundle, a flow can import before the devices it names exist. So after the last provider pass, bootstrap resolves those fields again from the names in the bundle. A field that gains devices is committed as a new flow version; names that still match no device get one more warning. All of these warnings go into the bootstrap run record.
• Bootstrap does not keep unresolved names in the flow: runs accept only device ids as default targets, so a stored name would make every run of the flow fail. Once bootstrap has finished, nothing fills the field in by itself: if the provider syncs later (for example on its next scheduled sync), import the flow's bundle again through Configuration Exchange or set the defaults in the flow editor.
• A successful or no-op bootstrap writes a marker to config_exchange_runs with actor = "instance-bootstrap", operation = "import", and bootstrap metadata in counts_json.
• If that marker already exists for the current database, later API restarts skip bootstrap.
• Failed imports record a failed run when possible, abort API startup, and retry on the next startup.
• Every bootstrap attempt, successful or failed, also writes a config_exchange.import entry to the audit log with system:bootstrap as the actor, so what an instance was seeded with is answerable from the same place as every later import.

No bootstrap-specific table is created.

Settings

Setting	Default	Meaning
HEGEMONY_BOOTSTRAP_ENABLED	false	Enable or disable instance bootstrap. Off by default so production instances never auto-import mounted files; the demo compose overlay enables it.
HEGEMONY_BOOTSTRAP_DIR	/bootstrap	Container directory scanned for YAML bundles.
HEGEMONY_BOOTSTRAP_ENABLE_SCHEDULES	false	Preserve enabled: true schedules during bootstrap.

Normal interactive Configuration Exchange imports still disable schedules by default for safety. HEGEMONY_BOOTSTRAP_ENABLE_SCHEDULES=true is only for operator-controlled first-start bootstrap.

Reapplying Data

Bootstrap is intentionally one-shot per database. To reapply changed bootstrap YAML, either reset the application database or import the changed bundle through Configuration Exchange as a normal operator action.

Demo Data

The public hegemony-demo-data repository is an example source of bootstrap bundles. It owns structured YAML fragments, generates a committed single-YAML bundle in dist/, and verifies that generated output is current in CI. The demo Compose overlay mounts that generated dist/ directory into /bootstrap.