Skip to content

Commit

Permalink
Merge pull request #239 from ava-labs/readme-fixes-b
Browse files Browse the repository at this point in the history 
README fixes per Markdownlint
  • Loading branch information
@cgcardona
cgcardona authored Aug 17, 2022
2 parents 970835a + 92e1b42 commit f5f0419
Showing 1 changed file with 93 additions and 98 deletions.
191 changes: 93 additions & 98 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@

## Note

This tool is under heavy development and the documentation/code snippers below may vary slightly from the actual code in the repository.
Updates to the documentation may happen some time after an update to the codebase.
Nonetheless, this README should provide valuable information about using this tool.
This tool is under heavy development and the documentation/code snippets below may vary slightly from the actual code in the repository. Updates to the documentation may happen some time after an update to the codebase. Nonetheless, this README should provide valuable information about using this tool.

## Overview

Expand All @@ -19,7 +17,7 @@ This is the preferred way. Does not require golang to be installed on the system

To download a binary for the latest release, run:

```
```sh
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-network-runner/main/scripts/install.sh | sh -s
```

Expand All @@ -29,7 +27,7 @@ _Downloading binaries from the Github UI will cause permission errors on Mac._

To add the binary to your path, run

```
```sh
cd bin
export PATH=$PWD:$PATH
```
Expand All @@ -40,28 +38,27 @@ To add it to your path permanently, add an export command to your shell initiali

To download the binary into a specific directory, run:

```
```sh
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-network-runner/main/scripts/install.sh | sh -s -- -b <relative directory>
```

### Install using golang

Requires golang to be installed on the system (https://go.dev/doc/install).
Requires golang to be installed on the system ([https://go.dev/doc/install](https://go.dev/doc/install)).

```sh
go install github.com/ava-labs/avalanche-network-runner@latest
```

After that, the `avalanche-network-runner` binary should be present under the `$HOME/go/bin/` directory.
Consider adding this directory to the `PATH` environment variable.
After that, the `avalanche-network-runner` binary should be present under the `$HOME/go/bin/` directory. Consider adding this directory to the `PATH` environment variable.

### Install by release download

Does not require golang to be installed on the system.

Download the desired distribution from https://github.com/ava-labs/avalanche-network-runner/releases
Download the desired distribution from [https://github.com/ava-labs/avalanche-network-runner/releases](https://github.com/ava-labs/avalanche-network-runner/releases).

Uncompress and locate where is convenient. Consider adding the target bin directory to the `PATH` environment variable.
Uncompress and locate where is convenient. Consider adding the target bin directory to the `PATH` environment variable.

### Install from source code and execute tests

Expand All @@ -79,8 +76,7 @@ From inside the cloned directory:
go install
```

After that, `avalanche-network-runner` binary should be present under `$HOME/go/bin/` directory.
Consider adding this directory to the `PATH` environment variable.
After that, `avalanche-network-runner` binary should be present under `$HOME/go/bin/` directory. Consider adding this directory to the `PATH` environment variable.

#### Run Unit Tests

Expand All @@ -101,7 +97,7 @@ To start it, execute inside the cloned directory:
./scripts/tests.e2e.sh AVALANCHEGO_VERSION1 AVALANCHEGO_VERSION2
```

The E2E test checks wheter a node can be restarted with a different binary version. Provide two
The E2E test checks whether a node can be restarted with a different binary version. Provide two
different versions as arguments. For Example:

```sh
Expand All @@ -117,8 +113,7 @@ setting it if trying to execute E2E tests without using that script.

## Using `avalanche-network-runner`

You can import this repository as a library in your Go program, but we recommend running `avalanche-network-runner` as a binary.
This creates an RPC server that you can send requests to in order to start a network, add nodes to the network, remove nodes from the network, restart nodes, etc.. You can make requests through the `avalanche-network-runner` command or by making API calls. Requests are "translated" into gRPC and sent to the server.
You can import this repository as a library in your Go program, but we recommend running `avalanche-network-runner` as a binary. This creates an RPC server that you can send requests to in order to start a network, add nodes to the network, remove nodes from the network, restart nodes, etc.. You can make requests through the `avalanche-network-runner` command or by making API calls. Requests are "translated" into gRPC and sent to the server.

**Why does `avalanche-network-runner` need an RPC server?** `avalanche-network-runner` needs to provide complex workflows such as replacing nodes, restarting nodes, injecting fail points, etc.. The RPC server exposes basic operations to enable a separation of concerns such that one team develops a test framework, and the other writes test cases and controlling logic.

Expand Down Expand Up @@ -173,9 +168,9 @@ Additional optional parameters which can be passed to the start command:

```bash
--plugin-dir ${AVALANCHEGO_PLUGIN_PATH} \
--blockchain-specs '{"vm_name": "subnetevm", "genesis": "/tmp/subnet-evm.genesis.json"}'
--global-node-config '{"index-enabled":false, "api-admin-enabled":true,"network-peer-list-gossip-frequency":"300ms"}'
--custom-node-configs" '{"node1":{"log-level":"debug","api-admin-enabled":false},"node2":{...},...}'
--blockchain-specs '{"vm_name": "subnetevm", "genesis": "/tmp/subnet-evm.genesis.json"}'
--global-node-config '{"index-enabled":false, "api-admin-enabled":true,"network-peer-list-gossip-frequency":"300ms"}'
--custom-node-configs" '{"node1":{"log-level":"debug","api-admin-enabled":false},"node2":{...},...}'
```
For example, to set `avalanchego --http-host` flag for all nodes:
Expand All @@ -194,7 +189,9 @@ avalanche-network-runner control start \
See the [subnet](#network-runner-rpc-server-subnet-evm-example) section for details about how to run subnets.
The network-runner supports avalanchego node configuration at different levels.
1. If neither `--global-node-config` nor `--custom-node-configs` is supplied, all nodes get a standard set of config options. Currently this set contains:
```json
{
"network-peer-list-gossip-frequency":"250ms",
Expand All @@ -206,18 +203,20 @@ The network-runner supports avalanchego node configuration at different levels.
"index-enabled":true
}
```
2. `--global-node-config` is a JSON string representing a *single* avalanchego config, which will be applied to **all nodes**. This makes it easy to define common properties to all nodes. Whatever is set here will be *combined* with the standard set above.
3. `--custom-node-configs` is a map of JSON strings representing the *complete* network with individual configs. This allows to configure each node independently. If set, `--number-of-nodes` will be **ignored** to avoid conflicts.
2. `--global-node-config` is a JSON string representing a _single_ avalanchego config, which will be applied to **all nodes**. This makes it easy to define common properties to all nodes. Whatever is set here will be _combined_ with the standard set above.
3. `--custom-node-configs` is a map of JSON strings representing the _complete_ network with individual configs. This allows to configure each node independently. If set, `--number-of-nodes` will be **ignored** to avoid conflicts.
4. The configs can be combined and will be merged, i.e. one could set global `--global-node-config` entries applied to each node, and also set `--custom-node-configs` for additional entries.
5. Common `--custom-node-configs` entries override `--global-node-config` entries which override the standard set.
6. The following entries will be **ignored in all cases** because the network-runner needs to set them internally to function properly:
```
--log-dir
--db-dir
--http-port
--staking-port
--public-ip
```
```sh
--log-dir
--db-dir
--http-port
--staking-port
--public-ip
```
**NAMING CONVENTION**: Currently, node names should be called `node` + a number, i.e. `node1,node2,node3,...node 101`
Expand Down Expand Up @@ -391,14 +390,13 @@ avalanche-network-runner control add-node \
You can also provide additional flags that specify the node's config:
```
--node-config '{"index-enabled":false, "api-admin-enabled":true,"network-peer-list-gossip-frequency":"300ms"}'
```sh
--node-config '{"index-enabled":false, "api-admin-enabled":true,"network-peer-list-gossip-frequency":"300ms"}'
```
`--node-config` allows to specify specific avalanchego config parameters to the new node.
See [here](https://docs.avax.network/build/references/avalanchego-config-flags) for the reference of supported flags.
`--node-config` allows to specify specific avalanchego config parameters to the new node. See [here](https://docs.avax.network/build/references/avalanchego-config-flags) for the reference of supported flags.
**Note**: The following parameters will be *ignored* if set in `--node-config`, because the network runner needs to set its own in order to function properly:
**Note**: The following parameters will be _ignored_ if set in `--node-config`, because the network runner needs to set its own in order to function properly:
`--log-dir`
`--db-dir`
Expand Down Expand Up @@ -671,8 +669,7 @@ type Config struct {
}
```
As you can see, some fields of the config must be set, while others will be auto-generated if not provided.
Bootstrap IPs/ IDs will be overwritten even if provided.
As you can see, some fields of the config must be set, while others will be auto-generated if not provided. Bootstrap IPs/ IDs will be overwritten even if provided.
## Genesis Generation
Expand Down Expand Up @@ -727,8 +724,7 @@ The function that returns a new network may have additional configuration fields
## Default Network Creation
The helper function `NewDefaultNetwork` returns a network using a pre-defined configuration.
This allows users to create a new network without needing to define any configurations.
The helper function `NewDefaultNetwork` returns a network using a pre-defined configuration. This allows users to create a new network without needing to define any configurations.
```go
// NewDefaultNetwork returns a new network using a pre-defined
Expand Down Expand Up @@ -760,10 +756,9 @@ The associated pre-defined configuration is also available to users by calling `
## Network Snapshots
A given network state, including the node ports and the full blockchain state, can be saved to a named snapshot.
The network can then be restarted from such a snapshot any time later.
A given network state, including the node ports and the full blockchain state, can be saved to a named snapshot. The network can then be restarted from such a snapshot any time later.
```
```go
// Save network snapshot
// Network is stopped in order to do a safe persistence
// Returns the full local path to the snapshot dir
Expand All @@ -783,37 +778,37 @@ The network runner allows users to interact with an AvalancheGo network using th
```go
// Network is an abstraction of an Avalanche network
type Network interface {
// Returns nil if all the nodes in the network are healthy.
// A stopped network is considered unhealthy.
// Timeout is given by the context parameter.
Healthy(context.Context) error
// Stop all the nodes.
// Returns ErrStopped if Stop() was previously called.
Stop(context.Context) error
// Start a new node with the given config.
// Returns ErrStopped if Stop() was previously called.
AddNode(node.Config) (node.Node, error)
// Stop the node with this name.
// Returns ErrStopped if Stop() was previously called.
RemoveNode(name string) error
// Return the node with this name.
// Returns ErrStopped if Stop() was previously called.
GetNode(name string) (node.Node, error)
// Return all the nodes in this network.
// Node name --> Node.
// Returns ErrStopped if Stop() was previously called.
GetAllNodes() (map[string]node.Node, error)
// Returns the names of all nodes in this network.
// Returns ErrStopped if Stop() was previously called.
GetNodeNames() ([]string, error)
// Save network snapshot
// Network is stopped in order to do a safe preservation
// Returns the full local path to the snapshot dir
SaveSnapshot(context.Context, string) (string, error)
// Remove network snapshot
RemoveSnapshot(string) error
// Get name of available snapshots
GetSnapshotNames() ([]string, error)
// Returns nil if all the nodes in the network are healthy.
// A stopped network is considered unhealthy.
// Timeout is given by the context parameter.
Healthy(context.Context) error
// Stop all the nodes.
// Returns ErrStopped if Stop() was previously called.
Stop(context.Context) error
// Start a new node with the given config.
// Returns ErrStopped if Stop() was previously called.
AddNode(node.Config) (node.Node, error)
// Stop the node with this name.
// Returns ErrStopped if Stop() was previously called.
RemoveNode(name string) error
// Return the node with this name.
// Returns ErrStopped if Stop() was previously called.
GetNode(name string) (node.Node, error)
// Return all the nodes in this network.
// Node name --> Node.
// Returns ErrStopped if Stop() was previously called.
GetAllNodes() (map[string]node.Node, error)
// Returns the names of all nodes in this network.
// Returns ErrStopped if Stop() was previously called.
GetNodeNames() ([]string, error)
// Save network snapshot
// Network is stopped in order to do a safe preservation
// Returns the full local path to the snapshot dir
SaveSnapshot(context.Context, string) (string, error)
// Remove network snapshot
RemoveSnapshot(string) error
// Get name of available snapshots
GetSnapshotNames() ([]string, error)
}
```
Expand All @@ -822,32 +817,32 @@ and allows users to interact with a node using the `node.Node` interface:
```go
// Node represents an AvalancheGo node
type Node interface {
// Return this node's name, which is unique
// across all the nodes in its network.
GetName() string
// Return this node's Avalanche node ID.
GetNodeID() ids.ShortID
// Return a client that can be used to make API calls.
GetAPIClient() api.Client
// Return this node's IP (e.g. 127.0.0.1).
GetURL() string
// Return this node's P2P (staking) port.
GetP2PPort() uint16
// Return this node's HTTP API port.
GetAPIPort() uint16
// Starts a new test peer, connects it to the given node, and returns the peer.
// [handler] defines how the test peer handles messages it receives.
// The test peer can be used to send messages to the node it's attached to.
// It's left to the caller to maintain a reference to the returned peer.
// The caller should call StartClose() on the peer when they're done with it.
AttachPeer(ctx context.Context, handler router.InboundHandler) (peer.Peer, error)
// Return this node's avalanchego binary path
GetBinaryPath() string
// Return this node's db dir
GetDbDir() string
// Return this node's logs dir
GetLogsDir() string
// Return this node's config file contents
GetConfigFile() string
// Return this node's name, which is unique
// across all the nodes in its network.
GetName() string
// Return this node's Avalanche node ID.
GetNodeID() ids.ShortID
// Return a client that can be used to make API calls.
GetAPIClient() api.Client
// Return this node's IP (e.g. 127.0.0.1).
GetURL() string
// Return this node's P2P (staking) port.
GetP2PPort() uint16
// Return this node's HTTP API port.
GetAPIPort() uint16
// Starts a new test peer, connects it to the given node, and returns the peer.
// [handler] defines how the test peer handles messages it receives.
// The test peer can be used to send messages to the node it's attached to.
// It's left to the caller to maintain a reference to the returned peer.
// The caller should call StartClose() on the peer when they're done with it.
AttachPeer(ctx context.Context, handler router.InboundHandler) (peer.Peer, error)
// Return this node's avalanchego binary path
GetBinaryPath() string
// Return this node's db dir
GetDbDir() string
// Return this node's logs dir
GetLogsDir() string
// Return this node's config file contents
GetConfigFile() string
}
```

0 comments on commit f5f0419

Please sign in to comment.