> ## Documentation Index
> Fetch the complete documentation index at: https://docs.regatta.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Overview

> The RDT configuration schema: the Cluster, Node, Device, and Module object types.

RDT describes a RegattaDB deployment with a single JSON configuration file, stored under
`~/.rdt/configs/<name>.json`. This page documents the schema. For the commands used to
create, edit, and manage these files, see
[Creating & Managing Configs](./creating-and-managing-configs.mdx).

## Deployment guidelines

Before designing a configuration, keep RegattaDB's general module placement guidelines
in mind:

* **SM**: exactly one per deployment.
* **SNA**: one per node that hosts at least one operational module (GDD, DCM, Sequencer, or RDB).
* **GDD**, **DCM**, **Sequencer**: exactly one per deployment.
* **RDB**: at least one per deployment; a node may host multiple RDB modules.

With that in mind, here's the JSON schema itself: the fields that make up the `Cluster`,
`Node`, `Device`, and `Module` objects in a config file.

## Cluster

| Field     | Type              | Description                                              |
| --------- | ----------------- | -------------------------------------------------------- |
| `version` | `string`          | Configuration schema version                             |
| `id`      | `string/UUID/int` | Cluster identifier. Defaults to `"regatta-cluster"`      |
| `nodes`   | list of Node      | The nodes that make up the deployment. Defaults to empty |

**Cluster-level validation:**

* Node `id` must be unique across the deployment.
* Exactly one instance each of SM, Sequencer, GDD, and DCM across the entire
  deployment (not per node).

## Node

| Field         | Type             | Description                                                                                  |
| ------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `id`          | `int`            | Unique identifier within the deployment. Defaults to `1`                                     |
| `name`        | `string`         | Node name. Defaults to `"regatta-node"`                                                      |
| `ip`          | IP address       | Address RDT uses to connect to the node                                                      |
| `num_threads` | `int `(optional) | Concurrency level for the node.<br />Leave unset to let the SM automatically set the value   |
| `ram_MB`      | `int `(optional) | RAM budget for the node, in megabytes. Leave unset to let the SM automatically set the value |
| `devices`     | list of Device   | Storage devices available on this node. Defaults to empty                                    |
| `modules`     | list of Module   | Modules to run on this node. Defaults to empty                                               |
| `config`      | `object`         | Arbitrary node config (e.g. probed hardware data). Defaults to empty                         |

**Node-level validation:**

* At most one instance each of SM, SNA, Sequencer, GDD, and DCM is allowed per node (mirrors
  the cluster-level rule).
* Module `id`s must be unique within the node.
* Every device name referenced by a module must exist in the node's `devices` list.
* Two modules on the same node cannot reference the same device.

## Device

| Field         | Type                | Description                                |
| ------------- | ------------------- | ------------------------------------------ |
| `name`        | `string`            | Referenced by modules by this name         |
| `path`        | path                | Path to the raw block device               |
| `capacity`    | `int `(optional)    | Capacity in bytes                          |
| `config`      | `object`            | Arbitrary device config. Defaults to empty |
| `description` | `string `(optional) | Free-form description                      |

## Module

All modules share a common set of fields; each module type additionally has fixed
defaults for `id`, `port`, and `service_port`.

| Field          | Type             | Description                                                                                          |
| -------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `type`         | `string`         | One of `sm`, `sna`, `sequencer`, `gdd`, `dcm`, `rdb`                                                 |
| `id`           | `int`            | Defaults to the type's standard id (see table below)                                                 |
| `name`         | `string`         | Auto-generated as `<type>_<id>` if not set                                                           |
| `port`         | `int`            | Communications port. Defaults to the type's standard port                                            |
| `service_port` | `int`            | Service port. Defaults to the type's standard service port                                           |
| `num_threads`  | `int `(optional) | Concurrency level for the module.<br />Leave unset to let the SM automatically set the value         |
| `ram_MB`       | `int `(optional) | RAM budget for the module, in megabytes. <br />Leave unset to let the SM automatically set the value |
| `devices`      | list of strings  | Names of devices (from the node) used by this module                                                 |
| `config`       | `object`         | Arbitrary module config, e.g. core binding (see below)                                               |

### Module type defaults

| Type      | Default id | Port | Service port |
| --------- | ---------- | ---- | ------------ |
| SM        | 1          | 8840 | 5000         |
| SNA       | 2          | 8841 | 5001         |
| Sequencer | 3          | 8842 | 5002         |
| GDD       | 4          | 8843 | 5003         |
| DCM       | 5          | 8844 | 5004         |
| RDB       | 10         | 8850 | 6001         |

### Core binding

A module can be pinned to specific CPU cores via its `config`:

```json theme={null}
"config": {
  "core_binded_node": "0",
  "core_binded_cores": "0-5"
}
```

* `core_binded_node` is required whenever `core_binded_cores` is set.
* If `num_threads` is left unset, it's derived automatically from the core range.
* If `num_threads` is set, it must not exceed the number of cores in the range.

## Example

A minimal single-node config with one RDB storage device:

```json theme={null}
{
  "version": "26.0",
  "id": "my-regattadb",
  "nodes": [
    {
      "id": 1,
      "name": "node_1",
      "ip": "10.0.0.1",
      "devices": [
        { "name": "disk1", "path": "/dev/nvme0n1" }
      ],
      "modules": [
        { "type": "sm", "id": 1, "port": 8840, "service_port": 5000, "config": {}, "devices": [] },
        { "type": "sna", "id": 2, "port": 8841, "service_port": 5001, "config": {}, "devices": [] },
        { "type": "sequencer", "id": 3, "port": 8842, "service_port": 5002, "config": {}, "devices": [] },
        { "type": "gdd", "id": 4, "port": 8843, "service_port": 5003, "config": {}, "devices": [] },
        { "type": "dcm", "id": 5, "port": 8844, "service_port": 5004, "config": {}, "devices": [] },
        { "type": "rdb", "id": 10, "port": 8850, "service_port": 6001, "config": {}, "devices": ["disk1"] }
      ]
    }
  ]
}
```

See [Creating & Managing Configs](./creating-and-managing-configs.mdx) to learn how to generate,
edit, and validate files like this without hand-writing the JSON, and
[Config Recipes](../examples/config-recipes.mdx) for multi-node and probed-hardware examples.

## Templates

`rdt config create --from <template>` starts a config from a packaged template instead
of a blank one. Two templates ship with RDT today:

* **`xsmall`**: a single-node, all-in-one layout: one node running all module types
  (SM, SNA, Sequencer, GDD, DCM, RDB).
* **`small`**: a 3-node "classic" multi-node layout: `node_1` runs every module type
  (like `xsmall`), while `node_2` and `node_3` each run only SNA and RDB.

No devices or CPU/RAM values are specified in either template. Adjust these, the node
IPs, and the node count for your environment.

## Next steps

See [Creating & Managing Configs](./creating-and-managing-configs.mdx) for the commands
that create, edit, validate, and share these configuration files.