Installation onto host machine

How to install BuildGrid directly onto your machine.


BuildGrid server currently only support Linux. macOS and Windows platforms are not supported.


BuildGrid only supports python3 >= 3.5 but has no system requirements. Main Python dependencies, automatically handled during installation, include:

Install from sources

BuildGrid has setuptools support. In order to install it to your home directory, typically under ~/.local, simply run:

git clone && cd buildgrid
pip3 install --user --editable .

Additionally, and if your distribution does not already include it, you may have to adjust your PATH, in ~/.bashrc, with:

export PATH="${PATH}:${HOME}/.local/bin"


The script defines three extra targets, auth, docs and tests. They declare required dependency for, respectively, authentication and authorization management, generating documentation and running unit-tests. They can be use as helpers for setting up a development environment. To use them simply run:

pip3 install --user --editable ".[auth,docs,tests]"

Installation through Docker

How to build a Docker image that runs BuildGrid.


A working Docker installation. Please consult Docker’s Getting Started Guide if you don’t already have it installed.

Docker Container from Sources

To clone the source code and build a Docker image, simply run:

git clone && cd buildgrid
docker build -t buildgrid_server .


The image built will contain the contents of the source code directory, including configuration files.


Whenever the source code is updated or new configuration files are made, you need to re-build the image.

After building the Docker image, to run BuildGrid using the default configuration file (found in buildgrid/_app/settings/default.yml), simply run:

docker run -i -p 50051:50051 buildgrid_server


To run BuildGrid using a different configuration file, include the relative path to the configuration file at the end of the command above. For example, to run the default standalone CAS server (without an execution service), simply run:

docker run -i -p 50052:50052 buildgrid_server buildgrid/_app/settings/cas.yml