From 51fa9ae3c2b6ecfdb924edfd3a508ed61751b443 Mon Sep 17 00:00:00 2001 From: mbecker20 Date: Mon, 6 Oct 2025 00:29:35 -0700 Subject: [PATCH] update setup script readme --- scripts/readme.md | 58 ++++++++++++++++++++++++++++---------- scripts/setup-periphery.py | 21 +++++++------- 2 files changed, 54 insertions(+), 25 deletions(-) diff --git a/scripts/readme.md b/scripts/readme.md index f68bbfb9d..003099bd6 100644 --- a/scripts/readme.md +++ b/scripts/readme.md @@ -1,5 +1,34 @@ # Periphery setup script +``` +usage: setup-periphery [-h] [--version VERSION] [--user] [--root-directory ROOT_DIRECTORY] [--core-address CORE_ADDRESS] + [--connect-as CONNECT_AS] [--onboarding-key ONBOARDING_KEY] [--force-service-file FORCE_SERVICE_FILE] + [--config-url CONFIG_URL] [--binary-url BINARY_URL] + +Install systemd-managed Komodo Periphery + +options: + -h, --help show this help message and exit + --version, -v VERSION + Install a specific Komodo version, like 'v2.0.0' (default: latest) + --user, -u Install systemd '--user' service (default: False) + --root-directory, -r ROOT_DIRECTORY + Specify a specific Periphery root directory. (default: /etc/komodo) + --core-address, -c CORE_ADDRESS + Specify the Komodo Core address for outbound connection. Leave blank to enable inbound connection server. (default: None) + --connect-as, -n CONNECT_AS + Specify the Server name to connect as. Defaults to hostname. (default: hostname) + --onboarding-key, -k ONBOARDING_KEY + Give an onboarding key for automatic Server onboarding into Komodo Core. (default: None) + --force-service-file FORCE_SERVICE_FILE + Recreate the systemd service file even if it already exists. (default: None) + --config-url CONFIG_URL + Use a custom config url. (default: + https://raw.githubusercontent.com/moghtech/komodo/refs/heads/main/config/periphery.config.toml) + --binary-url BINARY_URL + Use alternate binary source (default: https://github.com/moghtech/komodo/releases/download) +``` + These scripts will set up Komodo Periphery on your hosts, managed by systemd. *Note*. 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. @@ -13,7 +42,9 @@ There's two ways to install periphery: `System` and `User` Note. Run this after switching to root user (eg `sudo su -`). ```sh -curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3 +curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \ + | python3 - --core-address \ + --onboarding-key ``` Will install to paths: @@ -26,7 +57,9 @@ Will install to paths: *Note*. The user running periphery must be a member of the docker group, in order to use the docker cli without sudo. ```sh -curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3 - --user +curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \ + | python3 - --user --core-address \ + --onboarding-key ``` Will install to paths: @@ -34,19 +67,11 @@ Will install to paths: - periphery.service -> `$HOME/.config/systemd/user/periphery.service` - periphery.config.toml -> `$HOME/.config/komodo/periphery.config.toml` -*Note*. Ensure the user running periphery has write permissions to the configured folders `repo_dir`, `stack_dir`, and `ssl_key_file` / `ssl_cert_file` parent folder. -This allows periphery to clone repos, write compose files, and generate ssl certs. +*Note*. Ensure the user running periphery has write permissions to the configured `root_directory`. -*Note*. To ensure periphery stays running when your user logs out, use `sudo loginctl enable-linger $USER`. - -For example in `periphery.config.toml`, running under `ubuntu` user: -```toml -repo_dir = "/home/ubuntu/.komodo/repos" -stack_dir = "/home/ubuntu/.komodo/stacks" - -ssl_enabled = true -ssl_key_file = "/home/ubuntu/.komodo/ssl/key.pem" -ssl_cert_file = "/home/ubuntu/.komodo/ssl/cert.pem" +*Note*. To ensure periphery stays running when your user logs out, use this: +```shell +sudo loginctl enable-linger $USER ``` For additional information on configuring the systemd service, see the systemd service file documentation here: @@ -63,5 +88,8 @@ to the current default. Example: ```sh -curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | python3 - --force-service-file +curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \ + | python3 - --core-address \ + --onboarding-key \ + --force-service-file ``` \ No newline at end of file diff --git a/scripts/setup-periphery.py b/scripts/setup-periphery.py index 6c4356e15..fcc921459 100644 --- a/scripts/setup-periphery.py +++ b/scripts/setup-periphery.py @@ -8,7 +8,7 @@ import urllib.request def parse_args(): p = argparse.ArgumentParser( - prog="periphery-installer", + prog="setup-periphery", description="Install systemd-managed Komodo Periphery", formatter_class=argparse.ArgumentDefaultsHelpFormatter, ) @@ -16,51 +16,52 @@ def parse_args(): p.add_argument( "--version", "-v", default=json.load(urllib.request.urlopen("https://api.github.com/repos/moghtech/komodo/releases/latest"))["tag_name"], - help="Install a specific Komodo version, like 'v2.0.0'. Otherwise use latest." + help="Install a specific Komodo version, like 'v2.0.0'" ) p.add_argument( "--user", "-u", action="store_true", - help="Install systemd --user service" + help="Install systemd '--user' service" ) p.add_argument( "--root-directory", "-r", - help="Specify a specific Periphery root directory" + default="/etc/komodo", + help="Specify a specific Periphery root directory." ) p.add_argument( "--core-address", "-c", - help="Specify the Komodo Core address, https://komodo.example.com." + help="Specify the Komodo Core address for outbound connection. Leave blank to enable inbound connection server." ) p.add_argument( "--connect-as", "-n", default=os.uname().nodename, - help="Specify the Server name to connect as. Otherwise uses $(hostname)." + help="Specify the Server name to connect as. Defaults to hostname." ) p.add_argument( "--onboarding-key", "-k", - help="Give an onboarding key for automatic Server onboarding into Komodo Core" + help="Give an onboarding key for automatic Server onboarding into Komodo Core." ) p.add_argument( "--force-service-file", - help="Recreate the systemd service file even if it already exists" + help="Recreate the systemd service file even if it already exists." ) p.add_argument( "--config-url", default="https://raw.githubusercontent.com/moghtech/komodo/refs/heads/main/config/periphery.config.toml", - help="Use a custom config url" + help="Use a custom config url." ) p.add_argument( "--binary-url", default="https://github.com/moghtech/komodo/releases/download", - help="Use alternate binary source, like https://forge.mogh.tech/api/packages/komodo/generic/periphery" + help="Use alternate binary source" ) return p.parse_args()