Getting Started

Starting up a BuildGrid server requires only installation, a configuration file and PostgreSQL database.

Starting a demo BuildGrid server

To quickly try out BuildGrid, we provide pre-built container images, and a simple docker compose configuration example which starts up BuildGrid’s services at localhost:50051.

git clone https://gitlab.com/BuildGrid/buildgrid
cd buildgrid
docker compose -f docker-compose-examples/all-in-one.yml up

This will spin up the required BuildGrid services, CAS storage, and a worker ready to receive jobs on http://localhost:50051 (or grpc://localhost:50051) from one of the compatible REAPI clients from buildbox like RECC or Trexe.

Bazel is unlikely to work without extra effort with this configuration, unless you are running Bazel from the same environment we use as the basis for our worker container. See Bazel client for Bazel-specific instructions.

trexe --remote http://localhost:50051 echo WOOT!

NB: The example docker compose files should not be used for production.

For a production workflow a separate PostgreSQL database should be setup with buildgrid/data/revisions/all.sql. If unfamiliar with this refer to the PostgreSQL documentation.

To understand how to setup and configure BuildGrid without docker compose see the Manually deploying a BuildGrid documentation.

Further job examples

BuildGrid also comes with a command-line tool for executing simple commands called bgd execute.

We’re going to send a simple job that just cats a file. All Execute requests specify an Action to execute, and each Action has an “input root,” which is a directory that the job is performed inside. bgd execute requires this input root as a command-line parameter, so let’s make one.

In another terminal, create a directory in your home directory or somewhere else that is convenient, then add a file to it:

mkdir ~/my_input_root
echo "I'm in the input root!" >> ~/my_input_root/input_root.txt

Now, let’s send the action to our running BuildGrid instance and bot with bgd execute.

bgd execute --remote http://localhost:50051 --remote-cas http://localhost:50051 command ~/my_input_root /bin/cat input_root.txt

In the above request, notice that the input root (~/my_input_root) is specified first, before the rest of the command. The file is specified relative to the input root.

If all goes well, the request should have been sent to BuildGrid, which will have farmed it out to the bot. The bot will have done the work and sent it back to BuildGrid, and bgd execute should display the response metadata. Look for the stdout_raw field, which will contain the text of the file we catted.

If the stdout_raw field is empty, the output might be stored in CAS and need to be fetched. The digest to fetch is in the stdout_digest field. We can fetch it using the bgd cas tool.

bgd cas --remote http://localhost:50051 download-file <stdout_digest> action-stdout.log

Next steps

Now that we have a working BuildGrid, it is time to run some real Actions. Usage of BuildGrid with various clients is documented in the Using section.