BasicsPipelinesTargetsActions & ServicesIntegrationsSelf-HostedYAMLBuddy GitTroubleshootingAPI

Installation & configuration

  • Runners are used to speed up builds and tests by evenly distributing pipeline load
  • The server where Buddy self-hosted is first installed is the default runner (Primary).
  • You can install more runners on other nodes for extra performance.
Hint
All commands listed in the article must be run as root.
Tip
To run commands in non-interactive mode add --yes to the buddy command, e.g. buddy --yes update-runner-config

Requirements

ResourceRequirement
CPU2.6 GHz
Memory4 GB
Root disk30 GB
Hint
Runners require a Linux-type server (we recommend Ubuntu 20.04) with Docker and docker-compose installed to run.
Tip
The runners and the main Buddy instance must be able to connect to each other. You can configure the IP address and ports of the runner during the installation.
Warning
You cannot install a new runner on the server that runs the main Buddy self-hosted instance – this instance is a fully operational runner. Install new runners on different, compatible servers.

Installing runners

Launch the terminal on the server where you want to install the runner and run the commands below:

bash
curl -sSL https://get.buddy.works | sh 
buddy install-runner --token="$TOKEN" --standalone-host="$ADDRESS"$$
Tip
You can generate the command with the token and address from the application GUI or the CLI.

Supported flags

NameDescription
--drainSets the runner to draining mode.
--configFetches the data from a configuration file. Must have the path to the file set.
--standalone-hostREQUIRED. The new IP address of the main instance.
--tokenREQUIRED. Overwrites the default authorization token. If not provided, Buddy will use the most recently provided token.
--runner-memoryThe amount of RAM in MB allocated for the runner service.
--nameThe name of the runner. Ignored if empty.
--tagThe new tag applied to the runner. Ignored if empty.
--memoryThe new amount of RAM in MB that can be used by the build actions on the runner. Must be greater than 0 or will be ignored.
--shmThe new amount of shared memory in MB. Must be greater than 0 or will be ignored.
--concurrentThe new number of pipeline runners on the runner. Must be greater than 0 or will be ignored.)
--internal-hostThe IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server). Requires restart.
--external-hostThe external IP address of the server as seen by the primary server. Default value: the first detected external IP address. Requires restart.
--runner-internal-portThe listening port of the runner. Default: 1090. Can be changed if the port is taken.
--runner-external-portThe external port of the runner to which Buddy self-hosted is connecting. Default: 1090. Can be changed if the ports are mapped.
--registry-internal-portRegistry listening port. Default: 1091. Can be changed if the port is taken.
--registry-external-portRegistry external port to which Buddy self-hosted is connecting Default: 1091. Can be changed if the ports are mapped.
Hint
Flags have higher priority than the data in the configuration file. For example, setting the memory limit with a parameter flag will overwrite the value from the config file.

Generating installation command

GUI

  1. Sign in to your Buddy self-hosted instance as admin.
  2. Go to the Self-Hosted Admin panel and switch to the Runners tab.
  3. Click Add new runner and copy the installation command.
  4. Proceed to the installation step to continue.

CLI

On the server with the main instance, run the following to generate the installation command and token and save it to an executable file:

bash
buddy install-runner$

Supported flags

NameDescription
--drainSets the runner to draining mode.
--standalone-hostThe IP address of the main instance. Must be provided during the installation or in the config file.
--runner-memoryThe amount of RAM in MB allocated for the runner service.
--nameThe name of the runner.
--tagThe tag applied to the runner. Default value: empty (untagged).
--cpusThe number of CPUs that cane be used by the build actions on the runner. Default value: 0 (unlimited).
--memoryThe amount of RAM in MB that can be used by the build actions on the runner. Default value: 0 (unlimited).
--shmThe amount of shared memory in MB. Default value: 0 (unlimited).
--concurrentThe number of concurrent pipelines running on the runner. Default value: 0 (unlimited).
--internal-hostThe IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server).
--external-hostThe external IP address of the server as seen by the primary server. Default value: the first detected external IP address.
--runner-internal-portThe listening port of the runner. Default: 1090. Can be changed if the port is taken.
--runner-external-portThe external port of the runner to which Buddy self-hosted is connecting. Default: 1090. Can be changed if the ports are mapped.
--registry-internal-portThe listening port of the registry. Default: 1091. Can be changed if the port is taken.
--registry-external-portThe external port of the registry to which Buddy self-hosted is connecting. Default: 1091. Can be changed if the ports are mapped.

Runner authorization token

The authorization token is used to authenticate the runner in the main instance of Buddy self-hosted. To display the token run buddy configure and select 15. (Runner token) on the server with the main instance of Buddy Self-Hosted.

Hint
The token is long-lived and the same for all runners in your Buddy self-hosted instance. To regenerate the token, run the command above and select Regenerate.
Warning
Once regenerated, the token must be updated on all runners in the instance, or they will stop to communicate: bash buddy update-runner-config --token TOKEN_VALUE

CLI configuration options

Running buddy configure on the runner, shows the options listed below. To configure an option, type the corresponding number and press Enter.

  1. Runner data path – allows to move the application data on the runner to a different partition or disk

  2. IP & ports – allows to set IP & port addresses:

    • internal IP – the internal IP address to which the runner is bound
    • external host – the external IP address to which the primary instance is connecting to
    • registry listening port (default 1090)
    • runner listening port (default 1091)
    • registry external port (default 1091)
  3. Primary instance address – displays the IP address of the primary instance of Buddy.
  4. Runner token – displays the token used to authenticate in the primary instance of Buddy.
  5. Application memory management – changes the amount of RAM allocated to the Buddy application on the runner.

Last modified on Sep 24, 2024

Previous pageTunnelNext pageConfiguration file