Define a Docker Build Infrastructure
You can define a CI build infrastructure on any Linux or macOS host. This is the simplest build infrastructure to set up, and is well-suited for developers who want to run builds on a local host such as a laptop.
Important Notes
- To set up a local build environment, you must run a Docker Compose file that installs a Harness Delegate and the Local runner.
- The Docker Delegate has the following system requirements:
- Default 0.5 CPU.
- Default 1.5GB. Ensure that you provide the minimum memory for the Delegate and enough memory for the host/node system.
- The Docker Delegate is limited by the total amount of memory and CPU on the local host. Builds can fail if the host runs out of CPU or memory when running multiple builds.
Install the Delegate
- In the Harness UI, go to the screen that corresponds to the scope of your delegate: Account Settings > Account Resources > Delegates , or Project Setup > Delegates.
- Select New Delegate or Create a Delegate, select Docker for the delegate type, and then select Continue.
- Enter a delegate name and click Continue.
- Download the docker-compose.yml file that appears.
- Click Continue.
The UI shows the delegate as not connected. This is expected behavior. You need to complete this workflow to establish connectivity between the delegate and your instance. - Update the docker-compose.yml file you just downloaded as follows:
- For
DELEGATE TAGS=
, specify one of the following:macos-amd64
|macos-arm64
|windows-amd64
|linux-amd64
|linux-arm64
- macOS only — Add this setting to the
environment
list:- RUNNER_URL=
http://host.docker.internal:3000
- Linux only — Add the following line immediately after
restart: unless-stopped"
:network_mode: "host"
- For
- To start the delegate, cd to the folder where you downloaded the docker-compose file and then enter:
docker-compose -f <
updated-docker-compose.yml
> up -d
- Download a Drone Runner executable from https://github.com/harness/drone-docker-runner/releases .
- Enable execution permissions for the Runner. For example, on macOS you can run the command
sudo
chmod +x
drone-docker-runner-darwin-amd64
. - Start the runner binary:
- On macOS, run
./drone-docker-runner-darwin-amd64 server
Note: You might have to allow this app to be run from theSecurity and Privacy settings. - On Linux, run as sudo:
sudo ./drone-docker-runner-darwin-amd64 server
- On macOS, run
- Go back to the Delegates page where you created the new delegate. The delegate should appear as connected. This might take a few minutes.
Update the Pipeline
Update the pipeline where you want to use the Docker delegate, either from YAML or the Visual pipeline editor.
From the YAML view
Replace the stages : stage : spec : infrastructure
section for the stage to use platform
and runtime
as follows.
1. For the `os:` field, specify `Linux` | `MacOS` | `Windows`
2. For the `arch:` field, specify `Amd64` | `Arm64`
infrastructure
Field (before)
- stage:
...
spec:
...
infrastructure:
...
platform
and runtime
Fields (after, Linux example)
- stage:
...
spec:
...
platform:
os: Linux
arch: Amd64
runtime:
type: Docker
spec: {}
...
From the Visual Editor
Update the Infrastructure tab to use:
- Docker infrastructure
- Platform: Operating System and Architecture (Linux, AMD64 example below)
Troubleshooting
The delegate should connect to your instance after you finish the installation workflow above.
If the delegate does not connect after a few minutes, run the following commands to check the status:
docker ps
docker logs --follow <
docker-delegate-container-id
>
The container id should be the one with image name harness/delegate:latest
.
If you see a message like the following, the setup should be successful:
Finished downloading delegate jar version 1.0.77221-000 in 168 seconds