Relatude Help

relatude.db.json

Everything that is not code goes in relatude.settings/relatude.db.json: the databases, where they keep their data, the index engines, file stores, AI providers, the admin login and where the datamodel comes from. relatude new and relatude init write the file for you (§31). If it is missing, the server creates one at start that loads the bundled demo model. A store full of Relatude.DB.Demo.Models types means the file was never set up.

relatude.settings/ sits in the root data folder. That is the app's content root, unless ServerOptions.DefaultDataFolderPath names another folder. Relative paths in the file resolve against the root data folder, not against relatude.settings/.

MyApp/                    the content root and the root data folder
├── relatude.settings/    the settings: part of the application, committed and deployed
│   └── relatude.db.json
├── relatude.data/        the database: log, indexes, files; never committed or deployed
└── relatude.data.temp/   scratch space, emptied at every start

relatude.settings/ also holds the custom log definitions (§32.1) and the shared datamodel overrides (§3.1). §12.2 shows the whole layout and what to commit.

At every start, three more layers are merged over the file, in this order:

  1. relatude.db.overrides.json, where the settings pages of the admin UI save their changes. They never write relatude.db.json itself (Changes made in the admin UI).
  2. The RelatudeDB configuration section: appsettings, environment variables and user secrets. This is where secrets such as MasterPassword, TokenEncryptionSecret and API keys belong (Overriding settings from configuration).
  3. The settings callbacks in Program.cs, such as OnServerSettingsInit.

A typical file, with one database on local disk:

{
  "MasterUserName": "admin",                  // the password comes from configuration
  "DefaultStoreId": "8f6b…",                  // the database ctx.Database returns
  "ContainerSettings": [
    {
      "Id": "8f6b…",
      "Name": "MyDatabase",
      "AutoOpen": true,
      "IOSettings": [                         // storage backends, referred to by Id
        { "Id": "1a2b…", "Name": "Local disk", "IOType": "LocalDisk", "Path": "relatude.data" }
      ],
      "IoDatabase": "1a2b…",                  // the transaction log: the source of truth
      "IoBackup": "1a2b…",
      "IoLog": "1a2b…",
      "FileStoreSettings": [                  // where uploaded files go
        { "Id": "c4d5…", "IoProviderId": "1a2b…", "StoreType": "MultiFile", "MultiFileFolderDepth": 2,
          "SameHashSameFile": true, "HashAlgorithm": "SHA256" }
      ],
      "DatamodelSources": [                   // where the node types come from
        { "Id": "7e1c…", "Name": "App", "Type": "CompiledTypes", "Namespace": "MyApp.Models" }
      ],
      "LocalSettings": {                      // the engine: index engines, caches, backups…
        "EnableTextIndexByDefault": true,
        "DefaultFileStore": "c4d5…"
      }
    }
  ]
}

Objects refer to each other by Id. A database names its storage backends and file stores by Guid, so the log, the index files and the file bytes can live in different places without repeating connection details. Most other keys have a working default, so leave out what you do not change.