Node Quickstart

This page demonstrates Kwil DB in both single node and multi-node configurations using new randomly generated chains and validator keys. Use this to evaluate and test kwild. To prepare a production deployment, see Installation and Running a Kwil Node

Installation

To run either a single Kwil node, or a network of nodes, you will need to download the binaries. Kwil releases binaries on Github.

Kwil also requires a dedicated PostgreSQL host configured for kwild.

See the Installation page for details.

Single Node

Start

First ensure that PostgreSQL is running and configured for kwild. For the quickstart, just:

docker run -d -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    kwildb/postgres:latest

To run a single node, simply use the kwild binary with the --autogen flag. This will automatically generate a genesis file, private key, and more in the ~/.kwild directory.

kwild --autogen

note

The --autogen flag generates a random chain ID, which is the network's identity, as well as a new initial validator private key. The node will be the one initial validator. As such, this mode is primarily useful for a quick deployment for evaluation and testing; production networks will define their own chain ID and initial validator set.

Cleanup

To clean up when done testing, delete the ~/.kwild folder and the Postgres container:

# Remove kwild node data
rm ~/.kwild -rf

# Stop and remove the postgres container
docker container stop kwil-postgres
docker container rm -f kwil-postgres

Multi-Node

To run a local Kwil network, you can use the kwil-admin tool to generate multiple node configs.

Generate Configs

To generate the configs for 3 validators in ./kwil-testnet, run:

kwil-admin setup testnet -v 3 --hostnames "localhost,localhost,localhost" --output-dir ./kwil-testnet

This creates three nodes that can run on the same host for evaluation. A production network would comprise nodes on different machines, but with the same genesis.json file.

Run Nodes

First start postgres containers for each of the nodes. Use the following commands to start all three running in the background, with different named volumes, and listening on ports 5440-5442.

docker run -d -p 5440:5432 -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    --name node0 -d kwildb/postgres:latest
docker run -d -p 5441:5432 -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    --name node1 -d kwildb/postgres:latest
docker run -d -p 5442:5432 -e "POSTGRES_HOST_AUTH_METHOD=trust" \
    --name node2 -d kwildb/postgres:latest

tip

Use docker container ls to check the postgres container status. When done testing kwild, use docker container rm -f node0 node1 node2 and docker volume rm kwil0-testnet-pgdata kwil1-testnet-pgdata kwil2-testnet-pgdata to stop and delete them.

To run the nodes, we can use the kwild binary in 3 separate terminals. We will need to specify the --root_dir flag to point to the directory where the node config is located.

Terminal 1

kwild --root-dir ./kwil-testnet/node0 --app.pg-db-port 5440

Terminal 2

kwild --root-dir ./kwil-testnet/node1 --app.pg-db-port 5441

Terminal 3

kwild --root-dir ./kwil-testnet/node2 --app.pg-db-port 5442

Once the nodes are running, they will begin mining blocks. You can now connect to their gRPC and HTTP endpoints to interact with your local network.

For Developers

Given a clone of the source code repository and development tooling, there are other automated options for starting nodes for testing in the README. In particular, a Docker Compose service is defined in deployments/compose/kwil that automatically starts containers for both a single node with --autogen and a separate container for postgres. For a multi-node development environment, the command task dev:testnet:up will start several nodes in a network configuration.