# Files and settings

Every file a bench reads or writes, in one place — for looking one up. The
console writes all of them for you; this page is for when you want to read or
edit one yourself.

## The home directory

Everything the bench writes lives under one folder, the **home** —
`~/.plesty/server` unless `--home DIR`, `home:` in the fleet file or
`PLESTY_SERVER_HOME` says otherwise (in that order).

```text
~/.plesty/server/
├── fleet.yaml       a bench's fleet from before fleets/ (./fleet.yaml is looked at first)
├── last-fleet       which fleet file the console opened last
├── fleets/          this bench's fleets, <name>.yaml each; a new bench starts with an
│                    empty default.yaml
├── agent.yaml       the agent's address, token, worker count, role and data path
├── peers.yaml       on a master: the other benches it drives, with their tokens
├── packages/        installed modules, one environment per version
├── repos/           repository checkouts, one per (package, ref)
├── run/<name>/      each device's working folder — and its .env
├── runs/<name>/     experiment runs, when the module names no shared data folder
├── data/            where the devices write while no Plesty share is set: each its
│                    data_dir, or tmp/<name>
├── demo/            the welcome's demo: its runs, which its spectrometer replays
├── last-operator.txt who created the last run; welcome-seen, update-check.json
├── state/           what each server was started with, and whether it ended
├── logs/            <name>-<date>-<time>.log per device start or clear (<name>.current
│                    names the one in use), jobs/<id>.log per job
├── jobs/            the record of every install, update, field test and run
└── tools/           what the bench installed for itself (git, on Windows)
```

One machine can hold several benches by giving each its own home. They take
ports from the same range, so they move around each other rather than
collide. Backing up a bench is copying this folder; see
[Keep what you need first](../usage/uninstall.md#keep-what-you-need-first).

## The fleet file

`fleet.yaml` says what this bench runs: its devices and its experiments.
*Device ▸ Add device…* and `plesty-server declare` write it; *Edit ▸ Fleet
file…* shows it whole.

```yaml
version: 1

devices:
  pm100d:
    package: plesty-pm100d
    version: 0.2.1
    args: [--tcp-port, "5551", --address, "USB0::0x1313::0x8078::P0031744::INSTR"]
    env:
      PLESTY_REPORT_ARCHIVE: /shares/plesty/reports
    autostart: true

  k10cr1-dev:
    package: plesty-k10cr1
    git: https://gitlab.com/plesty/hub/devices/thorlab/plesty-k10cr1.git
    ref: exp
    args: [--address, "55123457"]
    autostart: false

experiments:
  pol-pl:
    package: plesty-pol-pl
    git: https://gitlab.com/plesty/hub/experiments/plesty-pol-pl.git
    ref: exp
    config: config/default.yaml
```

### A device

| Key | Means |
|---|---|
| the entry's name | The device's name on this bench. It names its log, its folder and its process record, so it must be unique. |
| `package` | The hub device module that runs it. |
| `version` | A release from PyPI. Leave it out to take the newest at install time. |
| `git` + `ref` | Install from a repository instead — a branch, tag or commit. `ref` defaults to `v<version>` when a version is given. Field tests need this. |
| `args` | Passed to the device server — the module's own options, such as `--address`. |
| `env` | Environment for the server and its field tests. It wins over the device's `.env`. |
| `port` | The port to serve on. Usually left out: see [Ports](#ports). |
| `autostart` | Whether the device is in the **working fleet** — the check box in the console. |
| `data_dir` | Where the device writes, relative to the bench's data path (*Server ▸ Configure…*): `pol-pl/cam`. Left out, it writes to `tmp/<name>`. Never absolute, never `..`. |

Two entries may run the same package at different versions, or the same
version twice on two ports.

### An experiment

| Key | Means |
|---|---|
| `package` | The hub experiment module. |
| `git` + `ref` | Where it is installed from. An experiment is normally installed from its repository: its `config/` files and `.env.example` are there and not in the release. |
| `version` | A release, for a module whose release carries what it needs. |
| `path` | A repository on this machine to run instead of an install — what *Hub ▸ Load from…* declares. |
| `config` | The configuration file a new run starts from. |
| `args` | Appended to the module's command. |
| `env` | Environment for its runs. A `<DEVICE>_ADDRESS` set here points the run at that address, and the bench does not start that device itself. |

An experiment has no port and no `autostart`: `fleet up` does not start it.

## Ports

Each device server listens on its own TCP port — what an experiment connects
to. Unless the declaration names one, the bench picks the lowest free port
from **5551** upwards (5550 is the agent's) and writes it into the fleet file,
so a device keeps the same port from then on.

- A port the bench picked, or one written as `port:`, is moved to a free one
  if something else holds it at start time — the bench says so.
- A port you named in `args` (`--tcp-port 5551`) or `env` is **not** moved:
  the server was told that number. `start` reports it busy and stops.

The rules in full are in [Ports](../design/ports.md).

## A device's `.env`

Each device has its own `<home>/run/<name>/.env`, read by its server and its
field tests — the place for an address, a serial number or a calibration
constant. It stays on the bench, unlike a fleet file that may be copied
elsewhere. Edit it in *Device config ▸ .env*.

```bash
DEVICE_ADDRESS=USB0::0x1313::0x8078::P0031744::INSTR
PLESTY_REPORT_ARCHIVE=/shares/plesty/reports
```

The fleet's `env:` wins over it, and it wins over the environment the bench
itself was started with. On the first install it is filled from the module's
`.env.example`; a later install adds keys the new example has and never
overwrites a value you set.

## The other files

| File | Where | Holds | Written by |
|---|---|---|---|
| `agent.yaml` | the home | `bind`, `token`, `workers`, `role`, `data_share`, `data_folder` | *Server ▸ Configure…*, `plesty-server data-path` |
| `peers.yaml` | the home | the benches a master drives: address and token each | *Server ▸ Benches…* |
| `setup.yaml` | an experiment module's folder | the benches and devices the experiment runs across, as variables | *Configure… ▸ Device Setup* — see [Run an experiment](../usage/experiment.md#the-benches-and-the-shared-disk) |
| experiment `.env` | beside `setup.yaml` | the values of those variables: addresses, tokens, shared-data folders | installing the module; *Device Setup* |
| run `config.yaml` | each run's folder | the configuration that run starts and resumes with | *Create run*, *Configure…* |

`agent.yaml`, `peers.yaml` and the experiment `.env` hold tokens and are
readable by their owner only. None of them belongs in a repository;
`fleet.yaml` and `setup.yaml` do.

## Environment variables

The variables the bench reads are in [the CLI overview](index.md#environment-variables).
The ones it **sets** for what it starts:

| Variable | Set for | Value |
|---|---|---|
| `DEVICE_DATA_ROOT` | every device the bench starts, once its share is set | `<share>/<bench folder>`: where the device may write |
| `DEVICE_DATA_PATH` | every device the bench starts, once its share is set | `<bench folder>/<data_dir>`, else `<bench folder>/tmp/<name>`; a device `.env` or the fleet's `env:` still wins |
| `PLESTY_DATA` | every device and experiment run the bench starts, once its share is set | the Plesty share as this machine mounts it; a run's `.env` still wins |
| `<DEVICE>_ADDRESS` | an experiment's run | `tcp://<host>:<port>` of each of its devices, e.g. `HWP_ADDRESS` |