Cardano SL Launcher
cardano-launcher is a tool for launching Cardano SL. It actually runs the whole Cardano SL system (i.e. a node, a wallet) and handles updates.
You can run it with
--help flag to see this usage info:
$ cardano-launcher --help Usage: cardano-launcher --node PATH [-n ARG] [--node-log PATH] [--wallet PATH] [-w ARG] --updater PATH [-u ARG] [--update-archive PATH] --node-timeout SEC [--report-server URL] Tool to launch Cardano SL Available options: -h,--help Show this help text --node PATH Path to the node executable -n ARG An argument to be passed to the node --node-log PATH Path to the log where node's output will be dumped --wallet PATH Path to the wallet executable -w ARG An argument to be passed to the wallet --updater PATH Path to the updater executable -u ARG An argument to be passed to the updater --update-archive PATH Path to the update archive (will be passed to the updater) --node-timeout SEC How much to wait for the node to exit before killing it --report-server URL Where to send logs in case of failure
For example (run via
$ stack exec cardano-launcher -- \ --node /tmp/blah-v000/node \ --node-timeout 5 \ --updater /bin/cardano-updater -u dir -u /tmp/n \ --update-archive /tmp/cardano-update.tar
cardano-node is a node application.
cardano-updater is a separate application for the node updates (see an explanation below). Arguments
--update-archive will be passed to the updater. Please note that
cardano-updater is not the only allowed updater, so arguments
--update-archive may appear unnecessary.
Node timeout is explained below.
There are two work scenarios for
cardano-launcher: desktop and server. If you provide a path to the wallet (e.g. Daedalus) using
--wallet argument during start,
cardano-node will run in desktop scenario, otherwise it will run in server one.
After the start, there are 2 steps:
- Running an updater.
- Running a node.
Updater’s work is explained below.
We can write log info in the log file before quitting. To do it, we must provide two additional arguments during launcher’s start,
--node-log. The first argument defines an URL of the report server, the second one defines a path to the log file. We asynchronously send log info to the report server via
POST-request. Please note that the file from the
--node-log argument must exist.
After the start, there are 3 steps:
- Running an updater.
- Running a node.
- Running a wallet.
For steps 1 and 2, see Server Scenario above.
The wallet is spawning as a separate process too.
After that, we wait until node or wallet stops. When it stopps, we check it:
- If the node exits, we write a log (see Server Scenario above for explanations) and wait for a wallet death.
- If the wallet exits, we check the exit code, and if it equals
20, we kill a node and restart the launcher in the desktop scenario. Please note that killing a node isn’t executed immediately; a node is killed after some timeout, and its value is obtained from the
--node-timeoutargument mentioned above.
- If the wallet exits and exit code isn’t equal to
20, we kill a node immediately.
Another important thing
cardano-launcher does is updating a node. The first step in both scenarios is running an updater. Please note that if the executable file in the
--updater argument doesn’t exist, updating will be skipped.
The core idea is very simple. The node update is a special
.tar-archive, it represents the difference between the old (current) version of the node and a new version of it. A path to this archive is obtained via
--update-archive argument. So,
cardano-updater applies this archive to the node, and after restart a new version of the node can be used.
Please note that when we run
cardano-launcher in desktop scenario, a wallet’s user is able to see that an update is ready, and there are two situations possible.
If a user agrees to apply this update, the wallet exits immediately with an exit code
20. In this case, as described above, launcher restarts a node and the update is applied.
If a user doesn’t agree to apply this update, the wallet continues working. But when it is restarted (sooner or later), that update will be applied.
Important: the updater runs synchronously, we start it and then wait for it to finish. If the updater finishes its work successfully,
.tar-archive will be deleted.