configuration and usage

Broker.md

@@ -8,4 +8,71 @@ Broker is essential part of ReCodEx solution which maintaines almost all communi
 ## Installation
 
 ## Configuration and usage
-Following text describes how to set up and run **broker** program. It's supposed to have required binaries installed. For instructions see [[Installation|Broker#installation]] section. Also, using systemd is recommended for best user experience, but it's not required. Almost all modern Linux distributions are using systemd now.
+Following text describes how to set up and run **broker** program. It's supposed to have required binaries installed. For instructions see [[Installation|Broker#installation]] section. Also, using systemd is recommended for best user experience, but it's not required. Almost all modern Linux distributions are using systemd now.
+
+Installation of **broker** program does following step to your computer:
+- create config file `/etc/recodex/brokerr/config.yml`
+- create _systemd_ unit file `/etc/systemd/system/recodex-broker.service`
+- put main binary to `/usr/bin/recodex-broker`
+- create system user and group `recodex` with nologin shell (if not existing)
+- create log directory `/var/log/recodex`
+- set ownership of config (`/etc/recodex`) and log (`/var/log/recodex`) directories to `recodex` user and group
+
+### Default broker configuration
+
+#### Configuration items
+
+Mandatory items are bold, optional italic.
+
+- _clients_ - specifies address and port to bind for clients (eq. frontends)
+    - _address_ - hostname or IP address as string (`*` for any)
+    - _port_ - desired port
+- _workers_ - specifies address and port to bind for workers
+    - _address_ - hostname or IP address as string (`*` for any)
+    - _port_ - desired port
+- _monitor_ - settings of monitor service connection
+    - _address_ - IP address of running monitor service
+    - _port_ - desired port
+- _notifier_ - details of connection which is used in case of errors and good to know states
+    - _address_ - address where frontend API runs
+    - _port_ - desired port
+    - _username_ - username which can be used for HTTP authentication
+    - _password_ - password which can be used for HTTP authentication
+- _logger_ - settings of logging capabilities
+    - _file_ - path to the logging file with name without suffix. `/var/log/recodex/broker` item will produce `broker.log`, `broker.1.log`, ...
+    - _level_ - level of logging, one of `off`, `emerg`, `alert`, `critical`, `err`, `warn`, `notice`, `info` and `debug`
+    - _max-size_ - maximal size of log file before rotating
+    - _rotations_ - number of rotation kept
+
+#### Example config file
+
+```{.yml}
+# Address and port for clients (frontend)
+clients:
+    address: "*"
+    port: 9658  # Address and port for workers
+workers:
+    address: "*"
+    port: 9657
+monitor:
+    address: "127.0.0.1"
+    port: 7894
+notifier:
+    address: "127.0.0.1"
+    port: 8080
+    username: ""
+    password: ""
+logger:
+    file: "/var/log/recodex/broker"  # w/o suffix - actual names will be broker.log, broker.1.log, ...
+    level: "debug"  # level of logging
+    max-size: 1048576  # 1 MB; max size of file before log rotation
+    rotations: 3  # number of rotations kept
+```
+
+### Running broker
+
+Running broker is very similar to the worker setup. There is only one broker per whole ReCodEx solution, so there is no need for systemd templates. So running broker is just:
+```
+# systemctl start recodex-broker.service
+```
+For more info please refer to worker part of this page or systemd documentation.