From 66f20ae4dae7c1112936f10d4dadcfbb3a3b8b64 Mon Sep 17 00:00:00 2001 From: Emmanuel Ameh Date: Thu, 6 Jun 2024 09:08:23 +0100 Subject: [PATCH] Review Getting started section (#1460) --- * [ ] CHANGELOG updated or not needed * [ ] Documentation updated or not needed * [ ] Haddocks updated or not needed * [ ] No new TODOs introduced or explained herafter --- docs/docs/getting-started.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 5d01455eb30..735baddad4b 100644 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -1,14 +1,13 @@ # Getting started +To get started quickly, we'll walk you through the standard demo setup, which includes: -To get started quickly, let's walk you through our standard demo setup consisting of +* A cluster of three `hydra-nodes`, each directly connected to the others and configured with one of three Hydra credentials: `Alice`, `Bob`, or `Carol` +* A single `cardano-node` producing blocks used as a (very fast) local `devnet` +* The `hydra-tui` example for clients to interact with the individual `hydra-node`. -- a cluster of three `hydra-node`, directly connected to each other, each having access to one of three Hydra credentials `alice`, `bob`, or `carol`; -- a single `cardano-node` producing blocks used as a (very fast) local `devnet`; -- the `hydra-tui` example clients to interact with the individual Hydra nodes. +This tutorial uses [Docker](https://www.docker.com/get-started) to install the nodes, so ensure Docker is installed. If you want to explore alternative ways of running the tools, see the [variant tutorial](./getting-started-without-docker.md) or the [testnet tutorial](./tutorial/index.md), which uses pre-built binaries. The documentation pages on [installation](./installation) and [configuration](./configuration) provide more details. -This tutorial will be using [Docker](https://www.docker.com/get-started) to install and the nodes, so make sure to have it installed. If you want to explore alternative ways of running the tools, see this [tutorial variant](./getting-started-without-docker.md) or the [testnet tutorial](./tutorial/index.md) does use pre-built binaries, while documentation pages on [installation](./installation) and [configuration](./configuration) provide more details. - -Also, the `hydra-tui` does use the HTTP/WebSocket API provided by the `hydra-node` behind the scenes. The [testnet tutorial](./tutorial/index.md) will show how to use this API using low-level commands or see the [API reference](/api-reference). +Additionally, the `hydra-tui` uses the HTTP/WebSocket API provided by the `hydra-node` behind the scenes. The [testnet tutorial](./tutorial/index.md) will show how to use this API using low-level commands, or you can see the [API reference](https://hydra.family/head-protocol/unstable/api-reference) for more details.
Video demonstration (a bit dated) @@ -23,7 +22,7 @@ These instructions have been tested only on Linux environments (Ubuntu, NixOS). ## Preparation -All commands below are written as if executed from the `demo` folder in the project repository, so make sure to clone the repository, switch into the demo folder and pull the latest docker images: +All commands below are written as if executed from the `demo` folder in the project repository. Ensure you clone the repository, switch into the `demo` folder, and pull the latest Docker images: ```shell git clone git@github.com:input-output-hk/hydra.git @@ -32,24 +31,25 @@ docker compose pull ``` :::info Shortcut -For convenience, we also provide a script `./run-docker.sh`, which combines all following steps. It also performs a few sanity checks to avoid tripping ourselves. +For convenience, we provide a script `./run-docker.sh`, which combines all the following steps. It also performs a few sanity checks to prevent potential issues. ::: ## Set up the devnet -Next, we can run prepare the devnet configuration to bootstrap a local Cardano blockchain. Note that, we use a simple variant of Cardano that requires no stake pools whatsoever. +Next, prepare the devnet configuration to bootstrap a local Cardano blockchain. +**Note** that we use a simplified variant of Cardano that does not require any stake pools. ```shell ./prepare-devnet.sh ``` -We can now bring the Cardano node up with: +Bring the Cardano node up with: ```shell docker compose up -d cardano-node ``` -You can verify that the devnet is up-and-running by checking the logs with: +Verify that the devnet is up-and-running by checking the logs with: ```shell docker compose logs cardano-node -f ``` @@ -57,10 +57,10 @@ docker compose logs cardano-node -f You should see traces containing `TraceAdoptedBlock`, which means that the devnet is producing blocks .. nice! :::info -Don't wait too long between these two commands. If you get `TraceNoLedgerView` errors from the Cardano node, the genesis start time is too far in the past and you need to update them by running `prepare-devnet.sh` again. +Do not wait too long between these two commands. If you get `TraceNoLedgerView` errors from the Cardano node, the genesis start time is too far in the past, and you need to update them by running `prepare-devnet.sh` again. ::: -Next we need to give Alice, Bob, and Carol some UTxOs to commit and some ADA to pay fees. We include a script `seed-devnet.sh` that uses the `cardano-cli` in the already running `cardano-node` container to do that: +Next, we need to give Alice, Bob, and Carol some UTXOs for committing and ada for paying fees. To do this, use the `seed-devnet.sh` script, which uses the `cardano-cli` within the already running `cardano-node` container: ```shell ./seed-devnet.sh @@ -68,13 +68,13 @@ Next we need to give Alice, Bob, and Carol some UTxOs to commit and some ADA to ## Start Hydra nodes -Finally, now that the on-chain preparations are done, we can bring the Hydra network (all three nodes for Alice, Bob and Carol) up by running: +Finally, now that the on-chain preparations are done, we can bring the Hydra network (all three nodes for Alice, Bob, and Carol) up by running: ```shell docker compose up -d hydra-node-{1,2,3} ``` -Using compose, you can start the demo Terminal-based User Interface (a.k.a. `hydra-tui`) to interact with Hydra nodes. There are 3 preconfigured TUI services in the compose definition: `hydra-tui-1`, `hydra-tui-2`, and `hydra-tui-3`. To connect to the first Hydra node in a terminal, run the following command: +Using `compose`, you can start the demo Terminal-based User Interface (`hydra-tui`) to interact with Hydra nodes. There are three preconfigured TUI services in the `compose` definition: `hydra-tui-1`, `hydra-tui-2`, and `hydra-tui-3`. To connect to the first Hydra node in a terminal, run the following command: ```shell docker compose run hydra-tui-1 @@ -84,6 +84,6 @@ This will start a full-blown terminal interface loaded with signing keys corresp ## Use the head -Using the terminal interface of any node, you can now `[i]nit` the Hydra head and `[c]ommit` pre-distributed funds to it. Note that these steps are near instant as the devnet is producing blocks much faster than a public testnet or the mainnet. After committing from all nodes, the head will automatically open and you can also use the `hydra-tui` or the API to create new transactions and submit them to the Hydra head. +Using the terminal interface of any node, you can now `[i]nit` the Hydra head and `[c]ommit` pre-distributed funds to it. Note that these steps are near-instant as the devnet is producing blocks much faster than a public testnet or the mainnet. After committing from all nodes, the head will automatically open, and you can also use the `hydra-tui` or the API to create new transactions and submit them to the Hydra head. -![](./open-head.png) +![](./open-head.png) \ No newline at end of file