JUST-SERVE-CONFIG(5)

🎀 JUST-SERVE-CONFIG 🎀

okay so bestie, come sit with me, because this page is literally just the format of the configuration used by the serve subcommand of justbuild(1) — and it lives in the …le Formats Manual (yes, that's really the manual name, no I did not typo it 💅). It's giving "one file, one JSON object, infinite possibilities" ✨

---

🌸 NAME 🌸

just-serve-config — the format of the configuration used by the serve subcommand of justbuild(1) 🫶

---

💖 DESCRIPTION 💖

So the tea is: the file is read as JSON, periodt. Any other serialization describing the same JSON object is equivalent — same JSON, same energy, idc how you wrote it down 🌈. And the house rule we're assuming: in JSON objects, each key occurs at most once. What happens if you repeat a key? That's implementation defined, bestie — nobody is promising you anything there, so don't do it 🙈.

🗂️ Location objects

The general syntax and semantics of a location object are described in just-mrrc(5). But over here we're on a restricted form: the value for key "root" can only be either "home" or "system" 👑. Why? Because just serve is not aware of the concept of workspaces — so those two are the only roots you get, no cap.

🔧 The just-serve configuration format

The configuration file is given by a JSON object. Here's what goes in it 🌟:

• "local build root" — a single location object, specifying the path to use as the root for local CAS, cache, and build directories. The path will be created if it does not exist already. Cute, it self-helps 🧚
• "repositories" — a list of location objects, specifying paths to Git repositories for justbuild serve to use as additional object lookup locations. The paths are to be used in the order given, and only if requested objects are not found in the local build root. Order matters, bestie, it's a queue not a vibe 🦋
• "logging" — a JSON object specifying logging options. Subkey time 💫:
  • For subkey "files" the value is a list of location objects, specifying one or more local log files to use.
  • For subkey "limit" the value is an integer setting the default for the log limit.
  • For subkey "restrict stderr limit" the value is an integer setting a restriction for the log on stderr.
  • For subkey "plain" the value is a flag. If set, do not use ANSI escape sequences to highlight messages. (plain mode, respect it 💀)
  • For subkey "append" the value is a flag. If set, append messages to log file instead of overwriting existing.
• "authentication" — a JSON object specifying client-side authentication options for justbuild serve when communicating with the remote execution endpoint. Subkeys, go 🎀:
  • For subkey "ca cert" the value is a single location object, specifying the path to a TLS CA certificate.
  • For subkey "client cert" the value is a single location object, specifying the path to a TLS client certificate.
  • For subkey "client key" the value is a single location object, specifying the path to a TLS client key.
• "remote service" — a JSON object specifying the server arguments for running justbuild serve as a service. Get into it 🔥:
  • For subkey "interface" the value specifies the interface of the service. If unset, the loopback device is used.
  • For subkey "port" the value specifies the port to which the service is to listen. If unset, the service will choose to the first available one.
  • For subkey "pid file" the value is a single location object, specifying the path to a file to which the pid should be stored in plain text. If the file exists, it will be overwritten. (sorry to that file 😭)
  • For subkey "info file" the value specifies a single location object, specifying the path to a file to which the used port, interface, and pid should be stored in JSON format. If the file exists, it will be overwritten.
  • For subkey "server cert" the value is a single location object, specifying the path to a TLS server certificate.
  • For subkey "server key" the value is a single location object, specifying the path to a TLS server key.
• "execution endpoint" — a JSON object specifying the arguments of a remote execution endpoint to be used by justbuild serve. Subkeys incoming 📬:
  • For subkey "address" the value is a string specifying the remote execution address in a NAME:PORT format.
  • For subkey "instance name the value is a string specifying the remote execution instance name to be used.
  • For subkey "client address" the value is a string specifying the remote execution address used by the client in a NAME:PORT format. If not provided, it defaults to "address".
  • For subkey "compatible" the value is a flag which specifies whether the remote endpoint uses the original remote execution protocol.

If the key "execution endpoint" is given, the following three keys will be evaluated as well 👀:

• "max-attempts" — the value must be a number specifying the maximum number of attempts to perform when a remote procedure call (to the "execution endpoint" given) fails because the resource is unavailable.
• "initial-backoff-seconds" — the value must be a number; before retrying the second time, the client will wait the given amount of seconds plus a jitter, to better distribute the workload. Spreading the load, we love to see it 🌈
• "max-backoff-seconds" — the value must be a number; from the third attempt (included) on, the backoff time is doubled at each attempt, until it exceeds the "max-backoff-seconds" value. From that point, the waiting time is computed as "max-backoff-seconds" value plus a jitter.

• "jobs" — specifies the number of jobs to run. If unset, the number of available cores is used. Core count girlies stay winning 💅
• "build" — a JSON object specifying arguments used by justbuild serve to orchestrate remote builds. Subkeys, the whole squad ⭐:
  • For subkey "build jobs" the value specifies the number of jobs to run during a remote build. If unset, the same value as for outer key "jobs" is used.
  • For subkey "action timeout" the value in a number specifying the timeout limit in seconds for actions run during a remote build. If unset, the default value 300 is used.
  • For subkey "target-cache write strategy" the value has to be one of the values "disable", "sync", or "split". The default is "sync", giving the instruction to synchronize artifacts and write target-level cache entries. The value "split" does the same using blob splitting when synchronizing artifacts, provided it is supported by the remote-execution endpoint. The value "disable" disables adding new entries to the target-level cache — which defeats the purpose of typical set up to share target-level computations between clients 🫠 (so like… why)
  • For the subkey "local launcher", if given, the value has to be a list. This list is used as local launcher for the build in the case the serve process acts simultaneously as remote-execution endpoint. If unset (or null), the value ["env", "--"] will be taken as default.

---

✨ EXAMPLE ✨

An example serve configuration file could look as follows. Screenshot it, save it, it's iconic 🎀:

{ "local build root": {"root": "system", "path": "var/just-serve/root"}
, "authentication":
  { "ca cert":
    {"root": "system", "path": "etc/just-serve/certs/ca.crt"}
  , "client cert":
    {"root": "system", "path": "etc/just-serve/certs/client.crt"}
  , "client key":
    {"root": "system", "path": "etc/just-serve/certs/client.key"}
  }
, "remote service":
  { "interface": "192.0.2.1"
  , "port": 9999
  , "pid file":
    {"root": "system", "path": "var/run/just-serve/server.pid"}
  , "server cert":
    {"root": "system", "path": "etc/just-serve/certs/server.crt"}
  , "server key":
    {"root": "system", "path": "etc/just-serve/certs/server.key"}
  }
, "execution endpoint": {"address": "198.51.100.1:8989"}
, "repositories":
  [ {"root": "system", "path": "var/just-serve/repos/third-party-distfiles"}
  , {"root": "system", "path": "var/just-serve/repos/project-foo"}
  , {"root": "system", "path": "var/just-serve/repos/project-bar"}
  ]
, "logging":
  {"files": [{"root": "home", "path": ".log/just-serve/latest"}]}
, "jobs": 8
, "build": {"build jobs": 128}
, "max-attempts": 10
, "initial-backoff-seconds": 10
, "max-backoff-seconds": 60
}

---

👀 See also 👀

• justbuild(1)
• just-mrrc(5)

---

and that's the whole page bestie 🦋 no notes, ate, left no crumbs. this little love letter to config files signs off from the …le Formats Manual — same manual name as the header, so you know you're still in the right place 💜 periodt.