% JUST SERVE CONFIG(5) | File Formats Manual NAME ==== just-serve-config - The format of the configuration used by the **`serve`** subcommand of **`just`**(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 **`just`** **`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 **`just`** **`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 **`just`** **`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 **`just`** **`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 **`just`** **`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. ```jsonc { "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 ======== **`just`**(1), **`just-mrrc`**(5)