[erp5:cluster] Make it easier to use tidstorage-dict parameter.
[slapos.git] / software / erp5 / README.txt
1 Software types
2 ==============
3 Which software type is an entry point and can be used for root software
4 instance.
5
6 Parameters are expected to be passed as of *.serialised recipes expect them::
7
8 ```
9 <?xml version='1.0' encoding='utf-8'?>
10 <instance>
11   <parameter id="_">...</parameter>
12 </instance>
13 ```
14
15 where `...` is a json expression (typically a dict).
16
17 single (default)
18 ----------------
19 This creates an ERP5 instance suited for small needs/resources, or local
20 development. A minimal ERP5 site is created when instance is started.
21
22 frontend-software-url
23 ~~~~~~~~~~~~~~~~~~~~~
24 Software URL of an existing frontend.
25 XXX: meaning should change (or it will go away) in order to be resilient to
26 software updates - as they are visible at software-url level.
27 If it is not provided, no frontend will be requested.
28
29 frontend-instance-guid
30 ~~~~~~~~~~~~~~~~~~~~~~
31 GUID of frontend instance.
32 Not perfect yet: if that instance is replaced, slaves have to be reconfigured.
33 Mandatory only if frontend-software-url is also provided.
34 XXX: should be complemented (or replaced) by more flexible and precise
35 criteria.
36
37 frontend-software-type (optional)
38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39 Frontend software type as defined by the software relase at
40 frontend-software-url.
41
42 frontend-domain (optional)
43 ~~~~~~~~~~~~~~~~~~~~~~~~~~
44 Domain name frontend must recognise as belonging to this instance.
45
46 cluster
47 -------
48 This creates a massive ERP5 instance suited for high-demanding production
49 setups - which also have a lot of available resources (several machines,
50 several CPUs per machine, GBs of ram, several machines...).
51
52 For each available key in the outmost dict are described below.
53 Publishes a dict in which each entry is the URL to a balancer entry point
54 (apache listening socket), witht the same keys as zope-partition-dict.
55
56 'zodb-software-type' (str, optional)
57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58 Storage mechanism to use. To know the list of supported values, see all keys in
59 instance.cfg.in's section [switch-softwaretype] which start with "zodb-".
60 Defaults to 'zeo'.
61
62 'zodb-dict' (dict, optional)
63 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64 Describes ZODBs to create and use in the instance. At least one entry is
65 required to achieve anything sensible with the instance.
66 key (str)
67   Zope internal name for this ZODB. Used to tell mountpoints apart in the ZMI
68   when populating them.
69 value (dict)
70   key (str)
71     Possible keys and associated value types:
72     'storage-family' (str, optional)
73       Storage family. All zodbs requested with the same value are provided
74       by the same service (ex: same ZEO process). Might not be supported by
75       all zodb-software-type, silently ignored if so (ie, each ZODB gets its
76       own family).
77       Defaults to 'default'.
78     'mount-point' (str, optional)
79       Storage mount point.
80       Defaults to '/'.
81     'cache-size' (int, optional)
82       Storage ZODB cache size (aka 'Connection cache'), in objects. No value
83       is specified when negative is provided (ie, uses ZODB's default).
84       Defaults to -1.
85     'storage-dict' (dict, optional)
86       Storage-type-specific parameters. For example, it can be used to tell where
87       a ZEO filestorage database is located.
88       When zodb-software-type is 'zeo', the following keys are supported:
89       'path' (string, optional)
90         FileStorage file path. Occurrences of '%(zodb)s' are replaced with the
91         path to partition's srv/zodb directory.
92         Defaults to '%(zodb)s/', Zope's internal name for this ZODB, and '.fs'.
93       'client' (dict, optional)
94         Client(=Zope)-side settings. 'server' and 'storage' keys will be
95         overwritten. Keys and values are expected to be strings, and map
96         directly to options in the resulting <zeoclient> section.
97         Defaults to {}.
98
99 'tidstorage-dict' (dict, optional)
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101 Backup parameters for tidstorage-related backup scripts.
102 TIDStorage is not deployed if not provided.
103 key (str)
104   Possible keys and associated value types:
105   'zodb-dict' (dict, optional)
106     key (str)
107       (same as zodb-dict)
108     value (str, optional)
109       Path to store backups of this zodb into. Occurrences of '%(backup)s' are
110       replaced with the path to partition's srv/backup/zodb directory.
111     Defaults to {}.
112     If an item is missing compared to zodb-dict, value defaults to
113     '%(backup)s/' + key.
114   'timestamp-path' (str, optional)
115     Path to backup timestamp file.
116     Occurrences of '%(backup)s' are replaced with the path to partition's
117     srv/backup/tidstorage directory.
118     Defaults to '%(backup)s/repozo_tidstorage_timestamp.log'.
119
120 'zope-partition-dict' (dict, optional)
121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122 key (str)
123   Instance name.
124 value (dict)
125   Possible keys and associated value types:
126   'family' (str, optional)
127     The family this partition is part of. For example: 'public', 'admin',
128     'backoffice', 'web-service'... Each family gets its own frontend
129     (=client-facing ip & port). It has no special meaning as far as
130     buildout is concerned.
131     Defaults to 'default'.
132   'instance-count' (int, optional)
133     The number of Zopes to setup on this partition.
134     Defaults to 1.
135   'thread-amount' (int, optional)
136     The number of worker threads for each created Zope process.
137     Defaults to 1.
138   'timerserver-interval' (int, optional)
139     The timerserver tick perdiod. 0 to disable timerserver.
140     Defaults to 5.
141   'computer-guid' (string, optional)
142     Computer on which partition should be allocated.
143     Defauts to the same computer as the one this .cfg is executed in.
144   'longrequest-logger-interval' (int, optional)
145     The period, in seconds, with which LongRequestLogger polls worker thread
146     stack traces. -1 to disable.
147     Defaults to -1.
148   'longrequest-logger-timeout' (int, optional)
149     The transaction duration after which LongRequestLogger will start logging
150     its stack trace, in seconds. Ignored if longrequest-logger-interval is -1.
151     Defaults to 1.
152   'port-base' (int, optional)
153     Start allocating ports at this value. Useful if one needs to make several
154     partitions share the same port range (ie, several partitions bound to a
155     single address).
156     Defaults to 2000.
157
158 'haproxy-maxconn' (int, optional)
159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160 The number of connections haproxy accepts for a given backend.
161 See haproxy's "server maxconn" setting.
162 Defaults to 1 (correct for single-worker-threaded zopes).
163
164 'haproxy-server-check-path' (str, optional)
165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166 The path haproxy accesses on a each backend to test their responsiveness.
167 Occurrences of '%(site-id)s' are replaced with site-id value (see below).
168 Defaults to '/'.
169
170 'apache-backend-path' (str, optional)
171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172 Used as a rewriterule to strip components from site's URL.
173 Occurrences of '%(site-id)s' are replaced with site-id value (see below).
174 XXX: You may want to avoid using this when also requesting a frontend apache.
175 Defaults to '/' (ie, nothing is stripped).
176
177 'apache-access-control-string' (str, optional)
178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179 The list of hosts apache accepts connections from.
180 Defaults to 'all'.
181
182 'apache-ssl-authentication' (booleanish, optional)
183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
184 Controls certificate-based authentication.
185 Defaults to '0' (disabled).
186
187 'site-id' (str, optional)
188 ~~~~~~~~~~~~~~~~~~~~~~~~~
189 Site object's id. Defaults to 'erp5'.
190
191 'ca' (dict, optional)
192 ~~~~~~~~~~~~~~~~~~~~~
193 Certificate autority parameters.
194 Possible keys and associated value types:
195 'country-code' (str, optional)
196   ISO 3166-1 alpha-2 country code. Defaults to 'ZZ'.
197 'email' (str, optional)
198   E-mail address. Defaults to 'nobody@example.com'
199 'state' (str, optional)
200   State name. Defaults to 'Dummy State'.
201 'city' (str, optional)
202   City name. Default to 'Dummy City'.
203 'company' (str, optional)
204   Company name. Defaults to 'Dummy Company'.
205
206 'use-ipv6' (boolean, optional)
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
208 Use IPv6 to communicate between partitions.
209 Defaults to False.
210
211 'test-database-amount' (int, optional)
212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
213 The number of databases to create in mariadb instance for tests' needs.
214 Defaults to 0.
215
216 'mariadb-computer-guid' (str, optional)
217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
218 Computer GUID identifying the partition mariadb is to be requested on.
219 Defaults to "cluster" software type's partition's effective computer GUID.
220
221 'cloudooo-computer-guid' (str, optional)
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223 Computer GUID identifying the partition cloudooo is to be requested on.
224 Defaults to "cluster" software type's partition's effective computer GUID.
225
226 'memcached-computer-guid' (str, optional)
227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
228 Computer GUID identifying the partition memcached is to be requested on.
229 Defaults to "cluster" software type's partition's effective computer GUID.
230
231 'kumofs-computer-guid' (str, optional)
232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233 Computer GUID identifying the partition kumofs is to be requested on.
234 Defaults to "cluster" software type's partition's effective computer GUID.
235
236 'zodb-computer-guid' (str, optional)
237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
238 Computer GUID identifying the partition ZODB server is to be requested on.
239 Defaults to "cluster" software type's partition's effective computer GUID.
240
241 'balancer-computer-guid' (str, optional)
242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243 Computer GUID identifying the partition balander (haproxy, apache, some HTTP
244 cache) is to be requested on.
245 Defaults to "cluster" software type's partition's effective computer GUID.
246
247 'cloudooo-json' (str, optional)
248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
249 XXX: what is this ?
250 XXX: should not require serialising json by hand as parameter value
251
252 'bt5' (str, optional)
253 ~~~~~~~~~~~~~~~~~~~~~
254 XXX: what is this ?
255
256 'bt5-repository-url' (str, optional)
257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
258 XXX: what is this ?
259
260 'smtp-url' (str, optional)
261 ~~~~~~~~~~~~~~~~~~~~~~~~~~
262 XXX: what is this ?
263
264 'timezone' (str, optional)
265 ~~~~~~~~~~~~~~~~~~~~~~~~~~
266 Timezone to put processes in (default timezone for DateTime instances).
267
268 'frontend-software-url' (str, optional)
269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
270 Frontend's software url.
271 Defaults to ''.
272 If non-empty, the following options are used (otherwise, they are all
273 optional and ignored):
274
275 'frontend-software-type' (str, optional)
276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
277 Frontend's software type.
278 Defaults to 'RootSoftwareInstance'
279
280 'frontend-instance-guid' (str, mandatory)
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282 Instance GUID identifying the partition frontend is on.
283
284 'frontend-domain' (str, optional)
285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286 The domain name used to access this ERP5 cluster, ignored if empty.
287 Defaults to ''.
288
289 For a better description of these parameters, see a frontend software
290 release documentation.
291