Make ERP5 SR able to deploy an ERP5 cluster.
[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 TCPv4 ports allocation
18 ----------------------
19 Service listening ports are allocated in the following pattern.
20 Base port of each software can be overridden, those are the default values.
21 - kumofs (persistent)
22   2000: manager
23   2001: server port (?)
24   2002: server listen port (?)
25   2003: gateway port (?)
26 - kumofs (volatile)
27   2010: manager
28   2011: server port (?)
29   2012: server listen port (?)
30   2013: gateway port (?)
31 - cloudooo
32   2020: cloudooo
33   2021: openoffice
34 - mariadb
35   2099: mariadb
36 - zeo & tidstorage
37   2100: tidstorage
38   2101: first zeo
39   2102: second zeo
40   (etc)
41 - haproxy
42   2150: first haproxy
43   2151: first apache
44   2152: second haproxy
45   2153: second apache
46   (etc)
47 - cluster-zope
48   2200: first zope
49   2201: second zope
50   (etc)
51 Note: these are not applicable when (yet unsupported) ipv6 mode is enabled, as
52 stunnel (used to tunnel ipv4-only services over ipv6) needs its own listening
53 ports.
54 This pattern was chosen to make it possible to deploy this software release in
55 a setup where all partitions would share the same IPv4 without having to
56 provide many parameters.
57 Some ports are unused in the overall range to allow software types to grow.
58
59 common
60 ------
61 Parameters which are available to all software types.
62
63 'mariadb-dict' (dict, optional)
64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
65 MariaDB (used for catalog, activity tables and id generator) instance
66 parameters.
67 Defaults to {}.
68 Possible keys and associated value types:
69 'tcpv4-port' (int, optional)
70   TCPv4 port to listen on.
71   Defaults to 2099.
72 'database-list' (list, optional)
73   Define the list of databases mariadb must provide, and the user having entire
74   access to each database. Each entry in the list is a dict, with these
75   possible keys and associated value types:
76   'name' (str, mandatory)
77     Database name
78   'user' (str, mandatory)
79     User login
80   'password' (str, mandatory)
81     User password
82   Defaults to: [{'name': 'erp5', 'user': 'user', 'password': 'insecure'}]
83 'test-database-amount' (int, optional)
84   Number of test databases to generate in addition of requested databases.
85   A test database, if it were provided as a database-list entry, would look
86   like:
87     {'name': 'erp5_test_0', 'user': 'testuser_0', 'password': 'testpassword0'}
88   with '0' being all numbers from 0 to test-database-amount - 1.
89   Defaults to 30.
90   Note: the default is way too much for "normal" usage. You are encouraged to
91   provide this key to some lower value: 0 if you don't intend to run any unit
92   test (ex: production instance) 3..5 if you intend to run tests without
93   paralellism.
94 'full-retention-days' (int, optional)
95   The number of days full backups will be kept.
96   If -1, backups are disabled.
97   If 0, backup never expire.
98   Defaults to 7.
99 'incremental-retention-days' (int, optional)
100   The number of days binlogs will be kept.
101   If -1, binlogs are disabled.
102   If 0, binlogs are never expired.
103   Defaults to 'full-retention-days' value.
104 'innodb-buffer-pool-size' (str, optional)
105   See mariadb documentation for innodb_buffer_pool_size configuration
106   parameter. Value is used verbatim in configuration file.
107   Empty string means unconfigured (ie, bail out to mariadb's default).
108   Defaults to "".
109 'innodb-log-file-size' (str, optional)
110   See mariadb documentation for innodb_log_file_size configuration parameter.
111   Value is used verbatim in configuration file.
112   Empty string means unconfigured (ie, bail out to mariadb's default).
113   Defaults to "".
114 'innodb-log-buffer-size' (str, optional)
115   See mariadb documentation for innodb_log_buffer_size configuration parameter.
116   Value is used verbatim in configuration file.
117   Empty string means unconfigured (ie, bail out to mariadb's default).
118   Defaults to "".
119 'mariadb-relaxed-writes' (int, optional)
120   Controls relaxed writes, which improves performances at the cost of data
121   safety. DO NOT ENABLE THIS ON PRODUCTION. It's fine for unit tests and may be
122   acceptable for development instances. Set to 1 to enable.
123   Default: 0
124
125 single (default)
126 ----------------
127 This creates an ERP5 instance suited for small needs/resources, or local
128 development. A minimal ERP5 site is created when instance is started.
129
130 frontend-software-url
131 ~~~~~~~~~~~~~~~~~~~~~
132 Software URL of an existing frontend.
133 XXX: meaning should change (or it will go away) in order to be resilient to
134 software updates - as they are visible at software-url level.
135 If it is not provided, no frontend will be requested.
136
137 frontend-instance-guid
138 ~~~~~~~~~~~~~~~~~~~~~~
139 GUID of frontend instance.
140 Not perfect yet: if that instance is replaced, slaves have to be reconfigured.
141 Mandatory only if frontend-software-url is also provided.
142 XXX: should be complemented (or replaced) by more flexible and precise
143 criteria.
144
145 frontend-software-type (optional)
146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
147 Frontend software type as defined by the software relase at
148 frontend-software-url.
149
150 frontend-domain (optional)
151 ~~~~~~~~~~~~~~~~~~~~~~~~~~
152 Domain name frontend must recognise as belonging to this instance.
153
154 cluster
155 -------
156 This creates a massive ERP5 instance suited for high-demanding production
157 setups - which also have a lot of available resources (several machines,
158 several CPUs per machine, GBs of ram, several machines...).
159
160 For each available key in the outmost dict are described below.
161 Publishes a dict in which each entry is the URL to a balancer entry point
162 (apache listening socket), witht the same keys as zope-partition-dict.
163
164 'zodb-software-type' (str, optional)
165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166 Storage mechanism to use. To know the list of supported values, see all keys in
167 instance.cfg.in's section [switch-softwaretype] which start with "zodb-".
168 Defaults to 'zeo'.
169
170 'zodb-tcpv4-port' (int, optional)
171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172 Base TCPv4 port for ZODB provider, if applicable (depends on chosen
173 software-type).
174 Defaults to 2100.
175
176 'zodb-dict' (dict, optional)
177 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178 Describes ZODBs to create and use in the instance. At least one entry is
179 required to achieve anything sensible with the instance.
180 key (str)
181   Zope internal name for this ZODB. Used to tell mountpoints apart in the ZMI
182   when populating them.
183 value (dict)
184   key (str)
185     Possible keys and associated value types:
186     'storage-family' (str, optional)
187       Storage family. All zodbs requested with the same value are provided
188       by the same service (ex: same ZEO process). Might not be supported by
189       all zodb-software-type, silently ignored if so (ie, each ZODB gets its
190       own family).
191       Defaults to 'default'.
192     'mount-point' (str, optional)
193       Storage mount point.
194       Defaults to '/'.
195     'cache-size' (int, optional)
196       Storage ZODB cache size (aka 'Connection cache'), in objects. No value
197       is specified when negative is provided (ie, uses ZODB's default).
198       Defaults to -1.
199     'storage-dict' (dict, optional)
200       Storage-type-specific parameters. For example, it can be used to tell where
201       a ZEO filestorage database is located.
202       When zodb-software-type is 'zeo', the following keys are supported:
203       'path' (string, optional)
204         FileStorage file path. Occurrences of '%(zodb)s' are replaced with the
205         path to partition's srv/zodb directory.
206         Defaults to '%(zodb)s/', Zope's internal name for this ZODB, and '.fs'.
207       'client' (dict, optional)
208         Client(=Zope)-side settings. 'server' and 'storage' keys will be
209         overwritten. Keys and values are expected to be strings, and map
210         directly to options in the resulting <zeoclient> section.
211         Defaults to {}.
212
213 'tidstorage-dict' (dict, optional)
214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215 Backup parameters for tidstorage-related backup scripts.
216 TIDStorage is not deployed if not provided.
217 key (str)
218   Possible keys and associated value types:
219   'zodb-dict' (dict, optional)
220     key (str)
221       (same as zodb-dict)
222     value (str, optional)
223       Path to store backups of this zodb into. Occurrences of '%(backup)s' are
224       replaced with the path to partition's srv/backup/zodb directory.
225     Defaults to {}.
226     If an item is missing compared to zodb-dict, value defaults to
227     '%(backup)s/' + key.
228   'timestamp-path' (str, optional)
229     Path to backup timestamp file.
230     Occurrences of '%(backup)s' are replaced with the path to partition's
231     srv/backup/tidstorage directory.
232     Defaults to '%(backup)s/repozo_tidstorage_timestamp.log'.
233
234 'zope-partition-dict' (dict, optional)
235 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236 key (str)
237   Instance name.
238 value (dict)
239   Possible keys and associated value types:
240   'family' (str, optional)
241     The family this partition is part of. For example: 'public', 'admin',
242     'backoffice', 'web-service'... Each family gets its own frontend
243     (=client-facing ip & port). It has no special meaning as far as
244     buildout is concerned.
245     Defaults to 'default'.
246   'instance-count' (int, optional)
247     The number of Zopes to setup on this partition.
248     Defaults to 1.
249   'thread-amount' (int, optional)
250     The number of worker threads for each created Zope process.
251     Defaults to 1.
252   'timerserver-interval' (int, optional)
253     The timerserver tick perdiod. 0 to disable timerserver.
254     Defaults to 5.
255   'computer-guid' (string, optional)
256     Computer on which partition should be allocated.
257     Defauts to the same computer as the one this .cfg is executed in.
258   'longrequest-logger-interval' (int, optional)
259     The period, in seconds, with which LongRequestLogger polls worker thread
260     stack traces. -1 to disable.
261     Defaults to -1.
262   'longrequest-logger-timeout' (int, optional)
263     The transaction duration after which LongRequestLogger will start logging
264     its stack trace, in seconds. Ignored if longrequest-logger-interval is -1.
265     Defaults to 1.
266   'port-base' (int, optional)
267     Start allocating ports at this value. Useful if one needs to make several
268     partitions share the same port range (ie, several partitions bound to a
269     single address).
270     Defaults to 2200.
271
272 'haproxy-maxconn' (int, optional)
273 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
274 The number of connections haproxy accepts for a given backend.
275 See haproxy's "server maxconn" setting.
276 Defaults to 1 (correct for single-worker-threaded zopes).
277
278 'haproxy-tcpv4-port' (int, optional)
279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280 Base TCPv4 port for load-balancer (haproxy + backend apache).
281 Defaults to 2150.
282
283 'haproxy-server-check-path' (str, optional)
284 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285 The path haproxy accesses on a each backend to test their responsiveness.
286 Occurrences of '%(site-id)s' are replaced with site-id value (see below).
287 Defaults to '/'.
288
289 'apache-backend-path' (str, optional)
290 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
291 Used as a rewriterule to strip components from site's URL.
292 Occurrences of '%(site-id)s' are replaced with site-id value (see below).
293 XXX: You may want to avoid using this when also requesting a frontend apache.
294 Defaults to '/' (ie, nothing is stripped).
295
296 'apache-access-control-string' (str, optional)
297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
298 The list of hosts apache accepts connections from.
299 Defaults to 'all'.
300
301 'apache-ssl-authentication' (booleanish, optional)
302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
303 Controls certificate-based authentication.
304 Defaults to '0' (disabled).
305
306 'site-id' (str, optional)
307 ~~~~~~~~~~~~~~~~~~~~~~~~~
308 Site object's id. Defaults to 'erp5'.
309
310 'ca' (dict, optional)
311 ~~~~~~~~~~~~~~~~~~~~~
312 Certificate autority parameters.
313 Possible keys and associated value types:
314 'country-code' (str, optional)
315   ISO 3166-1 alpha-2 country code. Defaults to 'ZZ'.
316 'email' (str, optional)
317   E-mail address. Defaults to 'nobody@example.com'
318 'state' (str, optional)
319   State name. Defaults to 'Dummy State'.
320 'city' (str, optional)
321   City name. Default to 'Dummy City'.
322 'company' (str, optional)
323   Company name. Defaults to 'Dummy Company'.
324
325 'mariadb-computer-guid' (str, optional)
326 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
327 Computer GUID identifying the partition mariadb is to be requested on.
328 Defaults to "cluster" software type's partition's effective computer GUID.
329
330 'cloudooo-tcpv4-port' (int, optional)
331 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
332 Base TCPv4 port for cloudooo.
333 Defaults to 2020.
334
335 'cloudooo-computer-guid' (str, optional)
336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
337 Computer GUID identifying the partition cloudooo is to be requested on.
338 Defaults to "cluster" software type's partition's effective computer GUID.
339
340 'memcached-size' (int, optional)
341 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
342 Megabytes of ram to allocate for volatile memcached use.
343 Defaults to 64.
344 Negative/zero values cause undefined behaviour which may change in the future.
345
346 'memcached-tcpv4-port'
347 ~~~~~~~~~~~~~~~~~~~~~~
348 Base TCPv4 port for volatile memcached.
349 Defaults to 2010.
350
351 'memcached-computer-guid' (str, optional)
352 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
353 Computer GUID identifying the partition memcached is to be requested on.
354 Defaults to "cluster" software type's partition's effective computer GUID.
355
356 'kumofs-tcpv4-port'
357 ~~~~~~~~~~~~~~~~~~~
358 Base TCPv4 port for persistent memcached.
359 Defaults to 2000.
360
361 'kumofs-computer-guid' (str, optional)
362 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
363 Computer GUID identifying the partition kumofs is to be requested on.
364 Defaults to "cluster" software type's partition's effective computer GUID.
365
366 'zodb-computer-guid' (str, optional)
367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
368 Computer GUID identifying the partition ZODB server is to be requested on.
369 Defaults to "cluster" software type's partition's effective computer GUID.
370
371 'balancer-computer-guid' (str, optional)
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373 Computer GUID identifying the partition balander (haproxy, apache, some HTTP
374 cache) is to be requested on.
375 Defaults to "cluster" software type's partition's effective computer GUID.
376
377 'font-url-list' (list of strings, optional)
378 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
379 List of extra fonts URLs to be used by cloudooo.
380 Defaults to [].
381
382 'bt5' (str, optional)
383 ~~~~~~~~~~~~~~~~~~~~~
384 XXX: what is this ?
385 Defaults to 'erp5_full_text_myisam_catalog \
386 erp5_configurator_standard \
387 erp5_configurator_maxma_demo \
388 erp5_configurator_ung \
389 erp5_configurator_run_my_doc'.
390
391 'bt5-repository-url' (str, optional)
392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
393 XXX: what is this ?
394 Defaults to SR's buildout['local-bt5-repository']['list'].
395
396 'smtp-url' (str, optional)
397 ~~~~~~~~~~~~~~~~~~~~~~~~~~
398 XXX: what is this ?
399 Defaults to 'smtp://localhost:25/'.
400
401 'timezone' (str, optional)
402 ~~~~~~~~~~~~~~~~~~~~~~~~~~
403 Timezone to put processes in (default timezone for DateTime instances).
404 Defaults to 'Europe/Paris'.
405
406 'frontend-software-url' (str, optional)
407 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
408 Frontend's software url.
409 Defaults to ''.
410 If non-empty, the following options are used (otherwise, they are all
411 optional and ignored):
412
413 'frontend-software-type' (str, optional)
414 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
415 Frontend's software type.
416 Defaults to 'RootSoftwareInstance'
417
418 'frontend-instance-guid' (str, mandatory)
419 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
420 Instance GUID identifying the partition frontend is on.
421
422 'frontend-domain' (str, optional)
423 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
424 The domain name used to access this ERP5 cluster, ignored if empty.
425 Defaults to ''.
426
427 For a better description of these parameters, see a frontend software
428 release documentation.
429