Skip to main content

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, 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, and configure it to only accept requests including your Core passkey.

Install the Periphery agent - systemd​

As root user:

curl -sSL https://raw.githubusercontent.com/moghtech/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.

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

You can find more information (and view the script) in the readme.

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 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:

https://github.com/moghtech/komodo/blob/main/compose/periphery.compose.yaml

Manual install steps - binaries​

  1. Download the periphery binary from the latest release.

  2. Create and edit your config files, following the config example.

note

See the periphery config docs for more information on configuring periphery.

  1. Ensure that inbound connectivity is allowed on the port specified in periphery.config.toml (default 8120).

  2. Install docker. See the docker install docs.

note

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

  1. 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/override-periphery-config-directory \
	--config-keyword periphery \
	--config-keyword config \
	--merge-nested-config true
info

You can run periphery --help to see the manual.

When running periphery in docker, use command to pass in additional arguments.

command: periphery --config-path /path/in/container/to/periphery.config.base.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.

Configuration​

The configuration can also be passed as YAML or JSON. You can use the it-tools to convert this TOML file to your preferred format:

Quick download to ./komodo/periphery.config.toml:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml
https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml