forked from github-starred/komodo
132 lines
5.2 KiB
Plaintext
132 lines
5.2 KiB
Plaintext
# Connect More Servers
|
|
|
|
```mdx-code-block
|
|
import RemoteCodeFile from "@site/src/components/RemoteCodeFile";
|
|
```
|
|
|
|
Connecting a server to Komodo has 3 steps:
|
|
|
|
1. Add the Server to Komodo via the Core API / UI.
|
|
2. Install and configure the Periphery agent on the server.
|
|
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 do whatever you want with the binary.
|
|
|
|
### Install the Periphery agent - systemd
|
|
|
|
As root user:
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](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 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
|
|
|
|
```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 the 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. |