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 Amount of time 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 updater allowed, 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.
Log info can be written to 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.
As the process starts, 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.
After that, we wait until node or wallet stops. When it stops, we check it:
- If the node exits, we write a log (see Server Scenario above for explanations) and wait for the wallet death.
- If the wallet exits, we check the exit code, and if it equals
20, we kill the node and restart the launcher in the desktop scenario. Please note that killing the node isn’t executed immediately; the 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 the 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 the 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, the
.tar-archive is deleted.