Platform Configuration
Settings → Platform Configuration lists every platform setting: each HEGEMONY_* environment variable from the environment variable reference, and the settings of each installed extension. Only a platform admin can open it, and change the settings marked Editable.
For each setting the page shows:
- Value: the value the API process runs with.
- Source: where the value came from. Set in UI is a value a platform admin stored on this page (hover the badge to see who and when), and the value the environment would give without it shows under it. Environment is an environment variable (hover the badge to see which one, including an older name the setting still reads), .env file is the
.envfile in the process's working directory, and Default is the built-in default. A value that is not at its default also shows the default under it. - Status:
- Editable: a platform admin can change it here.
- Environment only: it can only come from the environment, with the reason. The platform needs it before it can read its database, it differs between processes or hosts, it names a mount or a service of the deployment, it is key material that must stay outside the database, or a wrong value would lock every admin out of sign-in. Extension settings are environment-only, because an extension reads its settings once, when the platform discovers it.
- Secret: the value is never shown. The page says only whether it is set. There is no way to reveal it: the API never sends the value. No secret can be changed here.
- Security: changing it moves a security boundary.
- Restart needed: editable, but read when a process starts, so a change applies after the processes restart. Until then the page shows the value a restart brings under the one in force ("after restart"): the stored value, or after a reset the environment's. Meanwhile a running process keeps the value it started with, so the parts built from it at startup and the parts that read it again never disagree.
A password inside a URL, such as the one in HEGEMONY_DATABASE_URL, is replaced by *** in any value the page shows. Saving such a value as the page shows it keeps the stored password; a changed value that still holds *** is refused, so type the password again to change it.
Search filters by variable name, description and value. Only values not at their default hides the settings whose value equals the default.
Changing a setting
Change on an editable setting opens a dialog with the value in force, the environment's value when one is stored, the default and the type. Saving asks for a fresh sign-in, and records the change in the audit log (platform_setting, with the value before and after). A setting marked Security asks you to confirm that you understand the risk first.
- The value is checked together with every other setting, with the same rules the platform applies at startup, and refused with the reason when it does not pass.
- A stored value wins over the environment variable. Changing the environment variable later does not replace it; the page keeps showing the environment's value beside it.
- It applies to every process: the API replica you saved on at once, every other API replica, every worker and the scheduler within about ten seconds. A setting marked Restart needed applies after the processes restart; until then, and after a reset, the page says a restart is still needed. A worker or the scheduler that cannot reach the API when it starts retries for about a minute, then runs on the environment's values and logs an error. Settings marked Restart needed then keep the environment's values: restart that worker or the scheduler again once the API answers.
- Reset to environment removes the stored value; the environment variable or the default applies again.
The values are stored in the platform_setting_overrides table. If a stored value stops passing the checks (an environment variable it depends on changed, say), each process logs an error and keeps the values in force.
Export and import
Export downloads every setting as a JSON file (hegemony-platform-configuration-<time>.json), for a record of a deployment or to compare two. Each entry carries its value as the page shows it, where it came from, and whether an import may set it (importable: editable and not secret). A secret is never included, only whether it is set, and passwords inside URLs stay masked.
The values stored on this page also travel with Configuration Exchange, in the platform_settings section of a bundle: an export carries them, and an import sets them under the same rules as this page (editable settings only, checked together with every other setting, platform admins only, after a fresh sign-in as on this page). The import is committed first and then applied, like a save on this page. Settings that come from the environment stay out of a bundle, as before.
For developers
The classification of each setting (its section, and whether it is secret, environment-only, security-sensitive or needs a restart) lives in packages/core/settings_catalog.py. A new field in packages/core/settings.py must be added there too, or tests/core/test_settings_catalog.py fails. A setting missing from the catalog is treated as secret and environment-only, so a gap can only hide a value.
A stored value reaches code that reads get_settings().<name> where it uses the setting, or holds the settings object: packages/core/settings_overrides.py changes that object in place. A setting in _RESTART_REQUIRED is changed only when a process starts. A setting read once at startup into a local, a client or a middleware belongs in _RESTART_REQUIRED in the catalog, unless its reader is changed to read it again (as the scheduler's poll intervals and the CORS check do). The API applies stored values at startup and then every REFRESH_SECONDS; workers and the scheduler fetch them from GET /internal/platform-configuration/overrides (apps/worker/platform_settings.py).
An extension marks a secret setting with json_schema_extra={"secret": True} on its field. A field whose name says it holds key material (token, secret, password, pepper, key) is treated as secret even when unmarked.
The page reads GET /settings/platform-configuration and GET /settings/platform-configuration/export, which need the platform_configuration:view action. Changing and resetting use PUT and DELETE /settings/platform-configuration/{key}, which need platform_configuration:manage and a fresh sign-in. Both actions are platform admins' by default.