Improve documentation for the Buildbarn example

Author: stagnation

examples/remote_execution/buildbarn/.buckconfig

@@ -2,13 +2,10 @@
 root = .
 prelude = prelude
 
-[buck2]
-digest_algorithms = SHA256
-
 [buck2_re_client]
-action_cache_address = http://localhost:8980
-engine_address = http://localhost:8980
-cas_address = http://localhost:8980
+action_cache_address = grpc://localhost:8980
+engine_address = grpc://localhost:8980
+cas_address = grpc://localhost:8980
 
 [build]
   execution_platforms = root//platforms:platforms

examples/remote_execution/buildbarn/README.md

@@ -1,30 +1,51 @@
-## Remote execution integration with Build Barn
+## Remote execution integration with Buildbarn
 
-This project provides a small example of what a project that utilizes [Build Barn](https://github.com/buildbarn) for RE might look like.
+This project provides a small example of what a project that utilizes [Buildbarn](https://github.com/buildbarn).
 
 In this document, we will go over the key configs used in this setup.
+Using a local docker-compose deployment from the [example deployment repo](https://github.com/buildbarn/bb-deployments)
 
-### Relevant configs in .buckconfig
+### Deploy Buildbarn
 
-First, the Build Barn endpoint and certificate should be configured as the following:
+This is mostly a turn-key solution, with just one modification.
+Buck2 does not yet support instance-name prefixes for different workers [issue link](https://github.com/facebook/buck2/issues/180).
+So we will remove that from the deployment.
 
-```ini
-[buck2_re_client]
-engine_address       = $BB_ENDPOINT
-action_cache_address = $BB_ENDPOINT
-cas_address          = $BB_ENDPOINT
 ```
+... $ git clone https://github.com/buildbarn/bb-deployments
+... $ cd bb-deployments
+.../bb-deployments # Temporary workaround for issue #180: Remove the instance-name prefix
+.../bb-deployments $ sed -i 's/instanceNamePrefix: \'fuse\'/instanceNamePrefix: \'\'/' docker-compose/config/worker-fuse-ubuntu22-04.jsonnet
+.../bb-deployments $ cd docker-compose
+.../bb-deployments/docker-compose $ ./run.sh
+```
+
+This uses `docker-compose` to spin up the required Buildbarn services.
+Using FUSE based workers, those are generally the fastest as they can load action files on demand
+and avoids the overhead of setting up the full input root up front.
+In practice many actions do not read all the files in the input root.
+
+If you do not want FUSE workers you can instead switch to hardlinking workers
+```
+.../bb-deployments $ sed -i 's/instanceNamePrefix: \'hardlinking\'/instanceNamePrefix: \'\'/' docker-compose/config/worker-hardlinking-ubuntu22-04.jsonnet
+```
+
+More information is available in the [repo](https://github.com/buildbarn/bb-deployments).
+
+### Relevant configs in .buckconfig
 
-If you're using the Docker-compose setup, the endpoint would be `http://localhost:8980` for all 3 of those.
+First, the Buildbarn endpoint should be configured as the following:
 
-Additionally, set the `digest_algorithm` config to `SHA256`.
 ```ini
-[buck2]
-digest_algorithms = SHA256
+[buck2_re_client]
+engine_address       = grpc://localhost:8980
+action_cache_address = grpc://localhost:8980
+cas_address          = grpc://localhost:8980
 ```
 
-### Relevant configs in `ExecutionPlatformInfo`
+No TLS is used in this example (for history see this [issue](https://github.com/facebook/buck2/issues/156)).
 
-Build Barn takes in a Docker image and OSFamily  in its RE properties to select a worker.
+### Relevant configs in `ExecutionPlatformInfo`
 
-The execution platform used in this project `root//platforms:platforms` do so.
+The Buildbarn workers take in a Docker image as their execution platform.
+The execution platform used in this project `root//platforms:platforms` uses the `container-image` key to set this up.

examples/remote_execution/buildbarn/platforms/defs.bzl

@@ -21,6 +21,8 @@ def _platforms(ctx):
             # Set those up based on what workers you've registered with Build Barn.
             remote_execution_properties = {
                 "OSFamily": "Linux",
+                # This could be any Docker image.
+                # This one is Ubuntu 22.04 with many common language tools installed.
                 "container-image": "docker://ghcr.io/catthehacker/ubuntu:act-22.04@sha256:5f9c35c25db1d51a8ddaae5c0ba8d3c163c5e9a4a6cc97acd409ac7eae239448",
             },
             remote_execution_use_case = "buck2-default",