Skip to content

Commit

Permalink
fix: update solo readme with examples (#725)
Browse files Browse the repository at this point in the history 
Signed-off-by: Lenin Mehedy <[email protected]>
  • Loading branch information
@leninmehedy
leninmehedy authored Feb 1, 2024
1 parent d970796 commit dd8bbd7
Show file tree
Hide file tree
Showing 4 changed files with 132 additions and 71 deletions.
28 changes: 28 additions & 0 deletions solo/CONTRIBUTE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Contribute

Below we describe how you can set up local environment and contribute to `solo`.

## Developer instructions

* Clone the repo
* In order to support ES6 modules with `jest`, set an env
variable `export NODE_OPTIONS=--experimental-vm-modules >> ~/.zshrc`
* If you are using Intellij and would like to use debugger tools, you will need to
enable `--experimental-vm-modules` for `Jest`.
* `Run->Edit Configurations->Edit Configuration Templates->Jest` and then set `--experimental-vm-modules`
in `Node Options`.
* Run `npm i` to install the required packages
* Run `npm link` to install `solo` as the CLI
* Note: you need to do it once. If `solo` already exists in your path, you will need to remove it first.
* Alternative way would be to run `npm run solo -- <COMMAND> <ARGS>`
* Run `npm test` or `npm run test` to run the unit tests
* Run `solo` to access the CLI.
* Note that debug logs are stored at `$HOME/.solo/logs/solo.log`. So you may use `tail -f $HOME/.solo/logs/solo.log | jq
` in a separate terminal to keep an eye on the logs.
* Before making a commit run `npm run format`

## E2E tests

* In order to run E2E test, we need to set up cluster and install the chart.
* Run `./test/e2e/setup-e2e.sh`
* Run `npm run test-e2e`
171 changes: 102 additions & 69 deletions solo/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,107 +7,140 @@ An opinionated CLI tool to deploy and manage private Hedera Networks.
* Node(^18.19.0)
* Helm(^3.14.0)
* Kubectl(^1.28.2)
* Helpful tools (Optional):
* [`k9s`](https://k9scli.io/)
* [`kubectx`](https://github.com/ahmetb/kubectx)

## Install
## Setup

* Install [Node](https://nodejs.org/en/download). You may also use [nvm](https://github.com/nvm-sh/nvm) to manage different Node versions locally
* Install [kubectl](https://kubernetes.io/docs/tasks/tools/)
* Install [helm](https://helm.sh/docs/intro/install/)
* Useful tools (Optional)
* Install [kind](https://kind.sigs.k8s.io/)
* Install [k9s](https://k9scli.io/)
* Install [kubectx](https://github.com/ahmetb/kubectx)

## Install Solo

* Run `npm install -g @hashgraph/solo`

* Ensure you have a valid kubernetes context, cluster and namespace. You may use `kind` and `kubectl` CLIs to create
cluster and namespace as below:
## Setup Kubernetes cluster

* If you don't already have a cluster, you may use [kind](https://kind.sigs.k8s.io/) and
[kubectl](https://kubernetes.io/docs/tasks/tools/) to create a cluster and namespace as below:

```
export SOLO_NAMESPACE=solo # use a namespace that suits you
kind create cluster
export SOLO_CLUSTER_NAME=solo
export SOLO_NAMESPACE=solo
kind create cluster -n "${SOLO_CLUSTER_NAME}"
kubectl create ns "${SOLO_NAMESPACE}"
```

* Run `solo` from a terminal, It may show usage options as shown below:
## Generate Node Keys

### Standard keys (.pem file)

These keys are supported by Hedera platform >=`0.47.0-alpha.0`.
You may run `solo node keys --gossip-keys --tls-keys --key-format pem -i node0,node1,node2` command to generate the required node keys.

### Legacy keys (.pfx file)

All Hedera platform versions support the legacy `.pfx` formatted key files.

Unfortunately `solo` is not able to generate legacy `PFX` formatted keys. However, if `curl`, `keytool` and `openssl`
are installed, you may run the following command to generate the pfx formatted gossip keys in the default
cache directory (`$HOME/.solo/cache/keys`):

```
❯ solo
# Option - 1: Generate keys for default node IDs: node0,node1,node2
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/hashgraph/full-stack-testing/main/solo/test/scripts/gen-legacy-keys.sh)"
# Option - 2: Generate keys for custom node IDs
curl https://raw.githubusercontent.com/hashgraph/full-stack-testing/main/solo/test/scripts/gen-legacy-keys.sh -o gen-legacy-keys.sh
chmod +x gen-legacy-keys.sh
./gen-legacy-keys.sh alice,bob,carol
```

******************************* Solo *********************************************
Version : 0.18.0
Kubernetes Context : kind-kind
Kubernetes Cluster : kind-kind
Kubernetes Namespace : undefined
**********************************************************************************
Usage:
solo <command> [options]
# Examples

Commands:
solo init Initialize local environment
solo cluster Manage fullstack testing cluster
solo network Manage fullstack testing network deployment
solo node Manage Hedera platform node in fullstack testing network
solo relay Manage JSON RPC relays in fullstack testing network
## Deploy a private Hedera network (version `0.42.5`)

Options:
--dev Enable developer mode [boolean] [default: false]
-h, --help Show help [boolean]
-v, --version Show version number [boolean]
* Initialize `solo`

Select a command
```
solo init -t 0.42.5 # cache args for subsequent commands
```

* Deploy private Hedera network in your existing cluster and namespace
* Generate `pfx` node keys for default node IDs: node0,node1,node2 (You will need `curl`, `keytool` and `openssl`)

```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/hashgraph/full-stack-testing/main/solo/test/scripts/gen-legacy-keys.sh)"
```

* Setup cluster with shared components in the `default` namespace

```
solo cluster setup -n default
```

In a separate terminal, you may run `k9s` to view the pod status.

* Deploy helm chart with Hedera network components

```
solo network deploy -n "${SOLO_NAMESPACE}"
```

* Setup node with Hedera platform. It may take a while (~10 minutes depending on your internet speed) to download
various docker images and get the pods started.

```
solo init -n "${SOLO_NAMESPACE}" # cache args for subsequent commands
solo cluster setup
solo network deploy
solo node setup
```

* Start the nodes

```
solo node start
```

## Develop
## Deploy a private Hedera network (version `0.47.0-alpha.0`)

* In order to support ES6 modules with `jest`, set an env
variable `export NODE_OPTIONS=--experimental-vm-modules >> ~/.zshrc`
* If you are using Intellij and would like to use debugger tools, you will need to
enable `--experimental-vm-modules` for `Jest`.
* `Run->Edit Configurations->Edit Configuration Templates->Jest` and then set `--experimental-vm-modules`
in `Node Options`.
* Run `npm i` to install the required packages
* Run `npm link` to install `solo` as the CLI
* Note: you need to do it once. If `solo` already exists in your path, you will need to remove it first.
* Alternative way would be to run `npm run solo -- <COMMAND> <ARGS>`
* Run `npm test` or `npm run test` to run the unit tests
* Run `solo` to access the CLI as shown above.
* Note that debug logs are stored at `$HOME/.solo/logs/solo.log`. So you may use `tail -f $HOME/.solo/logs/solo.log | jq
` in a separate terminal to keep an eye on the logs.
* Before making a commit run `npm run format`
* Initialize `solo`

## E2E tests
```
solo init -t 0.47.0-alpha.0 # cache args for subsequent commands
```

* Generate `pem` node keys for default node IDs: node0,node1,node2

* In order to run E2E test, we need to set up cluster and install the chart.
* Run `./test/e2e/setup-e2e.sh`
* Run `npm run test-e2e`
```
solo node keys --gossip-keys --tls-keys --key-format pem -i node0,node1,node2
```

## Node Keys
* Setup cluster with shared components in the `default` namespace

### Standard keys (.pem file)
```
solo cluster setup -n default
```

`solo` is able to generate standard `PEM` formatted keys for nodes. You may
run `solo node keys --gossip-keys --tls-keys`
command to generate the required keys.
In a separate terminal, you may run `k9s` to view the pod status.

### Legacy keys (.pfx file)
* Deploy helm chart with Hedera network components

`solo` is not able to generate legacy `PFX` formatted gossip keys. However, you may use the
script [test/scripts/gen-legacy-keys](test/scripts/gen-legacy-keys.sh).
For example, if `curl`, `keytool` and `openssl` are installed on the machine, you may run the following command to
generate the pfx formatted gossip keys in the default
cache directory (`$HOME/.solo/cache/keys`):
```
solo network deploy -n "${SOLO_NAMESPACE}"
```

* Setup node with Hedera platform. It may take a while (~10 minutes depending on your internet speed) to download
various docker images and get the pods started.

```
# Option - 1: Generate keys for default node IDs: node0,node1,node2,node3
/bin/bash -c "${curl -fsSL https://raw.githubusercontent.com/hashgraph/solo/main/test/scripts/gen-legacy-keys.sh)"
solo node setup
# Option - 2: Generate keys for custom node IDs
curl -o gen-legacy-keys.sh https://raw.githubusercontent.com/hashgraph/solo/main/test/scripts/gen-legacy-keys.sh
./legacy-key-generation.sh alice,bob,carol
```

* Start the nodes

```
solo node start
```
2 changes: 1 addition & 1 deletion solo/test/scripts/gen-legacy-keys.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
#

keysDir="${HOME}/.solo/cache/keys"
ids="node0,node1,node2,node3"
ids="node0,node1,node2"
validity=36524 # number of days

if [ "$#" -gt 0 ]; then
Expand Down
2 changes: 1 addition & 1 deletion solo/test/scripts/gen-standard-keys.sh
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/bin/bash

keysDir="${HOME}/.solo/cache/keys"
ids="node0,node1,node2,node3"
ids="node0,node1,node2"
validity=36524 # number of days
generate_pfx=false

Expand Down

0 comments on commit dd8bbd7

Please sign in to comment.