BuildBuddy on AWS User Guide

Overview

This image runs BuildBuddy, an open source platform that makes Bazel builds faster and easier to debug. It combines a remote cache, a Build Event Protocol (BES) results store and a web dashboard, so your developers and CI stop rebuilding what has already been built and get a shareable, drillable view of every invocation. Point Bazel at this appliance and the first machine to build a target populates the cache; everyone else, including CI, downloads the result instead of recompiling.

This image runs the pinned upstream open source on-prem BuildBuddy container as a systemd managed service, self contained on SQLite and local disk with no external database to run. The dashboard is served on TCP 8080 and the gRPC cache and Build Event Protocol endpoint on TCP 1985.

Secure by default. Open source BuildBuddy ships with no built in authentication, so this image fronts the dashboard with an nginx reverse proxy that enforces HTTP Basic Auth, and there is no shared or default credential. On the first boot of your instance a one shot service generates a unique administrator password for that specific instance and writes it to a root owned file, so no two instances share a secret. The proxy fails closed with a non matching placeholder until first boot writes the real credential, so the dashboard is never open. The appliance also learns its own public address on every boot, so invocation links always work.

Open source, MIT licensed. This appliance ships only the official open source on-prem BuildBuddy image, built from the MIT licensed core. The enterprise only code is not bundled.

Connecting to your instance

SSH in as the default login user for your operating system variant:

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 (SSH) from your management network, inbound port 8080 (dashboard) and inbound port 1985 (gRPC cache and Build Event Protocol) from your own developer and CI hosts
• Bazel on the developer and CI machines you want to accelerate (or use the bundled bazelisk on the instance to self test)

Step 1: Launch the Instance from the AWS Marketplace

1. Open the product page on AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration.
2. Select the region and the m5.large instance type (or larger for a bigger shared cache), then Continue to Launch.
3. Under Launch, choose your VPC, subnet, key pair and a security group that opens ports 22, 8080 and 1985 as described above, then launch.

Step 2: Launch the Instance from the AWS CLI

aws ec2 run-instances \
  --image-id <ami-id-from-marketplace> \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids <sg-with-22-8080-1985> \
  --subnet-id <subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=buildbuddy}]'

Step 3: Connect to Your Instance

ssh -i your-key.pem ubuntu@<public-ip>

Step 4: Confirm BuildBuddy Is Running

BuildBuddy runs as a Docker container behind an nginx reverse proxy. Confirm the services are active and listening:

systemctl is-active docker nginx buildbuddy
ss -ltn | grep -E ':8080|:1985'

You should see active for all three services, nginx listening on 8080 and BuildBuddy listening on 1985.

Step 5: Retrieve This Instance's Administrator Password

On first boot a unique administrator password is generated for this instance and written to a root owned file. Read it with:

sudo cat /root/buildbuddy-credentials.txt

The file contains BUILDBUDDY_ADMIN_USER (which is admin), BUILDBUDDY_ADMIN_PASSWORD, the dashboard URL and the gRPC endpoint for this instance.

Step 6: Open the Dashboard

Open http://<public-ip>:8080 in a browser and sign in as admin with the password from Step 5. The dashboard shows the Quickstart, and every Bazel invocation you stream to it appears with targets, timing, the critical path, test logs and cache statistics.

Step 7: Point Bazel at the Cache and Build Event Protocol

On your developer or CI machines, add these flags to your build (or put them in your .bazelrc). Replace <public-ip> with your instance's address:

bazel build //... \
  --bes_backend=grpc://<public-ip>:1985 \
  --bes_results_url=http://<public-ip>:8080/invocation/ \
  --remote_cache=grpc://<public-ip>:1985

Bazel prints a BuildBuddy invocation URL at the start and end of the build. Open it to inspect the invocation. The cache statistics view shows the cache being populated and, on subsequent builds, hit.

Step 8: Self Test the Cache on the Instance

A bundled bazelisk and a minimal workspace at /opt/buildbuddy-selftest let you confirm the cache accelerates a real build directly on the box. Replace <public-ip> with your instance's address:

cd /opt/buildbuddy-selftest
sudo bazelisk build //:hello \
  --bes_backend=grpc://<public-ip>:1985 \
  --remote_cache=grpc://<public-ip>:1985

The build streams to the dashboard, and a second run after sudo bazelisk clean reports a remote cache hit.

Step 9: Authentication Is Enforced

The dashboard is only reachable with the per instance administrator credential. An unauthenticated request is rejected with 401; only the correct password returns 200:

PW=$(sudo grep '^BUILDBUDDY_ADMIN_PASSWORD=' /root/buildbuddy-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'unauthenticated: %{http_code}\n' http://127.0.0.1:8080/
curl -s -o /dev/null -w 'authenticated:   %{http_code}\n' -u "admin:$PW" http://127.0.0.1:8080/

The first command prints 401 and the second prints 200.

Step 10: Restrict the gRPC Endpoint and Add TLS

The open source gRPC cache and Build Event Protocol endpoint on port 1985 has no built in authentication (that is upstream's design). Scope the instance security group so that only your own developer and CI hosts can reach TCP 1985 and 8080. For production, front the dashboard with your own DNS and TLS termination and set app.build_buddy_url in /etc/buildbuddy/config.yaml to your public hostname.

Production Notes

• Cache size. The disk cache lives under /var/lib/buildbuddy on the OS disk with a default cap of 10 GB. Grow the EBS root volume and raise cache.max_size_bytes in /etc/buildbuddy/config.yaml, then sudo systemctl restart buildbuddy, for a larger shared cache.
• Remote build execution (RBE) is not enabled on this single instance appliance; it provides the remote cache and results store, which accelerate the vast majority of Bazel builds. Run BuildBuddy executors separately if you need RBE.
• Metrics. BuildBuddy exposes Prometheus metrics on loopback 127.0.0.1:9090.

Support

cloudimg provides 24/7 technical support for this BuildBuddy product by email (support@cloudimg.co.uk) and live chat. We help with deployment, retrieving the per instance administrator password, pointing Bazel at the cache and Build Event Protocol endpoint, sizing the cache, restricting the gRPC endpoint, adding TLS, and BuildBuddy version upgrades. For billing, subscription changes, or refund requests, contact support@cloudimg.co.uk.