# Configuration & Deployments

> Module configurations, Configuration Variables, secrets, and copying configuration between Instances.

URL: https://www.trakhound.com/docs/trakhound-framework/configuration

A configuration links a Package to the settings it runs with: its route, Volume, Router, and parameters. One Package can run under several configurations, each with its own settings. Configurations are created in the admin UI under **Config**, which saves them as YAML files in the Instance's configuration profile.

Diagram: One installed Package, MyCompany.Machines.Api, with versions 1.3.2 and 1.4.0 installed side by side, runs under two configurations: one at the route line1/machines and one at line2/machines, each with its own Volume and parameters. Both read the sqlServer Configuration Variable.

## Configuration Files

Each configuration is stored in the profile's configuration directory, grouped by category:

```
config/
  default/
    instance.config.yaml      Instance settings (see Instances)
    variables.config.yaml     Configuration Variables
    api/            One file per configured API
    app/            One file per configured App
    function/       One file per configured Function
    worker/         One file per configured Worker
    service/        One file per configured Service
    router/         One file per Router
    identity/       One file per Identity provider
    group/          One file per Group
    zone/           One file per Zone
```

For example, an API configuration:

```
id: example-api
name: Example API
route: example/api
volumeId: example
routerId: default
packageId: TrakHound.Example.Api
packageVersion: "*"
httpEnabled: true
parameters:
  directory: ${dataPath}/files
```

| Key | Applies To | Description |
| --- | --- | --- |
| `id`, `name`, `description` | All | Identify the configuration. |
| `packageId`, `packageVersion` | All | The Package to load. A version of `*` uses the newest stable installed version, and patterns such as `1.2.*` also work (see [Versions](https://www.trakhound.com/docs/trakhound-framework/packages)). |
| `parameters` | All | Name and value pairs read by the module. Values can reference [Configuration Variables](https://www.trakhound.com/docs/trakhound-framework/configuration#variables). |
| `volumeId` | All | The [Volume](https://www.trakhound.com/docs/trakhound-framework/volumes-and-variables) provided to the module. Empty uses the configuration `id`. A Package's `.defaultVolumeId` fills in an empty value when a version the configuration runs is installed; the module then uses that Volume, and its files aren't moved. |
| `routerId` | All but Services | The [Router](https://www.trakhound.com/docs/trakhound-framework/routing) used for data requests. Empty uses the Router of the configuration's Group, then `default`. |
| `groupId` | API, App, Function, Worker | The [Group](https://www.trakhound.com/docs/trakhound-framework/configuration#groups) the configuration is in. |
| `route` | API, App | The route the API or App is served at. Must be unique. |
| `httpEnabled` | API | `false` serves the API only inside the Instance (to other modules). |
| `mcpTools`, `mcpReadOnly`, `mcpInclude`, `mcpExclude` | API | Which endpoints are served as [MCP Tools](https://www.trakhound.com/docs/trakhound-framework/mcp-server#api-tools). |
| `functionId` | Function | The ID used to run the Function. |

### Adding a Configuration

1. In the admin UI, open **Config**, choose the category (for example **Api**), and click **Add**.
2. Choose a Package **From Source** or **Installed**. Tick **Use Latest Version** to follow updates.
3. Fill in **General** (Name, Route, Function ID, Volume, Router, and so on), the **Settings** provided by the Package, and any **Parameters**.
4. Click **Add**. Each list shows whether a configuration is Running, Not loaded, or Package missing.

> A Package can list its parameters in its manifest (`".configurationParameters": "host,port,useSsl"`) so they appear as fields in the configuration form.

## Secret Parameters

Parameters whose names contain `password`, `token`, or `secret`, or end in `key` (but not `name` or `id`), are encrypted in the configuration file when it is saved, and are hidden in the admin UI. Modules read them decrypted with `Configuration.GetParameter(name)`.

## Configuration Variables

Configuration Variables are values shared by every configuration in a profile, such as a data directory or a server name that many modules use. Reference one from any parameter value as `${name}`, or an environment variable of the Instance process as `${env:NAME}`. `$${name}` is the literal text `${name}`.

```
# variables.config.yaml
dataPath: D:\TrakHound\Data
sqlServer: sql01.mycompany.local

# A Function configuration
parameters:
  directory: ${dataPath}/reports
  server: ${sqlServer}
  apiKey: ${env:REPORTS_API_KEY}
```

- Edit Variables in the admin UI under **Config > Variables**, which shows how many configurations use each one and lists references to Variables that are not defined.
- Variables named like a secret are encrypted when saved and are never shown again. Type a new value to replace one.
- Variables are read when the Instance starts. After saving, click **Restart Instance** to apply them.
- A reference to a Variable that is not defined is left as it is, and a warning is logged.

In a module, `GetParameter()` returns values with references replaced (read parameters through it rather than the `Parameters` dictionary). APIs, Apps, Functions, and Workers can also read a Variable by name:

```
var dataPath = GetConfigurationVariable("dataPath"); // null if it isn't defined
```

> Configuration Variables are different from a module's [Variables](https://www.trakhound.com/docs/trakhound-framework/volumes-and-variables#variables), which store small values a single module remembers between runs.

## Groups

A Group organizes APIs, Apps, Functions, and Workers, such as the modules of one line, and sets the [Router](https://www.trakhound.com/docs/trakhound-framework/routing) of those that don't name their own. Groups never restrict anything: a [Zone](https://www.trakhound.com/docs/trakhound-framework/zones) can list a Group (`group:{id}`) to restrict every module in it.

1. Under **Config > Groups**, click **Add Group** and give it an ID, which modules and Zones refer to it by.
2. On its page, set a Name, Description, and **Router**.
3. Add modules with **Add Module** on the Group's page, or pick the Group on a module's configuration page.

**Explorer** lists a Group's modules in a folder for the Group, and filtering by its name shows them. The Group's page lists the Zones that refer to it, and removing a Group takes its modules out of it. `th packages install <packageId> --configure --group <id>` puts the configurations it adds in a Group.

## Deployments

A Deployment copies an Instance's configurations and Packages, and optionally its Package data (Volumes and Package Variables), to other Instances. Create and install Deployments in the admin UI under **Deploy**, or with the [CLI](https://www.trakhound.com/docs/trakhound-framework/cli) (`th deployments`).

| Section | What you can do |
| --- | --- |
| **Create** | Choose **Full** or **Incremental**, a Version and Description, the configuration profile, the **Configurations** to include (all, or only some categories such as Api, Functions, Services, or the profile's Instance Settings), which Packages to include (all installed, only those used by configurations, or **None**), which **Volumes** and **Package Variables** to include (none by default), and whether to **Include Secrets** (the admin accounts, Users, API keys, and secret values; without them the target keeps its own). Recent Deployments can be downloaded again. |
| **Install** | Drop a Deployment file, review the changes (including the licenses a Deployment for this device adds), optionally back up first, then click **Stop Instance and Install**. |
| **Backups** | Restore or delete a backup made before an install. |
| **Workspaces** | Create, open, export, and delete [Workspaces](https://www.trakhound.com/docs/trakhound-framework/configuration#workspaces), which hold the configuration for other Instances. |

- **Copy only settings** - Include only the configuration categories you want and choose **None** for Packages. Installing replaces only the included categories, and the Package versions on the target are not changed.
- **Variables and Zones** - A Deployment includes the profile's Configuration Variables (`variables.config.yaml`, part of the Instance Settings category, so leaving out Instance Settings leaves them out too), and can include [Zones](https://www.trakhound.com/docs/trakhound-framework/zones).
- **Secrets** - A Deployment made with Include Secrets carries the secret values. Store and send the file securely.
- **Package data** - Include the [Volumes](https://www.trakhound.com/docs/trakhound-framework/volumes-and-variables) (folders in the `volumes` folder, ex. a configuration's ID) and Package Variables (one collection per configuration ID) that hold settings your Packages keep:
  - Installing adds or replaces the Deployment's Volume files. Other files in the target's Volumes are kept, and nothing is deleted.
  - Each Package Variables collection replaces the target's collection with the same ID.
  - Incremental Deployments include only the Volume files and collections changed since the last Deployment, and backups include what the install replaces.
  - They're copied as they are, and Include Secrets doesn't apply to them, so don't include Volumes that hold passwords or keys unless you would include secrets.

Jobs and Scheduled Tasks are copied between Instances separately, with [Export and Import](https://www.trakhound.com/docs/trakhound-framework/functions#export-import) on the Schedule Board.

### Installing a Deployment at Startup

When it starts, before it reads any configuration, the Instance installs the deployment files (`.thd`) in its `deployments` folder. Use this to set up a new Instance with a known set of configurations and Packages: select a file on the Windows installer's **Deployment** page (or pass `/DEPLOYMENT=`), pass `--deployment` to the Linux `install.sh`, or copy a file into the folder and restart the Instance.

- Files are installed in name order (ex. `01-base.thd` before `02-site.thd`), each with a backup first. If an install fails, the backup is restored and the Instance starts with its previous configuration.
- Each file is installed only once, so passing the same file again on an upgrade doesn't overwrite changes made since. Installed files are moved to `deployments/installed` (or `deployments/failed`).
- **Deploy > Install > Installed at Startup** lists the results, and a notification shows each one.
- Set `TRAKHOUND_DEPLOYMENT_PATH` (or `--deploymentPath`) to read deployments from another folder, or from a single file such as a read-only Docker mount.

> Make startup deployments without Include Secrets, and put values that differ per site in Configuration Variables. Without Include Secrets, Deployments don't carry admin accounts.

### Workspaces

A Workspace holds the configurations, Variables, Zones, and Instance Settings for *another* Instance, so you can set it up without changing this one, ex. a device with no screen. Create one on **Deploy > Workspaces**, then open its Configuration, Zones, or Settings: they're the same admin pages, with a banner that shows which Workspace you're editing.

- Nothing in a Workspace runs on this Instance. Saving a configuration doesn't install its Package, and Workspaces aren't part of this Instance's Deployments or backups.
- **Export** creates a Deployment that replaces the target profile's APIs, Apps, Functions, Workers, Services, Identity providers, Routers, Groups, and Zones with the Workspace's, and carries its Variables and Instance Settings. Security profiles on the target are kept.
- The Package versions it uses are copied from this Instance, or downloaded from the Package source if they aren't installed here.
- For settings that differ on each device, set them to a Variable on the Settings page (ex. the port as `${port}`).

**Licenses and devices** - Licenses are issued for one device, so a Deployment only carries them when it's for one device:

- Add the License Files you received to the Workspace's **Licenses**, and enter the device's ID in **Target Device ID** when you export. The Deployment then includes that device's licenses and can only be installed on that device.
- List several devices on the Workspace's **Devices**, each with a label, its Device ID, and the Variable values that differ on it (ex. a PLC address). Export then creates **a Deployment for each device**, downloaded together in one `.zip`.
- On a device without the admin UI, `TrakHound.Instance device-id` shows its Device ID (see [Installation](https://www.trakhound.com/docs/trakhound-framework/installation#device-id)).
- Installing adds the licenses to the device's own, and a Deployment never sets a device's ID.
