Deploy Your Own Gaia Testnet

This document describes 3 ways to setup a network of wasmd 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.

Available Docker images

In case you need to use or deploy gaia as a container you could skip the build steps and use the official images, $TAG stands for the version you are interested in:

docker run -it -v ~/.wasmd:/root/.wasmd -v ~/.wasmcli:/root/.wasmcli tendermint:$TAG wasmd init
docker run -it -p 26657:26657 -p 26656:26656 -v ~/.wasmd:/root/.wasmd -v ~/.wasmcli:/root/.wasmcli tendermint:$TAG wasmd start
...
docker run -it -v ~/.wasmd:/root/.wasmd -v ~/.wasmcli:/root/.wasmcli tendermint:$TAG wasmcli version

The same images can be used to build your own docker-compose stack.

Single-node, Local, Manual Testnet

This guide helps you create a single validator node that runs a network locally for testing and other development related uses.

Requirements

Install gaia
Install jq (optional)

Create Genesis File and Start the Network

# 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
wasmd init --chain-id=testing testing

# Create a key to hold your validator account
wasmcli 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
wasmd add-genesis-account $(wasmcli keys show validator -a) 1000000000stake,1000000000validatortoken

# Generate the transaction that creates your validator
wasmd gentx --name validator

# Add the generated bonding transaction to the genesis file
wasmd collect-gentxs

# Now its safe to start `wasmd`
wasmd start

This setup puts all the data for wasmd in ~/.wasmd. You can examine the genesis file you created at ~/.wasmd/config/genesis.json. With this configuration wasmcli is also ready to use and has an account with tokens (both staking and custom).

Set up client

wasmcli config chain-id testing
wasmcli config trust-node true
wasmcli config node tcp://localhost:26657
wasmcli config output json
wasmcli config indent true

# verify initial setup
wasmcli query account $(wasmcli keys show validator -a)
wasmcli query wasm list-code
wasmcli query wasm list-contracts

# upload a contract and verify
cp $HOME/go/src/github.com/cosmwasm/wasmd/x/wasm/internal/keeper/testdata/contract.wasm upload.wasm
wasmcli tx wasm store validator upload.wasm --gas 800000
# TODO: stops after one hit
wasmcli query wasm list-code
wasmcli query wasm code 1 download.wasm
sha256sum upload.wasm download.wasm

# prepare more accounts
wasmcli keys add fred
wasmcli keys add bob
wasmcli tx send $(wasmcli keys show validator -a) $(wasmcli keys show fred -a) 98765stake
wasmcli query account $(wasmcli keys show fred -a)
wasmcli query account $(wasmcli keys show bob -a)

# instantiate contract and verify
INIT="{\"verifier\":\"$(wasmcli keys show fred -a)\", \"beneficiary\":\"$(wasmcli keys show bob -a)\"}"
wasmcli tx wasm instantiate validator 1 "$INIT" --amount=50000stake
sleep 3
wasmcli query wasm list-contracts
CONTRACT=cosmos18vd8fpwxzck93qlwghaj6arh4p7c5n89uzcee5
wasmcli query wasm contract $CONTRACT
wasmcli query wasm contract-state $CONTRACT
wasmcli query account $CONTRACT

# execute fails if wrong person
wasmcli tx wasm execute validator $CONTRACT "{}"
sleep 3
wasmcli query tx <hash from above>
wasmcli query account $(wasmcli keys show bob -a)

wasmcli tx wasm execute fred $CONTRACT "{}"
sleep 3
wasmcli query account $(wasmcli keys show bob -a)
wasmcli query account $CONTRACT

Multi-node, Local, Automated Testnet

From the networks/local directory:

Requirements

Install gaia
Install docker
Install docker-compose

Build

Build the wasmd binary (linux) and the tendermint/wasmdnode 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.

# Work from the SDK repo
cd $GOPATH/src/github.com/cosmwasm/wasmd

# Build the linux binary in ./build
make build-linux

# Build tendermint/wasmdnode image
make build-docker-wasmdnode

Run Your Testnet

To start a 4 node testnet run:

make localnet-start

This command creates a 4-node network using the wasmdnode image. The ports for each node are found in this table:

Node ID	P2P Port	RPC Port
`gaianode0`	`26656`	`26657`
`gaianode1`	`26659`	`26660`
`gaianode2`	`26661`	`26662`
`gaianode3`	`26663`	`26664`

To update the binary, just rebuild it and restart the nodes:

make build-linux localnet-start

Configuration

The make localnet-start creates files for a 4-node testnet in ./build by calling the wasmd testnet command. This outputs a handful of files in the ./build directory:

$ tree -L 2 build/
build/
├── wasmcli
├── wasmd
├── gentxs
│   ├── node0.json
│   ├── node1.json
│   ├── node2.json
│   └── node3.json
├── node0
│   ├── wasmcli
│   │   ├── key_seed.json
│   │   └── keys
│   └── wasmd
│       ├── ${LOG:-wasmd.log}
│       ├── config
│       └── data
├── node1
│   ├── wasmcli
│   │   └── key_seed.json
│   └── wasmd
│       ├── ${LOG:-wasmd.log}
│       ├── config
│       └── data
├── node2
│   ├── wasmcli
│   │   └── key_seed.json
│   └── wasmd
│       ├── ${LOG:-wasmd.log}
│       ├── config
│       └── data
└── node3
    ├── wasmcli
    │   └── key_seed.json
    └── wasmd
        ├── ${LOG:-wasmd.log}
        ├── config
        └── data

Each ./build/nodeN directory is mounted to the /wasmd directory in each container.

Logging

Logs are saved under each ./build/nodeN/wasmd/gaia.log. You can also watch logs directly via Docker, for example:

docker logs -f wasmdnode0

Keys & Accounts

To interact with wasmcli and start querying state or creating txs, you use the wasmcli directory of any given node as your home, for example:

wasmcli keys list --home ./build/node0/wasmcli

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/wasmcli/key_seed.json and can be restored to the CLI using the wasmcli keys add --restore command :::

Special Binaries

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=gaiafoo make localnet-start

Multi-Node, Remote, Automated Testnet

The following should be run from the networks directory.

Terraform & Ansible

Automated deployments are done using Terraform to create servers on AWS then Ansible to create and manage testnets on those servers.

Prerequisites

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.

Create a Remote Network

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

Quickly see the /status Endpoint

make validators-status

Delete Servers

make validators-stop

Logging

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

Monitoring

You can install the DataDog agent with:

make datadog-install

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

deploy-testnet.md

deploy-testnet.md

Deploy Your Own Gaia Testnet

Available Docker images

Single-node, Local, Manual Testnet

Requirements

Create Genesis File and Start the Network

Set up client

Multi-node, Local, Automated Testnet

Requirements

Build

Run Your Testnet

Configuration

Logging

Keys & Accounts

Special Binaries

Multi-Node, Remote, Automated Testnet

Terraform & Ansible

Prerequisites

Create a Remote Network

Quickly see the /status Endpoint

Delete Servers

Logging

Monitoring

Files

deploy-testnet.md

Latest commit

History

deploy-testnet.md

File metadata and controls

Deploy Your Own Gaia Testnet

Available Docker images

Single-node, Local, Manual Testnet

Requirements

Create Genesis File and Start the Network

Set up client

Multi-node, Local, Automated Testnet

Requirements

Build

Run Your Testnet

Configuration

Logging

Keys & Accounts

Special Binaries

Multi-Node, Remote, Automated Testnet

Terraform & Ansible

Prerequisites

Create a Remote Network

Quickly see the /status Endpoint

Delete Servers

Logging

Monitoring