From e3bc5a542b7eb64c5b7f0d748fc46db40d65eb0d Mon Sep 17 00:00:00 2001 From: Timo Welde Date: Thu, 13 Jun 2019 18:07:31 +0200 Subject: [PATCH 1/3] docs: make it more clear, how to run a node --- README.md | 130 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 109 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index b8735858a8..78b0eb853d 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,127 @@ -# prototype-chain +![](https://user-images.githubusercontent.com/1248214/57789522-600fcc00-7739-11e9-86d9-73d7032f40fc.png) + +# KILT mashnet-node (previously prototype-chain) Substrate node implementation for the KILT prototype -## Updating with latest substrate-node-template +## How to use +To start a node, you need to build the code, or use an existing image and decide for a command to execute. -The command `substrate-node-new`, described in https://docs.substrate.dev/docs/creating-a-custom-substrate-chain downloads a node-template, which this repo bases on. -We just added our modules to the runtime. +## Building / Images +To build the code, or get a prebuilt image, you have these options: +- Docker image from dockerhub +- Building the docker image yourself +- Building the code without docker -To update it, a stable template can be copied from https://github.com/shawntabrizi/substrate-package. -Just copy the contents of substrate-node-template and add our changes on top. +### Dockerhub +To get the image from dockerhub execute following command: +``` +docker pull kiltprotocol/mashnet-node +``` +and run the node by executing: +``` +docker run -p 9944:9944 kiltprotocol/mashnet-node [node command] +``` + +### Building docker image +Clone this repo and navigate into it. + +Build docker image: +``` +docker build -t local/mashnet-node . +``` +start, by running: +``` +docker run -p 9944:9944 local/mashnet-node [node command] +``` + +### Build code without docker +You need to have rust and cargo installed and configured properly. + +You can build it by executing these commands: +``` +./init.sh +./build.sh +cargo build +``` + +For execution see the section about commands. + +## Commands +To start the node you have following options: +- start-node.sh helper script +- executing the node binary directly +### Helper script +We include a helper script, which sets up the arguments used for the node binary. + +Use it by executing: +``` +./start-node.sh --help +``` + +This can be used in all building strategies: +``` +docker run -p 9944:9944 kiltprotocol/mashnet-node ./start-node.sh --connect-to alice +``` +or +``` +docker run -p 9944:9944 local/mashnet-node ./start-node.sh --connect-to alice +``` +or if you build it without docker: +``` +./start-node.sh --connect-to alice +``` + +### Node binary +The node binary, which gets build lies in the directory +``` +./target/debug/node [arguments] +``` + +If you want to start a local dev-chain you can execute: +``` +./target/debug/node --dev +``` + +If you are using a docker image, run: +``` +docker run -p 9944:9944 kiltprotocol/mashnet-node ./target/debug/node --dev --ws-port 9944 --ws-external --rpc-external +``` -If the mentioned repo of shawntabrizi isn't updated anymore, the `substrate-node-new` command can still be used to get a fresh node-template. It might need some changes to work, though. -## Running a local node that connects to KILT prototype testnet in AWS +## Examples + +### Running a local node that connects to KILT prototype testnet in AWS There are master boot nodes running in the KILT testnet: * Alice (bootnode-alice.kilt-prototype.tk) * Bob (bootnode-bob.kilt-prototype.tk) -To start a node and connect to Alice you can use the shell script `start-node.sh`: +To start a node and connect to alice you can use the shell script `start-node.sh`: ``` -./start-node.sh --connect-to Alice +./start-node.sh --connect-to alice ``` If you want to connect to this node via RPC, add the `--rpc` flag: ``` -./start-node.sh --connect-to Alice --rpc +./start-node.sh --connect-to alice --rpc ``` Run `./start-node.sh --help` for more information. -### Running a node inside a docker container +### Running a node with local image, which runs a dev-chain +build docker image (only do if code has changed, takes ~15 min) +``` +docker build -t dev/mashnet-node . +``` +run chain in dev mode locally +``` +docker run -p 9944:9944 dev/mashnet-node ./target/debug/node --dev --ws-port 9944 --ws-external --rpc-external +``` + +## Development with AWS images: Make sure to have the `awscli` installed. Otherwise Install it via `brew install awscli` (Mac). You also need to have your docker daemon system running (on mac, just download and install the docker application). @@ -51,20 +140,19 @@ docker pull 348099934012.dkr.ecr.eu-central-1.amazonaws.com/kilt/prototype-chain 3. Run node - a. To run a node and connect it to the KILT testnet: Run the image and pass the command to start a node: +To run a node and connect it to the KILT testnet: Run the image and pass the command to start a node: ``` -docker run 348099934012.dkr.ecr.eu-central-1.amazonaws.com/kilt/prototype-chain ./start-node.sh --connect-to Alice +docker run 348099934012.dkr.ecr.eu-central-1.amazonaws.com/kilt/prototype-chain ./start-node.sh --connect-to alice ``` The node should be connected to the KILT testnet. +## Updating with latest substrate-node-template - b. For local development with an isolated local chain, execute: +The command `substrate-node-new`, described in https://docs.substrate.dev/docs/creating-a-custom-substrate-chain downloads a node-template, which this repo bases on. +We just added our modules to the runtime. -``` -# build docker image (only do if code has changed, takes ~15 min) -docker build -t prototype-chain . +To update it, a stable template can be copied from https://github.com/shawntabrizi/substrate-package. +Just copy the contents of substrate-node-template and add our changes on top. -# run chain in dev mode locally -docker run -p 9944:9944 prototype-chain ./target/debug/node --dev --ws-port 9944 --ws-external --rpc-external -``` +If the mentioned repo of shawntabrizi isn't updated anymore, the `substrate-node-new` command can still be used to get a fresh node-template. It might need some changes to work, though. From f86109c71c1ce3abd0cd57aba7eba26e2d7b032a Mon Sep 17 00:00:00 2001 From: Timo Welde Date: Thu, 13 Jun 2019 18:24:18 +0200 Subject: [PATCH 2/3] docs: quickstart guide and TOC --- README.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 78b0eb853d..afbeab26f6 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,33 @@ Substrate node implementation for the KILT prototype +## Table of Contents +- [How to use TLDR](#how-to-use-tldr) +- [How to use](#how-to-use) +- [Building / Images](#building--images) + - [Dockerhub](#dockerhub) + - [Building docker image](#building-docker-image) + - [Build code without docker](#build-code-without-docker) +- [Commands](#commands) + - [Helper script](#helper-script) + - [Node binary](#node-binary) +- [Examples](#examples) + - [Running a local node that connects to KILT prototype testnet in AWS](#running-a-local-node-that-connects-to-kilt-prototype-testnet-in-aws) + - [Running a node with local image, which runs a dev-chain](#running-a-node-with-local-image-which-runs-a-dev-chain) +- [Development with AWS images](#development-with-aws-images) +- [Updating with latest substrate-node-template](#updating-with-latest-substrate-node-template) + +## How to use TLDR +Start chain and connect to alice bootnode: +``` +docker run -p 9944:9944 kiltprotocol/mashnet-node ./start-node.sh --connect-to alice +``` + +Start dev chain for local development +``` +docker run -p 9944:9944 kiltprotocol/mashnet-node ./target/debug/node --dev --ws-port 9944 --ws-external --rpc-external +``` + ## How to use To start a node, you need to build the code, or use an existing image and decide for a command to execute. @@ -121,7 +148,7 @@ run chain in dev mode locally docker run -p 9944:9944 dev/mashnet-node ./target/debug/node --dev --ws-port 9944 --ws-external --rpc-external ``` -## Development with AWS images: +## Development with AWS images Make sure to have the `awscli` installed. Otherwise Install it via `brew install awscli` (Mac). You also need to have your docker daemon system running (on mac, just download and install the docker application). From 640caa6a671b313b083c60a338e22a1cf101f60c Mon Sep 17 00:00:00 2001 From: Timo Welde Date: Thu, 13 Jun 2019 18:28:15 +0200 Subject: [PATCH 3/3] docs: better structure --- README.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index afbeab26f6..1b97e19ba9 100644 --- a/README.md +++ b/README.md @@ -7,16 +7,16 @@ Substrate node implementation for the KILT prototype ## Table of Contents - [How to use TLDR](#how-to-use-tldr) - [How to use](#how-to-use) -- [Building / Images](#building--images) - - [Dockerhub](#dockerhub) - - [Building docker image](#building-docker-image) - - [Build code without docker](#build-code-without-docker) -- [Commands](#commands) - - [Helper script](#helper-script) - - [Node binary](#node-binary) -- [Examples](#examples) - - [Running a local node that connects to KILT prototype testnet in AWS](#running-a-local-node-that-connects-to-kilt-prototype-testnet-in-aws) - - [Running a node with local image, which runs a dev-chain](#running-a-node-with-local-image-which-runs-a-dev-chain) + - [Building / Images](#building--images) + - [Dockerhub](#dockerhub) + - [Building docker image](#building-docker-image) + - [Build code without docker](#build-code-without-docker) + - [Commands](#commands) + - [Helper script](#helper-script) + - [Node binary](#node-binary) + - [Examples](#examples) + - [Running a local node that connects to KILT prototype testnet in AWS](#running-a-local-node-that-connects-to-kilt-prototype-testnet-in-aws) + - [Running a node with local image, which runs a dev-chain](#running-a-node-with-local-image-which-runs-a-dev-chain) - [Development with AWS images](#development-with-aws-images) - [Updating with latest substrate-node-template](#updating-with-latest-substrate-node-template) @@ -34,13 +34,13 @@ docker run -p 9944:9944 kiltprotocol/mashnet-node ./target/debug/node --dev --ws ## How to use To start a node, you need to build the code, or use an existing image and decide for a command to execute. -## Building / Images +### Building / Images To build the code, or get a prebuilt image, you have these options: - Docker image from dockerhub - Building the docker image yourself - Building the code without docker -### Dockerhub +#### Dockerhub To get the image from dockerhub execute following command: ``` docker pull kiltprotocol/mashnet-node @@ -50,7 +50,7 @@ and run the node by executing: docker run -p 9944:9944 kiltprotocol/mashnet-node [node command] ``` -### Building docker image +#### Building docker image Clone this repo and navigate into it. Build docker image: @@ -62,7 +62,7 @@ start, by running: docker run -p 9944:9944 local/mashnet-node [node command] ``` -### Build code without docker +#### Build code without docker You need to have rust and cargo installed and configured properly. You can build it by executing these commands: @@ -74,11 +74,11 @@ cargo build For execution see the section about commands. -## Commands +### Commands To start the node you have following options: - start-node.sh helper script - executing the node binary directly -### Helper script +#### Helper script We include a helper script, which sets up the arguments used for the node binary. Use it by executing: @@ -99,7 +99,7 @@ or if you build it without docker: ./start-node.sh --connect-to alice ``` -### Node binary +#### Node binary The node binary, which gets build lies in the directory ``` ./target/debug/node [arguments] @@ -116,9 +116,9 @@ docker run -p 9944:9944 kiltprotocol/mashnet-node ./target/debug/node --dev --ws ``` -## Examples +### Examples -### Running a local node that connects to KILT prototype testnet in AWS +#### Running a local node that connects to KILT prototype testnet in AWS There are master boot nodes running in the KILT testnet: @@ -138,7 +138,7 @@ If you want to connect to this node via RPC, add the `--rpc` flag: Run `./start-node.sh --help` for more information. -### Running a node with local image, which runs a dev-chain +#### Running a node with local image, which runs a dev-chain build docker image (only do if code has changed, takes ~15 min) ``` docker build -t dev/mashnet-node .