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.
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
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 -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 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
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.
kwild --root-dir ./kwil-testnet/node0 --app.pg-db-port 5440
kwild --root-dir ./kwil-testnet/node1 --app.pg-db-port 5441
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 JSON-RPC 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.