Node Setup and Configuration Tools

The setup command provides functions for creating and managing node configuration and data, including:

• performing quick setup of a standalone Kwil node (init) and Kwil test networks (testnet)
• updating genesis config a hash of the initial database state (genesis-hash)
• resetting node state and all data files (reset)

Quick Setup of a Single Kwil Node

The init command facilitates quick setup of an isolated Kwil node on a fresh network in which that node is the single validator. This permits rapid prototyping and evaluation of Kwil DB functionality.

For example, to create a node configuration for a new network in a node root folder at ~/.kwild-new:

$ kwil-admin setup init --root-dir ~/.kwild-new
Initialized node in /home/user/.kwild-new

The above command also generated a new config.toml and private_key file in the node directory.

Additional nodes may join this new network by specifying the existing node as a persistent peer in kwild's configuration and in the validators section of the genesis configuration. See Kwil Daemon Configuration for more information on node setup.

Creating a New Test Network of Several Nodes

The setup testnet command is used to create multiple node configurations, all with the same genesis config, and pre-configured to connect to each other. This command has several options:

kwil-admin setup testnet [--validators V] [--non-validators N] [--config FILE]
  [--output-dir DIR] [--node-dir-prefix PRE] [--hostname-prefix PRE]
  [--hostname-suffix SUF] [--starting-ip IP] [--hostnames HOSTNAMES] [--p2p-port PORT]

There are defaults for each flag, with the output writing to a folder called .testnet in the current folder. For example, the following command creates a new test network with 8 total nodes comprising 4 validators and 4 non-validators:

$ kwil-admin setup testnet -o ~/.kwild-testnet-xyz
Successfully initialized 3 node directories: /home/jon/.kwild-testnet-xyz

$ tree ~/.kwild-testnet-xyz
/home/user/.kwild-testnet-xyz
├── node0
│   ├── abci
│   │   ├── config
│   │   │   └── genesis.json
│   │   └── data
│   ├── config.toml
│   └── private_key
├── node1
│   ├── abci
│   │   ├── config
│   │   │   └── genesis.json
...

The config files for each of the nodes will specify all of the other nodes as persistent peers so that they will connect to each other on startup. This is generally only practical for small test networks with fewer than 12 nodes.

For more information on usage, configurations, and more, use the --help flag:

kwil-admin setup testnet --help

Updating Genesis Config with Initial Postgres Data

If preparing a network with initial databases, it is required to update the "app hash" in kwild's genesis configuration to reflect the initial state of a Postgres database. The syntax is:

kwil-admin setup genesis-hash [--genesis GENESIS] [--root-dir ROOTDIR] [--snapshot SNAPSHOT] \
  [--dbname DBNAME] [--host HOST] [--port PORT] [--user USER] [--password PASSWORD]

Both inputs are optional, using default paths. GENESIS is the path to the genesis file to patch, which is ~/.kwild/abci/config/genesis.json by default. The ROOTDIR argument is the root directory of a node, which is ~/.kwild by default. Alternatively, configurations for a Postgres connection can be provided, or a path to a snapshot file can be specified. Use the --help flag for more information.

Resetting All Application Data

To delete all of a Kwil node's data files, use the reset command.

WARNING: This command should not be used on production systems. This should only be used to reset disposable test nodes.

kwil-admin setup reset [--root-dir DIR] [--force] [--dbname DBNAME] [--host HOST] \
  [--port PORT] [--user USER] [--password PASSWORD]

This command only requires one: (a) --root-dir to specify a node root directory containing the files to reset, or (b) --force to automatically reset the files in the default node root directory at ~/.kwild.

Extra Postgres configurations can be provided if needed, but the command will attempt to connect using the configurations in the config.toml file in the node root.