# Connect More Servers

Connecting a server to Komodo has 2 steps:

1.  Install the Periphery agent on the server (either binary or container).
2.  Add the server to Komodo via the Core API / UI.

## Install Periphery

You can install Periphery as a systemd managed process, run it as a [docker container](https://github.com/mbecker20/komodo/pkgs/container/periphery), or do whatever you want with the binary.

:::warning
Allowing unintended access to the Periphery agent API is a security risk.
Ensure to take appropriate measures to block access to the Periphery API, such as firewall rules on port `8120`.
Additionally, you can whitelist your Komodo Core IP address in the [Periphery config](https://github.com/mbecker20/komodo/blob/main/config/periphery.config.toml#L46),
and configure it to [only accept requests matching including your Core passkey](https://github.com/mbecker20/komodo/blob/main/config/periphery.config.toml#L51).
:::

### Install the Periphery agent - systemd

As root user:
```bash
curl -sSL https://raw.githubusercontent.com/mbecker20/komodo/main/scripts/setup-periphery.py | python3
```

Periphery can also be installed to run as the calling user, just note this comes with some additional configuration.

```bash
curl -sSL https://raw.githubusercontent.com/mbecker20/komodo/main/scripts/setup-periphery.py | python3 - --user
```

You can find more information (and view the script) in the [readme](https://github.com/mbecker20/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.
:::

### Install the Periphery agent - container

You can use a docker compose file like this:
```yaml
services:
  periphery:
    image: ghcr.io/mbecker20/periphery:latest
    # image: ghcr.io/mbecker20/periphery:latest-aarch64 # use for arm support
    labels:
      komodo.skip: # Prevent Komodo from stopping with StopAllContainers
    logging:
      driver: local
    ports:
      - 8120:8120
    volumes:
      ## Mount external docker socket
      - /var/run/docker.sock:/var/run/docker.sock
      ## Allow Periphery to see processes outside of container
      - /proc:/proc
      ## use self signed certs in docker volume, 
      ## or mount your own signed certs.
      - ssl-certs:/etc/komodo/ssl
      ## manage repos in a docker volume, 
      ## or change it to an accessible host directory.
      - repos:/etc/komodo/repos
      ## manage stack files in a docker volume, 
      ## or change it to an accessible host directory.
      - stacks:/etc/komodo/stacks
      ## Optionally mount a path to store compose files
      # - /path/to/compose:/host/compose
    environment:
      ## Full list: `https://github.com/mbecker20/komodo/blob/main/config/periphery.config.toml`
      ## Configure the same passkey given to Komodo Core (KOMODO_PASSKEY)
      PERIPHERY_PASSKEYS: your_core_passkey # Alt: PERIPHERY_PASSKEYS_FILE
      ## Adding IP here will ensure calling IP is in the list. (optional)
      PERIPHERY_ALLOWED_IPS:
      ## Enable HTTPS server
      PERIPHERY_SSL_ENABLED: true
      ## If the disk size is overreporting, can use one of these to 
      ## whitelist / blacklist the disks to filter them, whichever is easier.
      ## Accepts comma separated list of paths.
      ## Usually whitelisting /etc/hostname gives correct size.
      PERIPHERY_INCLUDE_DISK_MOUNTS: /etc/hostname
      # PERIPHERY_EXCLUDE_DISK_MOUNTS: /snap,/etc/repos

volumes:
  ssl-certs:
  repos:
  stacks:
```

### Manual install steps - binaries

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

2.  Create and edit your config files, following the [config example](https://github.com/mbecker20/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 inbound connectivity is allowed on the port specified in periphery.config.toml (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

```
periphery \
	--config-path /path/to/periphery.config.base.toml \
	--config-path /other_path/to/overide-periphery-config-directory \
	--config-keyword periphery \
	--config-keyword config \
	--merge-nested-config true
```

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

### Passing config files

Either file paths or directory paths can be passed to `--config-path`.

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. If passed, then only config files with file names that contain all keywords will be merged.

When passing multiple config files, later --config-path given in the command will always overide previous ones. Directory config files are merged in alphabetical order by name, so `config_b.toml` will overide `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 overide config. So if you pass `allowed_ips = []` in your overide 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 overide 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 overide config.

## Configuration

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

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

<RemoteCodeFile
	title="https://github.com/mbecker20/komodo/blob/main/config/periphery.config.toml"
	url="https://raw.githubusercontent.com/mbecker20/komodo/main/config/periphery.config.toml"
	language="toml"
/>
```
