Provided by: justbuild_1.5.1-1ubuntu2_amd64 
NAME
just-serve-config - The format of the configuration used by the serve subcommand of justbuild(1)
DESCRIPTION
The file is read as JSON. Any other serialization describing the same JSON object is equivalent. We
assume, that in JSON objects, each key occurs at most once; it is implementation defined how repetitions
of the same key are treated.
Location objects
The general syntax and semantics of a location object are described in just-mrrc(5). Here we use a
restricted form where the value for key "root" can only be either "home" or "system". This is because
just serve is not aware of the concept of workspaces.
The just-serve configuration format
The configuration file is given by a JSON object.
• The value for the key "local build root" is 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.
• The value for the key "repositories" is 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.
• The value for the key "logging" is a JSON object specifying logging options.
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.
For subkey "append" the value is a flag. If set, append messages to log file instead of overwriting
existing.
• The value for the key "authentication" is a JSON object specifying client-side authentication options
for justbuild serve when communicating with the remote execution endpoint.
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.
• The value for the key "remote service" is a JSON object specifying the server arguments for running
justbuild serve as a service.
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.
For subkey "info file" the value specifies a single location object, specifying the path to a file 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.
• The value for the key "execution endpoint" is a JSON object specifying the arguments of a remote
execution endpoint to be used by justbuild serve.
For subkey "address" the value is a string specifying the remote execution address in a NAME:PORT format.
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.
• "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.
• The value for the key "jobs" specifies the number of jobs to run. If unset, the number of available
cores is used.
• The value for the key "build" is a JSON object specifying arguments used by justbuild serve to
orchestrate remote builds.
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.
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.
{ "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)
JUST SERVE CONFIG(5) | File Formats Manual()