kbf

Quick start

From a host to your first remote build. Each step is tagged: works today is in the code, specified is decided in the design documents and not built yet.

One rule for the command line. A host's role is a flag, --mode=frontend|storage|daemon|storage-and-daemon|all-in-one, or mode = "..." in /etc/kbf/kbf.toml. It is never a subcommand. The word form (kbf all-in-one) still works as a hidden alias, but help and errors name the flag.

  1. Install kbf-installer specified

    kbf-installer is the one package of the farm: it installs and verifies the kbf release, runs as a service, and takes update orders. Pick a channel on the install page.

    # Any Linux host: the install script
$ curl -fsSL https://kbf.dev/install.sh | sudo sh
    # Debian and Ubuntu
$ sudo apt install ./kbf-installer_VERSION_amd64.deb

  2. Set up a mode specified

    Installing starts nothing. setup fetches and verifies the first release, writes /etc/kbf/kbf.toml, creates the users and directories, and starts the units. For a single machine:

    $ sudo kbf-installer setup --mode=all-in-one

    A frontend host needs a Postgres database you provide; setup creates the schema. A storage or daemon host passes --token-file with its enrollment token. The flags are in the installer contract.

  3. Check the settings works today

    Every mode reads its settings from kbf.toml and takes --check, which prints every missing prerequisite and exits non-zero. All keys are on the configuration page.

    $ kbf all-in-one --check

  4. Point Buck2 at the frontend works today

    In the .buckconfig of your project, send actions, cache reads and blobs to the frontend's REAPI address (port 8980 by default) and use SHA-256 digests:

    [buck2]
  digest_algorithms = SHA256

[buck2_re_client]
  engine_address = grpc://FRONTEND:8980
  action_cache_address = grpc://FRONTEND:8980
  cas_address = grpc://FRONTEND:8980
  tls = false
  instance_name = main

    Replace FRONTEND with your frontend's name. Without a certificate the listener speaks plain text; turn on TLS with reapi-tls-cert and reapi-tls-key and set tls = true.

  5. Build works today

    Run a build with remote execution enabled. A second run, on any machine, is answered from the cache.

    $ buck2 build //... --prefer-remote

Next: how updates work, or the architecture.