|
| 1 | +# Cluster |
| 2 | + |
| 3 | +## Getting Started |
| 4 | + |
| 5 | +This module provides an executable for starting a demo cluster of nodes. |
| 6 | +It is designed to remove all the overhead of setting up a configuration |
| 7 | +and an environment and to _just work_, out-of-the-box. Minor configuration |
| 8 | +adjustments are however possible via environment variables. |
| 9 | + |
| 10 | +``` |
| 11 | +$> stack exec -- cardano-sl-cluster-demo |
| 12 | +Cluster is starting (4 core(s), 1 relay(s), 1 edge(s))... |
| 13 | +...core0 has no health-check API. |
| 14 | +......system start: 1539179287 |
| 15 | +......address: 127.0.0.1:3000 |
| 16 | +......locked assets: - |
| 17 | +...core1 has no health-check API. |
| 18 | +......system start: 1539179287 |
| 19 | +......address: 127.0.0.1:3001 |
| 20 | +......locked assets: - |
| 21 | +...core2 has no health-check API. |
| 22 | +......system start: 1539179287 |
| 23 | +......address: 127.0.0.1:3002 |
| 24 | +......locked assets: - |
| 25 | +...core3 has no health-check API. |
| 26 | +......system start: 1539179287 |
| 27 | +......address: 127.0.0.1:3003 |
| 28 | +......locked assets: - |
| 29 | +...relay has no health-check API. |
| 30 | +......system start: 1539179287 |
| 31 | +......address: 127.0.0.1:3100 |
| 32 | +...wallet OK! |
| 33 | +......system start: 1539179287 |
| 34 | +......api address: 127.0.0.1:8090 |
| 35 | +......doc address: 127.0.0.1:8190 |
| 36 | +Cluster is (probably) ready! |
| 37 | +``` |
| 38 | + |
| 39 | + |
| 40 | +## Configuring Nodes |
| 41 | + |
| 42 | +_Almost anything_ from the normal CLI arguments of a node or a wallet node can be |
| 43 | +configured via an ENV variable using an `UPPER_SNAKE_CASE` naming, correctly |
| 44 | +prefixed with `DEMO_` with a few gotchas: |
| 45 | + |
| 46 | +- Flags need an explicit boolean value |
| 47 | + |
| 48 | +- There's no ENV vars mapping to (i.e. you can't configure): |
| 49 | + - `--db-path` |
| 50 | + - `--logger-config` |
| 51 | + - `--node-id` |
| 52 | + - `--tlsca` |
| 53 | + - `--tlscert` |
| 54 | + - `--tlskey` |
| 55 | + - `--topology` |
| 56 | + - `--wallet-db-path` |
| 57 | + - `--keyfile` |
| 58 | + Those variables actually corresponds to artifacts or location handled by the |
| 59 | + cluster library. Messing up with one of those can break the whole cluster. |
| 60 | + |
| 61 | +- There's an extra `LOG_SEVERITY` variable that can be set to `Debug`, `Info` |
| 62 | + and so forth to ajust logging severity for _all_ nodes. |
| 63 | + |
| 64 | +- There's an extra `STATE_DIR` variable used to provide the working directory |
| 65 | + for all nodes. See the [State Directory](#state-directory) section here-below. |
| 66 | + |
| 67 | +- There's an extra `SYSTEM_START_OFFSET` which can be used to tweak the system |
| 68 | + start offset such that nodes can all correctly boot. |
| 69 | + |
| 70 | +- When it make senses, variable values are automatically incremented by the |
| 71 | + node index. For instance, if you provide `LISTEN=127.0.0.1:3000`, then |
| 72 | + - core0 will receive "127.0.0.1:3000" |
| 73 | + - core1 will receive "127.0.0.1:3001" |
| 74 | + - core2 will receive "127.0.0.1:3002" |
| 75 | + - etc. |
| 76 | + |
| 77 | + This is the case for: |
| 78 | + - `--listen` |
| 79 | + - `--wallet-address` |
| 80 | + - `--wallet-doc-address` |
| 81 | + |
| 82 | +For instance, one can disable TLS client authentication doing: |
| 83 | + |
| 84 | +``` |
| 85 | +$> DEMO_NO_CLIENT_AUTH=True stack exec -- cardano-sl-wallet-new:demo |
| 86 | +``` |
| 87 | + |
| 88 | +### Relative FilePath |
| 89 | + |
| 90 | +One can provide relative filepath as values for ENV vars. They are computed from |
| 91 | +the root repository folder, so for instance, providing `./state-demo` will point |
| 92 | +to the directory `$(git rev-parse --show-toplevel)/state-demo`. |
| 93 | + |
| 94 | + |
| 95 | +### State Directory |
| 96 | + |
| 97 | +By default, each node receives a temporary state directory from the system; |
| 98 | +probably somewhere in `/tmp`. This location can always be overriden by |
| 99 | +providing an extra `DEMO_STATE_DIR` variable with a custom location. |
| 100 | + |
| 101 | +Note that, each default has been choosen in such way that they won't conflict |
| 102 | +if all nodes were to share the same state directory :) |
| 103 | + |
| 104 | +### Configuring Cluster |
| 105 | + |
| 106 | +The `cardano-sl-cluster-demo` is actually a full-blown CLI with default arguments. |
| 107 | + |
| 108 | +``` |
| 109 | +$> stack exec -- cardano-sl-cluster-demo --help |
| 110 | +cardano-sl-cluster-demo |
| 111 | +
|
| 112 | +Spawn a demo cluster of nodes running cardano-sl, ready-to-use |
| 113 | +
|
| 114 | +Usage: |
| 115 | + cardano-sl-cluster-demo [--no-genesis-wallets] [options] |
| 116 | + cardano-sl-cluster-demo --help |
| 117 | +
|
| 118 | +Options: |
| 119 | + --cores=INT Number of core nodes to start [default: 4] |
| 120 | + --relays=INT Number of relay nodes to start [default: 1] |
| 121 | + --edges=INT Number of edge nodes (wallet) to start [default: 1] |
| 122 | +``` |
| 123 | + |
| 124 | +So, the components of the cluster may be tweaked by providing arguments to the CLI. |
| 125 | +For instance, one could switch off the wallet node by doing: |
| 126 | + |
| 127 | +``` |
| 128 | +$> stack exec -- cardano-sl-cluster-demo --edges 0 |
| 129 | +``` |
| 130 | + |
| 131 | +## Known Issues |
| 132 | + |
| 133 | +The current logging implementation of _cardano-sl_ heavily relies on a global mutable state |
| 134 | +stored in a shared `MVar`. Since every node in `cardano-sl-cluster-demo` is spawned from a |
| 135 | +common parent thread, they all eventually end up sharing the same logging state. |
| 136 | + |
| 137 | +This result in a non-friendly behavior where, every logging handler get replaced by the one |
| 138 | +from the next node started by the cluster. So once started, every log entry gets logged _as-if_ |
| 139 | +they were logged by the last node started (with default parameters, the wallet node). |
| 140 | + |
| 141 | +This is why you won't find any log (apart from a couple of lines on start-up) inside log files, |
| 142 | +and duplicated lines in one of them (likely `wallet.log.pub`); fixing this is non-trivial. |
| 143 | + |
| 144 | + |
| 145 | +<p align="center"> |
| 146 | +（✿ ͡◕ ᴗ◕ )つ━━✫ ✧･ﾟ* <i>enjoy</i> *:･ﾟ✧*:･ﾟ❤ |
| 147 | +</p> |
0 commit comments