Merge pull request #842 from input-output-hk/jpraynaud/update-current-documentation-2023-03-31

Update current documentation

Author: jpraynaud

docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-aggregator.md

@@ -161,6 +161,81 @@ Run 'serve' command in release with a custom configuration via env vars
 GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) RUN_INTERVAL=60000 NETWORK=**YOUR_CARDANO_NETWORK** ./mithril-aggregator serve
 ```
 
+## Release build and run binary 'genesis' command
+
+Build in release with default configuration
+
+```bash
+make build
+```
+
+Display the help menu
+
+```bash
+./mithril-aggregator genesis --help
+```
+
+You should see
+
+```bash
+mithril-aggregator-genesis 
+Aggregator runs in Genesis tools mode
+USAGE:
+    mithril-aggregator genesis <SUBCOMMAND>
+OPTIONS:
+    -h, --help    Print help information
+SUBCOMMANDS:
+    bootstrap    Bootstrap a genesis certificate Test only usage
+    export       Export payload to sign with genesis secret key
+    help         Print this message or the help of the given subcommand(s)
+    import       Import payload signed with genesis secret key and create & import a genesis certificate
+```
+
+Run 'genesis bootstrap' command in release with default configuration, **only in test mode**.
+This allows the Mithril Aggregator node to bootstrap a `Genesis Certificate`. After this operation, the Mithril Aggregator will be able to produce new snapshots and certificates.
+
+```bash
+./mithril-aggregator genesis bootstrap
+```
+
+Or with a specific `Genesis Secret Key`, **only in test mode**.
+
+```bash
+./mithril-aggregator genesis bootstrap --genesis-secret-key **YOUR_SECRET_KEY*
+```
+
+Run 'genesis export' command in release with default configuration.
+This allows the Mithril Aggregator node to export the `Genesis Payload` that needs to be signed (and later reimported) of the `Genesis Certificate`. The signature of the `Genesis Payload` must be done manually with the owner of the `Genesis Secret Key`.
+
+```bash
+./mithril-aggregator genesis export
+```
+
+Or with a custom export path (to override the default value `./mithril-genesis-payload.txt`)
+
+```bash
+./mithril-aggregator genesis export --target-path **YOUR_TARGET_PATH**
+```
+
+Run 'genesis import' command in release with default configuration.
+This allows the Mithril Aggregator node to import the signed payload of the `Genesis Certificate` and create it in the store. After this operation, the Mithril Aggregator will be able to produce new snapshots and certificates.
+
+```bash
+./mithril-aggregator genesis import
+```
+
+Or with a custom export path (to override the default value `./mithril-genesis-signed-payload.txt`)
+
+```bash
+./mithril-aggregator genesis import --signed-payload-path **YOUR_SIGNED_PAYLOAD_PATH**
+```
+
+Run 'genesis import' command in release with a custom configuration via env vars
+
+```bash
+GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**) RUN_INTERVAL=60000 NETWORK=**YOUR_CARDANO_NETWORK** ./mithril-aggregator genesis import
+```
+
 ## Release build and run binary 'era' command
 
 Build in release with default configuration

docs/versioned_docs/version-maintained/manual/developer-docs/nodes/mithril-client.md

@@ -187,7 +187,57 @@ If you want to dig deeper, you can get access to several level of logs from the
 
 <CompiledBinaries />
 
-## Build and run Docker container
+## Run Docker container
+
+### Registry Image
+
+The list of available images on the registry is listed [here](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
+
+Prepare environment variables (values can be retrieved on the above **Mithril Networks** table)
+
+```bash
+export MITHRIL_IMAGE_ID=**YOUR_MITHRIL_IMAGE_ID**
+export NETWORK=**YOUR_CARDANO_NETWORK**
+export AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
+export GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**)
+export SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/snapshots | jq -r '.[0].digest')
+```
+
+Here is an example configuration for the `release-preprod` network and the `latest` stable Docker image
+
+```bash
+export MITHRIL_IMAGE_ID=latest
+export NETWORK=preprod
+export AGGREGATOR_ENDPOINT=https://aggregator.release-preprod.api.mithril.network/aggregator
+export GENESIS_VERIFICATION_KEY=$(wget -q -O - https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey)
+export SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/snapshots | jq -r '.[0].digest')
+```
+
+Then create a shell function for the Mithril Client
+
+```bash
+mithril_client () {
+  docker run --rm -e NETWORK=$NETWORK -e GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT --name='mithril-client' -v $(pwd):/app/data -u $(id -u) ghcr.io/input-output-hk/mithril-client:$MITHRIL_IMAGE_ID $@
+}
+```
+
+Now you can use the `mithril_client` function:
+
+```bash
+# 1- Help
+mithril_client help
+
+# 2- List snapshots
+mithril_client list
+
+# 3- Download latest snapshot
+mithril_client download $SNAPSHOT_DIGEST
+
+# 4- Restore latest snapshot
+mithril_client restore $SNAPSHOT_DIGEST
+```
+
+### Local Image
 
 Build a local Docker image
 

docs/versioned_docs/version-maintained/manual/getting-started/bootstrap-cardano-node.md

@@ -158,31 +158,69 @@ If you want to dig deeper, you can get access to several level of logs from the
 
 <CompiledBinaries />
 
+## Run Docker container
+
+The list of available images on the registry is listed [here](https://github.com/input-output-hk/mithril/pkgs/container/mithril-client)
+
+Prepare an environment variable with the selected Docker image
+
+```bash
+export MITHRIL_IMAGE_ID=**YOUR_MITHRIL_IMAGE_ID**
+```
+
+Here is an example configuration for the `latest` stable Docker image
+
+```bash
+export MITHRIL_IMAGE_ID=latest
+```
+
+Then create a shell function for the Mithril Client:
+```bash
+mithril_client () {
+  docker run --rm -e NETWORK=$NETWORK -e GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY -e AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT --name='mithril-client' -v $(pwd):/app/data -u $(id -u) ghcr.io/input-output-hk/mithril-client:$MITHRIL_IMAGE_ID $@
+}
+```
+
+Now you can use the `mithril_client` function:
+```bash
+# 1- Help
+mithril_client help
+
+# 2- List snapshots
+mithril_client list
+```
+
+:::tip
+
+In the following part of the document, you will need to replace the `./mithril-client` commands with `mithril_client` in order to use the above shell function.
+
+:::
+
 ## Bootstrap a Cardano node from a testnet Mithril snapshot
 
 ### Step 1: Prepare some useful variables
 
 ```bash
 # Cardano network
-NETWORK=**YOUR_CARDANO_NETWORK**
+export NETWORK=**YOUR_CARDANO_NETWORK**
 
 # Aggregator API endpoint URL
-AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
+export AGGREGATOR_ENDPOINT=**YOUR_AGGREGATOR_ENDPOINT**
 
 # Genesis verification key
-GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**)
+export GENESIS_VERIFICATION_KEY=$(wget -q -O - **YOUR_GENESIS_VERIFICATION_KEY**)
 
 # Digest of the latest produced snapshot for convenience of the demo
 # You can also modify this variable and set it to the value of the digest of a snapshot that you can retrieve at step 2
-SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/snapshots | jq -r '.[0].digest')
+export SNAPSHOT_DIGEST=$(curl -s $AGGREGATOR_ENDPOINT/snapshots | jq -r '.[0].digest')
 ```
 
 ### Step 2: Select A Snapshot
 
 List the available snapshots with which you can bootstrap a Cardano node
 
 ```bash
-GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client list
+./mithril-client list
 ```
 
 You will see a list of snapshots
@@ -208,7 +246,7 @@ You will see a list of snapshots
 Get some more details from a specific snapshot (Optional)
 
 ```bash
-GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client show $SNAPSHOT_DIGEST
+./mithril-client show $SNAPSHOT_DIGEST
 ```
 
 You will see more information about a snapshot
@@ -233,7 +271,7 @@ You will see more information about a snapshot
 Download the selected snapshot from the remote location to your remote location
 
 ```bash
-GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client download $SNAPSHOT_DIGEST
+./mithril-client download $SNAPSHOT_DIGEST
 ```
 
 You will see that the selected snapshot archive has been downloaded locally
@@ -249,7 +287,7 @@ to /home/mithril/data/testnet/cd587611b5ff2445c714bef083d9455ed3e42e9304ae0ad38b
 Verify the Certificate of the snapshot and unpack its content in order to feed the Cardano node database
 
 ```bash
-GENESIS_VERIFICATION_KEY=$GENESIS_VERIFICATION_KEY NETWORK=$NETWORK AGGREGATOR_ENDPOINT=$AGGREGATOR_ENDPOINT ./mithril-client restore $SNAPSHOT_DIGEST
+./mithril-client restore $SNAPSHOT_DIGEST
 ```
 
 You will see that the snapshot archive is unpacked and that the associated certificate is valid