# Connect More Servers

```mdx-code-block
import RemoteCodeFile from "@site/src/components/RemoteCodeFile";
```

Connecting a server to Komodo has 3 steps:

1.  **Create an Onboarding Key** via the Komodo Core API / UI (they can also be reused).
2.  **Install the Periphery agent** on the server or VM.
3.  Confirm the connection status is OK.

## Install Periphery

You can install Periphery as a systemd managed process, run it as a [docker container](https://github.com/moghtech/komodo/pkgs/container/komodo-periphery), or run the binary directly with another process manager.

### Install the Periphery agent - systemd

**As root user:**
```bash
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."
```

Periphery can also be installed to run as a **systemd user service** (for the calling user).

```bash
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - --user \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."
```

You can find more information (and view the script) in the [readme](https://github.com/moghtech/komodo/tree/main/scripts).

:::info
This script can be run multiple times without issue, and it won't change existing config after the first run. Just run it again after a Komodo version release, and it will update the periphery version.
:::

:::tip
For deployment to many servers, a tool like [Ansible](https://docs.ansible.com/) should be used.
An example of such a setup can be found here: https://github.com/bpbradley/ansible-role-komodo
:::

### Install the Periphery agent - container

You can use a docker compose file:

```mdx-code-block
<RemoteCodeFile
	title="https://github.com/moghtech/komodo/blob/main/compose/periphery.compose.yaml"
	url="https://raw.githubusercontent.com/moghtech/komodo/main/compose/periphery.compose.yaml"
	language="yaml"
/>
```

### Manual install steps - binaries

1.  Download the periphery binary from the latest [release](https://github.com/moghtech/komodo/releases).

2.  Create and edit your config files, following the [config example](https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml).

:::note
See the [periphery config docs](https://docs.rs/komodo_client/latest/komodo_client/entities/config/periphery/index.html)
for more information on configuring periphery.
:::

3.  Ensure that connectivity with Komodo Core is possible via the chosen connection method. **So either**:

		- Periphery can reach Komodo Core at the configured `core_address`.
		- Komodo Core can reach Periphery on the specified port (default `8120`).

4.  Install docker. See the [docker install docs](https://docs.docker.com/engine/install/).

:::note
Ensure that the user which periphery is run as has access to the docker group without sudo.
:::

5.  Start the periphery binary with your preferred process manager, like systemd.

### Example periphery start command

```sh
periphery --config-path /path/to/periphery.config.toml
```

:::info
You can run `periphery --help` to see the manual.
:::

When running periphery in docker, use [command](https://docs.docker.com/reference/compose-file/services/#command) to pass in additional arguments.
```
command: periphery --config-path /path/in/container/to/periphery.config.base.toml
```



## Configuration

The configuration can also be passed as **YAML** or **JSON**.
You can use it-tools to convert this TOML file to your preferred format:
  - YAML: https://it-tools.tech/toml-to-yaml
  - JSON: https://it-tools.tech/toml-to-json

Quick download to `./komodo/periphery.config.toml`:
```bash
wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml
```

```mdx-code-block
<RemoteCodeFile
	title="https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml"
	url="https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml"
	language="toml"
/>
```

### Passing config files

Either file paths or directory paths can be passed to `--config-path` (alias: `-c`). By default, no paths will be used, meaning the configuration is entirely
loaded via environment variables.

When using directories, the file entries can be filtered by name with the `--config-keyword` argument, which can be passed multiple times to add more keywords.
These are each wildcard patterns to match file names.
Only config files with file names that contain a keyword will be merged, with files matching later defined keywords having higher priority on field conflicts.
By default, the only keyword is `*config*.*`. This matches files like `config.toml`, `periphery.config.yaml`, etc.

When passing multiple config files, later --config-path given in the command will always override previous ones.
Directory config files are merged in alphabetical order by name, so `config_b.toml` will override `config_a.toml`.

There are two ways to merge config files.
The default behavior is to completely replace any base fields with whatever fields are present in the override config.
So if you pass `allowed_ips = []` in your override config, the final allowed_ips will be an empty list as well.

`--merge-nested-config true` will merge config fields recursively and extend config array fields.

For example, with `--merge-nested-config true` you can specify an allowed ip in the base config, and another in the override config, they will both be present in the final config.

Similarly, you can specify a base docker / github account pair, and extend them with additional accounts in the override config.