Skip to main content

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 either Running a Kwil Node or the Production Deployment guide.

Prerequisites​

Ensure that you have the following prerequisites installed:

  • Docker
  • kwild
  • An Ethereum address that can be designated as the database's owner

Installation​

To run either a single Kwil node, or a network of nodes, you will need to download the kwild binary. 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 start --autogen --db-owner <YOUR_ETHEREUM_ADDRESS>
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. See the Production Guide page for more information.

Cleanup​

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

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

# 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 kwild to generate multiple node configs.

Generate Configs​

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

kwild setup testnet -v 3 -u --out-dir ./kwil-testnet --db-owner <YOUR_ETHEREUM_ADDRESS>

This creates three nodes that can run on the same host for evaluation. Note the -u flag, which assigns unique ports for each node. 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 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 -v node0 node1 node2 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 flag to point to the directory where the node config is located.

Terminal 1
kwild start --root ./kwil-testnet/node0 --db.port 5440
Terminal 2
kwild start --root ./kwil-testnet/node1 --db.port 5441
Terminal 3
kwild start --root ./kwil-testnet/node2 --db.port 5442

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

Cleanup​

To clean up when done testing, delete the ./kwil-testnet folder and the Postgres containers:

# Remove kwild node data
rm -rf ./kwil-testnet
# Stop and remove the postgres containers and their anonymous volumes
docker container rm -f -v node0 node1 node2

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.