Deploying Runners
Deploying a Runner with Docker
Prerequisites
- A Container Engine: You will need Docker installed on your machine. Install Docker here.
-
Docker Authentication Required: To prevent TLS handshake timeouts or image pull failures, ensure you are authenticated with Docker Hub before attempting to deploy a self-hosted runner. Docker may restrict access to images due to excessive unauthenticated pull requests. You can authenticate using docker login.
Please note, for enterprise users, be aware that Docker Desktop has commercial use limitations. Review Docker’s licensing terms to ensure compliance in larger organizations.
-
Blink User: You must have either the Owner role,Contributor role, or a custom role that includes both the
runners:viewandrunners:editpermissions. To learn more about role-based access and permissions, see the User Roles documentation.
Requirements
When deploying self-hosted runners on a hardened OS, it’s crucial to ensure proper communication between Docker containers, therefor please implement the following requirements:| Requirement | Explanation |
|---|---|
| Manage internal firewall settings | An internal firewall might prevent communication between containers. To resolve this, create a firewall rule that allows containers to communicate with each other internally. The port used for internal container communication is selected randomly, so the firewall rule must accommodate this configuration/requirements |
| Ensure sufficient disk space | Ensure that your system has at least 30GB of available disk space on the /var partition to avoid deployment issues. |
| Verify DNS server configuration | Ensure that all DNS servers configured on your system are correctly resolving addresses, as DNS issues could impact network operations during deployment. |
| Authenticate with Docker | Before deploying a Docker runner, run docker login to authenticate with Docker Hub. Unauthenticated image pulls may be rate-limited, resulting in TLS handshake timeouts or failed downloads. |
Deployment Guide
1
Navigate to the Runners page
In the left-hand navigation bar, select Runners. Then, click the New Runner button in the top-right corner to open the configuration dialog.
2
Fill in the parameters:
Fill in the required details:
- Name: Enter a name for the Runner group.
- Tags: Add or create tags (optional).
- Default: Check this box to set this Runner group as the default. When enabled, any workflows that do not explicitly specify a Runner group will automatically be assigned to this one.
3
Choose Runner Type
Choose Docker as your runner type.
4
Copy and save the command
Click ‘Continue’. to proceed. A dialog box will appear with the command needed to install the Runner in your Docker environment. To copy the command, click the button in the top-right corner.
WARNINGPlease be aware that the provided command contains the registration token of the Runner, which will not be retrievable after copying. It is essential to securely store this token in a safe location for future reference.