1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
% JUST SERVE CONFIG(5) | File Formats Manual
NAME
====
**`just`** **`serve`** configuration - 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 *`"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)
|
