Deployment guide

BuildBuddy

Overview

This image runs BuildBuddy v2.287.0, the open source Bazel build acceleration platform from buildbuddy-io, on Ubuntu 24.04 LTS. BuildBuddy combines a remote content-addressable cache, a Build Event Protocol (BES) results store, and a web dashboard, so your team stops rebuilding what has already been built and gets a shareable, drillable view of every Bazel invocation. Point Bazel at the appliance, and action results are cached centrally. The first machine to build a target populates the cache, and everyone else, including CI, downloads the result instead of recompiling.

The appliance ships the official open source on-prem image (gcr.io/flame-public/buildbuddy-app-onprem, pinned by digest), run as a systemd-managed container. It is self-contained on SQLite plus a local disk cache, so there is no external database to run. The dashboard is served on port 8080, fronted by an nginx reverse proxy with HTTP Basic Auth. The gRPC BES and remote cache endpoint is served on port 1985.

BuildBuddy's core is open source and MIT licensed. The project's enterprise/ code is under a separate commercial license and is not part of this image. This appliance ships only the open source on-prem build.

What you get:

BuildBuddy v2.287.0 (official open source buildbuddy-app-onprem image, pinned by digest), run by systemd
The BuildBuddy dashboard on :8080, behind an nginx HTTP Basic Auth reverse proxy
The gRPC BES and remote cache endpoint on :1985 for Bazel clients
A per-VM dashboard administrator password, generated on first boot and recorded in a root-only file
Self-contained storage: SQLite plus a local disk cache under /var/lib/buildbuddy, with no external datastore
A pre-installed bazelisk and a self-test workspace at /opt/buildbuddy-selftest, so you can prove the cache from the VM
docker.service, nginx.service and buildbuddy.service as systemd units, enabled and active
No default login in the image
24/7 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point. For a larger shared cache, choose a larger size and grow the OS disk.

In the NSG, allow inbound 22/tcp from your management network, 8080/tcp for the dashboard, and 1985/tcp for Bazel clients. The gRPC endpoint on port 1985 has no built-in authentication in the open source edition. Restrict 1985/tcp to your trusted build hosts and CI in the NSG. BuildBuddy serves plain HTTP, so for production, front it with your own domain and TLS.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure portal, choose Create a resource, search the Marketplace for BuildBuddy by SecureAnyCloud, and select Create. On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22), 8080 and 1985. Then choose Review + create, and then Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:buildbuddy-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name buildbuddy \
  --image sac1647283583153:buildbuddy-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name buildbuddy --port 8080 --priority 1010
az vm open-port --resource-group <your-rg> --name buildbuddy --port 1985 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

BuildBuddy runs as the buildbuddy systemd service (the official buildbuddy-app-onprem container), with nginx providing the Basic Auth reverse proxy and docker providing the runtime. Confirm that all three services are active, and that the dashboard (8080) and gRPC cache (1985) ports are listening:

systemctl is-active docker nginx buildbuddy
sudo ss -tlnp | grep -E ':8080|:1985|:8081|:9090' | awk '{print $4}' | sort -u

Expected output:

active active active 0.0.0.0:1985 0.0.0.0:8080 127.0.0.1:8081 127.0.0.1:9090

Port 8080 is the public nginx Basic Auth proxy. Port 1985 is the gRPC BES and remote cache endpoint for Bazel. Ports 8081 (BuildBuddy's own web port) and 9090 (Prometheus metrics) are bound to loopback and reached only through the proxy.

Step 5 - Retrieve your per-VM credentials

On the first boot of every VM, buildbuddy-firstboot.service generates a unique dashboard administrator password, writes it to the nginx Basic Auth file, and records the access URLs and the credential in a root-only file. Read the file with:

sudo cat /root/buildbuddy-credentials.txt

Expected output (your password and IP will differ):

BUILDBUDDY_URL=http://<vm-public-ip>:8080 BUILDBUDDY_ADMIN_USER=admin BUILDBUDDY_ADMIN_PASSWORD=<unique-per-VM-password> BUILDBUDDY_GRPC_URL=grpc://<vm-public-ip>:1985

There is no default or shared credential in the image, and the password is unique to this VM. buildbuddy-configure.service sets the URLs to this VM's detected public IP on every boot, so the links work over the Azure public IP without further setup.

Step 6 - Confirm the dashboard is secured

The dashboard is fronted by nginx with HTTP Basic Auth. Confirm that an unauthenticated request is rejected (401), that a wrong password is rejected (401), and that the per-VM administrator credential is accepted (200):

U=$(sudo grep '^BUILDBUDDY_ADMIN_USER=' /root/buildbuddy-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^BUILDBUDDY_ADMIN_PASSWORD=' /root/buildbuddy-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'no auth: %{http_code}\n' http://127.0.0.1:8080/
curl -s -o /dev/null -w 'wrong pass: %{http_code}\n' -u "$U:wrong" http://127.0.0.1:8080/
curl -s -o /dev/null -w 'admin: %{http_code}\n' -u "$U:$P" http://127.0.0.1:8080/

Expected output:

no auth: 401 wrong pass: 401 admin: 200

Step 7 - Accelerate a real Bazel build (self-test)

The image ships bazelisk and a minimal Bazel workspace at /opt/buildbuddy-selftest so you can prove the remote cache from the VM. Copy it to a writable directory, then build it twice. The first build populates the cache. The second build, after a clean, is served from the cache (remote cache hit).

cp -r /opt/buildbuddy-selftest ~/bb-selftest && cd ~/bb-selftest bazel build //:hello \
  --bes_backend=grpc://127.0.0.1:1985 \
  --bes_results_url=http://127.0.0.1:8080/invocation/ \
  --remote_cache=grpc://127.0.0.1:1985 bazel clean bazel build //:hello \
  --bes_backend=grpc://127.0.0.1:1985 \
  --bes_results_url=http://127.0.0.1:8080/invocation/ \
  --remote_cache=grpc://127.0.0.1:1985

The second build reports a remote cache hit, and each build prints a Streaming build results to: link to its invocation in the dashboard:

INFO: 2 processes: 1 remote cache hit, 1 internal. INFO: Build completed successfully, 2 total actions INFO: Streaming build results to: http://<vm-public-ip>:8080/invocation/<invocation-id>

The first bazelisk run downloads the pinned Bazel version, so it takes a little longer. On your own machines, point any Bazel build at this appliance with the same --bes_backend and --remote_cache flags (using grpc://<vm-public-ip>:1985), or add them to a .bazelrc.

Step 8 - Open the dashboard

Browse to http://<vm-public-ip>:8080/ and sign in with admin and the password from your credentials file. The landing page is a Quickstart that shows the exact .bazelrc configuration for this appliance. The --bes_results_url and --bes_backend lines are prefilled with this VM's own address, ready to copy into any Bazel project.

Step 9 - Inspect an invocation

Open the invocation link that Bazel printed in Step 7 (Streaming build results to: http://.../invocation/<id>) to reach its detail page. BuildBuddy shows whether the build succeeded, the targets built, the command line, timing and critical path, and per-invocation cache statistics. This shareable, drillable view makes a failing or slow build easy to diagnose.

Step 10 - Review the cache performance

Open the invocation's Cache tab (or the second cached build's invocation) to see cache requests, hits and bytes transferred. These figures show that the remote cache served artifacts instead of rebuilding them. Use this view to confirm the acceleration your team gets across builds and CI.

Step 11 - Production hardening

The image ships a fully functional cache, results store and dashboard. For production, apply the following measures:

Restrict the gRPC endpoint. Open source BuildBuddy does not authenticate the gRPC cache and BES endpoint on 1985, so anyone who can reach it can read and write the cache. Restrict 1985/tcp to your trusted build hosts and CI runners in your NSG.
Add TLS and DNS. Front the dashboard with your own domain and a TLS-terminating reverse proxy or Azure Application Gateway. BuildBuddy generates invocation links from app.build_buddy_url in /etc/buildbuddy/config.yaml. If you front the dashboard yourself, set that value to your https:// address and run sudo systemctl restart buildbuddy.
Rotate the dashboard password. Replace the Basic Auth credential with sudo htpasswd -B /etc/buildbuddy/htpasswd admin and then run sudo systemctl reload nginx.
Plan for remote build execution (RBE). This single-VM appliance provides the remote cache and results store, which accelerate the majority of Bazel builds. Full RBE (running actions on remote executors) is out of scope for a single VM. Run BuildBuddy executors separately if you need it.

Maintenance

Back up your data. The invocation history (SQLite) and cache live under /var/lib/buildbuddy on the OS disk. Snapshot the OS disk to back them up. The cache is safe to discard and refills over time.
Set a public URL. app.build_buddy_url is set to the detected public IP on each boot. For a stable hostname or HTTPS, set it in /etc/buildbuddy/config.yaml and run sudo systemctl restart buildbuddy.
Apply security updates. Unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
Upgrade BuildBuddy. The BuildBuddy image is pinned for reproducibility. To upgrade, pull a newer buildbuddy-app-onprem tag and update it in /etc/systemd/system/buildbuddy.service.

Support

SecureAnyCloud provides 24/7/365 expert technical support for this image. Contact sales@secureanycloud.com for help. BuildBuddy's open source core is licensed under the MIT License. SecureAnyCloud provides this image, and additional charges apply for build, maintenance and 24/7 support.

Deploy on Azure

Launch BuildBuddy on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

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 is served on TCP 1985.

What you get:

An nginx reverse proxy that enforces HTTP Basic Auth in front of the dashboard. Open source BuildBuddy ships with no built-in authentication, and there is no shared or default credential in this image.
A unique administrator password for each instance. On the first boot, a one-shot service generates the password and writes it to a root-owned file, so no two instances share a secret.
A proxy that fails closed. It uses a non-matching placeholder until first boot writes the real credential, so the dashboard is never open.
Automatic detection of the instance's public address on every boot, so invocation links keep working
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.

Operating system variant: Ubuntu 24.04 LTS.

SSH login user: ubuntu.

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 that allows inbound port 22 (SSH) from your management network, and inbound port 8080 (dashboard) and port 1985 (gRPC cache and Build Event Protocol) from your own developer and CI hosts
Bazel on the developer and CI machines that you want to accelerate (or the bundled bazelisk on the instance, for a self-test)

Launch the instance from the AWS Marketplace

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

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}]'

Connect to your instance

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

Confirm that BuildBuddy is running

BuildBuddy runs as a Docker container behind an nginx reverse proxy. Confirm that 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.

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 the file 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.

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. Every Bazel invocation that you stream to it appears with targets, timing, the critical path, test logs and cache statistics.

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 the URL to inspect the invocation. The cache statistics view shows the cache being populated and, on later builds, being hit.

Self-test the cache on the instance

A bundled bazelisk and a minimal workspace at /opt/buildbuddy-selftest let you confirm that the cache accelerates a real build directly on the instance. 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.

Verify that authentication is enforced

The dashboard is reachable only with the per-instance administrator credential. An unauthenticated request is rejected with 401, and 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.

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, by upstream 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. For a larger shared cache, grow the EBS root volume, raise cache.max_size_bytes in /etc/buildbuddy/config.yaml, and then run sudo systemctl restart buildbuddy.
Remote build execution (RBE). RBE is not enabled on this single-instance appliance. The appliance 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

SecureAnyCloud provides 24/7 technical support for this BuildBuddy product by email (sales@secureanycloud.com) 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 sales@secureanycloud.com.

Deploy on AWS

Launch BuildBuddy on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS