This document describes 3 ways to setup a network of Finschia
nodes, each serving a different usecase:
- Single-node, local, manual testnet
- Multi-node, local, automated testnet
- Multi-node, remote, automated testnet
Supporting code can be found in the networks directory and additionally the local
or remote
sub-directories.
NOTE: The
remote
network bootstrapping may be out of sync with the latest releases and is not to be relied upon.
TBD
This guide helps you create a single validator node that runs a network locally for testing and other development related uses.
- Install Finschia
- Install
jq
(optional)
# You can run all of these commands from your home directory
cd $HOME
# Initialize the genesis.json file that will help you to bootstrap the network
fnsad init --chain-id=testing testing
# Create a key to hold your validator account
fnsad keys add validator
# Add that key into the genesis.app_state.accounts array in the genesis file
# NOTE: this command lets you set the number of coins. Make sure this account has some coins
# with the genesis.app_state.staking.params.bond_denom denom, the default is staking
fnsad add-genesis-account $(fnsad keys show validator -a) 1000000000stake,1000000000validatortoken
# Generate the transaction that creates your validator
fnsad gentx validator 1000000000stake --chain-id testing
# Add the generated bonding transaction to the genesis file
fnsad collect-gentxs
# Now its safe to start `fnsad`
fnsad start
This setup puts all the data for Finschia
in ~/.finschia
. You can examine the genesis file you created at ~/.finschia/config/genesis.json
. With this configuration finschia
is also ready to use and has an account with tokens (both staking and custom).
From the networks/local directory:
Build the fnsad
binary (linux) and the finschia/finschianode
docker image required for running the localnet
commands. This binary will be mounted into the container and can be updated rebuilding the image, so you only need to build the image once.
# Clone the finschia repo
git clone https://github.com/Finschia/finschia.git
# Work from the finschia repo
cd finschia
# Build the linux binary in ./build
make build-linux
# Build finschia/finschianode image
make build-docker-finschianode
To start a 4 node testnet run:
make localnet-start
This command creates a 4-node network using the finschianode image. The ports for each node are found in this table:
Node ID | P2P Port | RPC Port |
---|---|---|
finschianode0 |
26656 |
26657 |
finschianode1 |
26659 |
26660 |
finschianode2 |
26661 |
26662 |
finschianode3 |
26663 |
26664 |
To update the binary, just rebuild it and restart the nodes:
make build-linux localnet-start
To stop docker Finschia nodes:
make localnet-stop
The make localnet-start
creates files for a 4-node testnet in ./build
by
calling the fnsad testnet
command. This outputs a handful of files in the
./build
directory:
$ tree -L 2 build/
build/
├── gentxs
│ ├── node0.json
│ ├── node1.json
│ ├── node2.json
│ └── node3.json
├── finschia
├── node0
│ └── finschia
│ ├── config
│ ├── data
│ ├── key_seed.json
│ ├── keyring-test
│ └── finschia.log
├── node1
│ └── finschia
│ ├── config
│ ├── data
│ ├── key_seed.json
│ ├── keyring-test
│ └── finschia.log
├── node2
│ └── finschia
│ ├── config
│ ├── data
│ ├── key_seed.json
│ ├── keyring-test
│ └── finschia.log
└── node3
└── finschia
├── config
├── data
├── key_seed.json
├── keyring-test
└── finschia.log
Each ./build/nodeN
directory is mounted to the /finschia
directory in each container.
Logs are saved under each ./build/nodeN/finschia/finschia.log
. You can also watch logs
directly via Docker, for example:
docker logs -f finschianode0
To interact with fnsad
and start querying state or creating txs, you use the
fnsad
directory of any given node as your home
, for example:
fnsad keys list --home ./build/node0/finschia
Now that accounts exists, you may create new accounts and send those accounts funds!
::: tip
Note: Each node's seed is located at ./build/nodeN/finschia/key_seed.json
and can be restored to the CLI using the fnsad keys add --restore
command
:::
If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. For example:
# Run with custom binary
BINARY=fnsad make localnet-start
The following should be run from the networks directory.
Automated deployments are done using Terraform to create servers on AWS then Ansible to create and manage testnets on those servers.
- Install Terraform and Ansible on a Linux machine.
- Create an AWS API token with EC2 create capability.
- Create SSH keys
export AWS_ACCESS_KEY_ID="2345234jk2lh4234"
export AWS_SECRET_ACCESS_KEY="234jhkg234h52kh4g5khg34"
export TESTNET_NAME="remotenet"
export CLUSTER_NAME= "remotenetvalidators"
export SSH_PRIVATE_FILE="$HOME/.ssh/id_rsa"
export SSH_PUBLIC_FILE="$HOME/.ssh/id_rsa.pub"
These will be used by both terraform
and ansible
.
SERVERS=1 REGION_LIMIT=1 make validators-start
The testnet name is what's going to be used in --chain-id, while the cluster name is the administrative tag in AWS for the servers. The code will create SERVERS amount of servers in each availability zone up to the number of REGION_LIMITs, starting at us-east-2. (us-east-1 is excluded.) The below BaSH script does the same, but sometimes it's more comfortable for input.
./new-testnet.sh "$TESTNET_NAME" "$CLUSTER_NAME" 1 1
make validators-status
make validators-stop
You can ship logs to Logz.io, an Elastic stack (Elastic search, Logstash and Kibana) service provider. You can set up your nodes to log there automatically. Create an account and get your API key from the notes on this page, then:
yum install systemd-devel || echo "This will only work on RHEL-based systems."
apt-get install libsystemd-dev || echo "This will only work on Debian-based systems."
go get github.com/mheese/journalbeat
ansible-playbook -i inventory/digital_ocean.py -l remotenet logzio.yml -e LOGZIO_TOKEN=ABCDEFGHIJKLMNOPQRSTUVWXYZ012345
You can install the DataDog agent with:
make datadog-install