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:
bashcurl -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
- Sign in to your Buddy self-hosted instance as admin.
- Go to the Self-Hosted Admin panel and switch to the Runners tab.
- Click Add new runner and copy the installation command.
- 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:
bashbuddy 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.
- Runner data path – allows to move the application data on the runner to a different partition or disk
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)
- Primary instance address – displays the IP address of the primary instance of Buddy.
- Runner token – displays the token used to authenticate in the primary instance of Buddy.
- Application memory management – changes the amount of RAM allocated to the Buddy application on the runner.
Last modified on Sep 24, 2024