Changes made in the admin UI: relatude.db.overrides.json

The settings pages of the admin UI never write relatude.db.json. That file describes the application: you write it, keep it in source control and deploy it with the code. What an administrator changes belongs to the installation. So a save from the settings pages writes only the difference from relatude.db.json, into relatude.db.overrides.json:

// relatude.data/overrides/relatude.db.overrides.json
{
  "Name": "Production",
  "ContainerSettings": [
    {
      "Id": "6f1d2c3b-2222-4a5b-9c8d-000000000002",
      "LocalSettings": { "NodeCacheSizeGb": 2.5 },          // a changed value
      "IOSettings": [                                       // an element added here
        { "Id": "a30d711e-…", "$added": true, "Name": "Second disk", "IOType": "LocalDisk", "Path": "second" }
      ],
      "DatamodelSources": [                                 // an element removed here
        { "Id": "6f1d2c3b-4444-…", "$removed": true }
      ]
    }
  ]
}

The file has the shape of relatude.db.json and holds only the keys that changed. List elements are matched on their Id: a changed element holds its Id and the changed fields, an added one is written whole with "$added": true, and a removed one is its Id with "$removed": true.

At every start and soft restart, the settings are built in four layers, each merged over the one before:

Layer	Where	Written by
1	`relatude.db.json`	you, or `relatude init`
2	`relatude.db.overrides.json`	the settings pages of the admin UI
3	the `RelatudeDB` configuration section	appsettings, environment variables, user secrets
4	`OnServerSettingsInit`, `OnContainerSettingsInit`, `OnStoreSettingsInit`	your code

A save takes layers 3 and 4 off before it works out the difference. So neither a secret from configuration nor a value your code sets ever lands in either file.

Unknown keys and values that do not fit are skipped with a warning. A file that is not valid JSON stops the start, because the next save would overwrite it. If its storage cannot be reached at startup, the server starts without it, and the settings pages refuse to save until a restart can read it.

On the settings pages, every field is tagged with where its value comes from:

Tag	The value comes from
default	nothing: the built-in default applies
shared	`relatude.settings/relatude.db.json`, part of the application
this server	`relatude.db.overrides.json`, saved on this installation
appsettings	the configuration section; the field is locked
code	the settings callbacks in `Program.cs`; the field is locked

Move to shared, at the top right of the page, lists what is set only on this server, beside what relatude.db.json says. Choose entries, then:

Move into relatude.db.json writes them into relatude.db.json and removes them from the overrides file. Values from configuration are never moved. The file is rewritten, so its comments are lost, and a moved secret is stored in plain text. Do this in development: on a server, relatude.db.json is the deployed copy, which the next deployment replaces (On a server).
Discard puts back what relatude.db.json says, and saves.

The same tags and Move to shared button are on every page that saves on this server: Databases, Activity, the model editor's overrides (§3.1), Logs (§32.1) and API (§33.2).

Where the file is. It is kept with the default database (the one DefaultStoreId names), in an overrides/ folder in that database's storage: relatude.data/overrides/relatude.db.overrides.json on local disk with the default settings, or a blob under overrides/ on Azure Blob storage. So the admin UI's changes go wherever the database's files go. If you move the default database's folder by hand in relatude.db.json, move the overrides file with it.

ServerOptions.SettingsOverridesFilePath and UseSettingsOverridesFile keep the file elsewhere or turn it off (the options). The CLI finds the file the same way: relatude settings shows where it is and how many settings it changes, and --overrides <file> points elsewhere.