Contents

Profiles

A folder of plain files carrying a whole configuration: what it holds, what it may set, how it is validated and applied as a whole, and how a deployment is compared with it.

A profile is a folder of plain files holding a whole configuration: the settings, the sources, and the rules that decide who may read them. It is how a second office is set up like the first, and how a rebuilt server comes back the way it was, without anyone remembering which settings were changed.

shell01
prem profile validate <folder>    check it against this deployment, change nothing
prem profile apply <folder>       apply it, or refuse the whole profile
prem profile show [<folder>]      what is applied, and how this deployment differs

The folder holds profile.json (a name, a version, and the seam versions it expects; the name follows the rule a source's name does, up to 64 letters, digits, dots, hyphens and underscores, starting with a letter or digit) and, as it needs them, settings.json, groups.json, sources.json and golden-set.json. A file a profile does not know is refused rather than ignored: a profile that quietly skips a file is a profile that quietly does not configure something.

A profile can set what an administrator can set, and nothing further. There is no file in it that creates a user, grants a role, puts somebody in a group, or writes a rule naming somebody who does not exist.

In settings.json, null unsets a setting, as prem settings unset does, so its default applies; a trust setting cannot be unset. The MCP authorization flow's settings are checked as the whole profile would leave them, so a profile that turns the flow on and sets its address is valid whatever the order of its lines (see The authorization flow).

A profile can create the groups it names. groups.json lists their names:

shell02
[ "hr", "engineering" ]

The groups are applied before the sources and the rules, so a rule may name a group the same profile creates, and a fresh server takes the starter profile in one step:

shell03
prem profile apply ./samples/profiles/starter

A group that exists already is left as it is. A group the profile creates is recorded in the change record like one made on the groups page. Who is in a group is not in a profile: an administrator adds the members. The starter profile names hr because its rule does, and engineering because its golden set asks a question as somebody in it to prove that person is told nothing.

prem profile validate names every group, user or agent a rule names that neither exists nor is in groups.json, so the list of what to create is the output of a validate run rather than something to work out by reading the files.

validate reports every problem it finds rather than the first, and changes nothing. apply validates the whole profile before it writes anything, so a profile with one bad item changes nothing at all. The apply itself is not one transaction, because the settings, sources and rules each carry their own; what holds is that nothing is applied unless everything validated, and a failure part way through names exactly what was applied and what was not.

A source's folder may be written relative to the profile, so a profile can ship the documents it configures. A source's folder and prefix cannot be changed by applying a profile, since that would mean removing the source and indexing a whole corpus again.

golden-set.json is copied to a folder the server can read (--golden-set-dir, by default Premagentic-golden-sets in the shared application data folder, C:\ProgramData\Premagentic-golden-sets on Windows) and the golden set path is set to the copy. The default is shared rather than per-account on purpose: the file is read by the account the service runs as, which is usually not the account applying the profile. Every account on the machine may read what is copied there, the Windows service's account included, by the rules C:\ProgramData gives the folders made in it. The folder is beside setup's credentials folder (C:\ProgramData\Premagentic for the Windows service) and never in it, so a profile applied before setup does not make that folder with those rules, which setup would refuse.