CoreumFoundation / crust

5 stars 8 forks source link

crust

crust helps you build and run all the applications needed for development and testing.

Prerequisites

To use crust you need:

Install them manually before continuing.

Building

  1. Clone repos to the directory of your choice (let's call it $COREUM_PATH):
cd $COREUM_PATH
git clone https://github.com/CoreumFoundation/crust
git clone https://github.com/CoreumFoundation/coreum

If you are going to use faucet and explorer, also clone these repos:

git clone https://github.com/CoreumFoundation/faucet
git clone https://github.com/CoreumFoundation/bdjuno
  1. Not required but recommended: Add bin directory of all projects to your PATH environment variable:
export PATH="$COREUM_PATH/crust/bin:$COREUM_PATH/coreum/bin:$COREUM_PATH/faucet/bin:$COREUM_PATH/bdjuno/bin:$PATH"
  1. Compile all the required binaries and docker images:
$COREUM_PATH/crust/bin/crust build images
$COREUM_PATH/coreum/bin/coreum-builder build images

If you are going to use faucet and explorer, also build their images:

$COREUM_PATH/faucet/bin/faucet-builder build images
$COREUM_PATH/bdjuno/bin/bdjuno-builder build images

After the command crust build images completes you may find executable $COREUM_PATH/crust/bin/cored, being both blockchain node and client.

Note: You need to run respective builder build images after you modify that project. For example if you do a modification in coreum project, you need to run coreum-builder build images.

Executing znet

znet is the tool used to spin up development environment running the same components which are used in production.

znet may be executed using two methods. First is direct where you execute command directly:

$ crust znet <command> [flags]

Second one is by entering the znet-environment:

$ crust znet [flags]
(<environment-name>) [znet] $ <command> 

The second method saves some typing.

Flags

All the flags are optional. Execute

$ crust znet <command> --help

to see what the default values are.

--env

Defines name of the environment, it is visible in brackets on the left. Each environment is independent, you may create many of them and work with them in parallel.

--profiles

Defines the list of available application profiles to run. Available profiles:

NOTE: 1cored, 3cored, 5cored and devnet are mutually exclusive.

To start fully-featured set you may run:

$ crust znet start --profiles=3cored,faucet,explorer,monitoring

NOTE: Notice from here on out, if you already have a znet env started with a set profiles, and you want to start znet with a different set of profiles, you need to remove previous znet env with crust znet remove and only then you can start the new env.

--cored-version

The --cored-version allows to start the znet with any previously released version.

$ crust znet start --cored-version=v1.0.0 --profiles=3cored,faucet,explorer,monitoring

NOTE: if you already have a znet env started with different profiles, you need to remove it with crust znet remove so you can start a new environment.

Also, it's possible to execute tests with any previously released version.

$ crust znet test --cored-version=v1.0.0 --test-groups=coreum-upgrade

Commands

In the environment some wrapper scripts for znet are generated automatically to make your life easier. Each such <command> calls crust znet <command>.

Available commands are:

Example

Basic workflow may look like this:

# Enter the environment:
$ crust znet
(znet) [znet] $

# Start applications
(znet) [znet] $ start

# Print spec
(znet) [znet] $ spec

# Stop applications
(znet) [znet] $ stop

# Start applications again
(znet) [znet] $ start

# Stop everything and clean resources
(znet) [znet] $ remove
$

Logs

After entering and starting environment:

$ crust znet
(znet) [znet] $ start

it is possible to use logs wrapper to tail logs from an application:

(znet) [znet] $ logs cored-00-val

Playing with the blockchain manually

For each cored instance started by znet wrapper script named after the name of the node is created, so you may call the client manually. There are also three standard keys: alice, bob and charlie added to the keystore of each instance.

If you start znet using default --profiles=1cored there is one cored application called cored-00-val. To use the client you may use cored-00-val wrapper:

(znet) [znet] $ start 

Generate a wallet to transfer funds to

(znet) [znet] $ cored-00-val keys add {YOUR_WALLET_NAME}

Take the address the out put of the command above, you will use it in the next commands.

(znet) [znet] $ cored-00-val query bank balances {YOUR_GENERATED_ADDRESS}
(znet) [znet] $ cored-00-val tx bank send bob {YOUR_GENERATED_ADDRESS} 10udevcore
(znet) [znet] $ cored-00-val query bank balances {YOUR_GENERATED_ADDRESS}

Integration tests

You may run integration tests directly:

$ crust znet test

Tests run on top of --profiles=integration-tests.

It's also possible to enter the environment first, and run tests from there:

$ crust znet 
(znet) [znet] $ start --profiles=integration-tests
(znet) [znet] $ tests

# Remember to clean everything
(znet) [znet] $ remove

After tests complete environment is still running so if something went wrong you may inspect it manually.

Hard reset

If you want to manually remove all the data created by znet do this:

Monitoring

If you use the monitoring profile to start the znet you can open http://localhost:3001 to access the Grafana UI (admin/admin credentials). Or use http://localhost:9092 to access the prometheus UI.