Install Self-Hosted
Get Started on Cloud
BasicsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsSelf-HostedYAMLBuddy GitTroubleshooting

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

Resource Requirement
CPU 2.6 GHz
Memory 4 GB
Root disk 30 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

Name Description
--drain Sets the runner to draining mode.
--config Fetches the data from a configuration file. Must have the path to the file set.
--standalone-host REQUIRED. The new IP address of the main instance.
--token REQUIRED. Overwrites the default authorization token. If not provided, Buddy will use the most recently provided token.
--runner-memory The amount of RAM in MB allocated for the runner service.
--name The name of the runner. Ignored if empty.
--tag The new tag applied to the runner. Ignored if empty.
--memory The 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.
--shm The new amount of shared memory in MB. Must be greater than 0 or will be ignored.
--concurrent The new number of pipeline runners on the runner. Must be greater than 0 or will be ignored.)
--internal-host The IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server). Requires restart.
--external-host The external IP address of the server as seen by the primary server. Default value: the first detected external IP address. Requires restart.
--runner-internal-port The listening port of the runner. Default: 1090. Can be changed if the port is taken.
--runner-external-port The external port of the runner to which Buddy self-hosted is connecting. Default: 1090. Can be changed if the ports are mapped.
--registry-internal-port Registry listening port. Default: 1091. Can be changed if the port is taken.
--registry-external-port Registry 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

Name Description
--drain Sets the runner to draining mode.
--standalone-host The IP address of the main instance. Must be provided during the installation or in the config file.
--runner-memory The amount of RAM in MB allocated for the runner service.
--name The name of the runner.
--tag The tag applied to the runner. Default value: empty (untagged).
--cpus The number of CPUs that cane be used by the build actions on the runner. Default value: 0 (unlimited).
--memory The amount of RAM in MB that can be used by the build actions on the runner. Default value: 0 (unlimited).
--shm The amount of shared memory in MB. Default value: 0 (unlimited).
--concurrent The number of concurrent pipelines running on the runner. Default value: 0 (unlimited).
--internal-host The IP address that will be bound by the runner. Default value: empty (binds to all IP's on the server).
--external-host The external IP address of the server as seen by the primary server. Default value: the first detected external IP address.
--runner-internal-port The listening port of the runner. Default: 1090. Can be changed if the port is taken.
--runner-external-port The external port of the runner to which Buddy self-hosted is connecting. Default: 1090. Can be changed if the ports are mapped.
--registry-internal-port The listening port of the registry. Default: 1091. Can be changed if the port is taken.
--registry-external-port The 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