3.4 Configuration Management
3.4.1 Configuration Model
Configuration exists in two places, and understanding the relationship is necessary before editing anything.
-
On disk: the two merged files described in 2.4.4. These are read at startup and are what the service actually runs on.
-
In the database: versioned configuration schemas, which is what the System Configuration screen in the portal reads and writes.
A file watcher restarts the service when the on-disk configuration changes, so a file edit takes effect without an explicit restart.
In a container deployment the on-disk files are regenerated from the environment file at every container start, so an edit made in a running container is lost on restart. Edit the environment file instead. This is a mistake that appears to work and then silently reverts.
3.4.2 Versioned Configuration and History
Each configuration change creates a new version. Prior versions are retained.
The active version is identified, and version history is browsable.
A previous version can be restored, which makes a bad change recoverable.
Changes are attributable, which is what makes configuration part of the audit trail rather than a mystery.
3.4.3 Editing Configuration Safely
Never hardcode a value that the configuration system provides. Every service reads configuration dynamically.
Change one thing at a time, and validate after each change. The file watcher restarts the service, so a broken change takes effect immediately.
Take a copy of the current configuration before a substantial change, independently of the version history.
Be aware of a platform-specific caveat: the configuration writer opens the file without an explicit character encoding, so a configuration value containing a non-Latin-1 character can cause the write to fail on Windows and report failure without writing the file. Avoid non-ASCII characters in configuration values until this is fixed. Documenting this is more useful than leaving an administrator to discover it.
3.4.4 Restore and Rollback
-
From version history: select a previous version and restore it. Appropriate for a configuration mistake.
-
From a file copy: replace the on-disk file and let the watcher restart the service, or restart explicitly.
From the environment file, in a container deployment — correct the variable and restart the container, which regenerates the configuration.
After any restore, verify the version endpoint responds and that a data view loads. A restored configuration that starts is not necessarily a configuration that works.