Guide: Running an Avisen node

The official Avisen client is deployed to https://hub.docker.com/repository/docker/avisen/client-kt/general.

For starting out, we recommend connecting with an official test network or starting your own. See boot nodes for official boot node addresses.

Running the first time

Docker Compose

We recommend running a node using Docker Compose. This will help automate the start-up of the database and node and make it easier to set the client’s many environment variables.

Choose a node type

An Avisen node can start in many different nodes:

UTILITY: a node that is running without a blockchain, network, or database. Useful for generating key-pairs and working with Avisen's local utilities. Most REST API endpoints are disabled in this mode, but you still get access to the crypto utilities. A database is not used in this mode.

REPLICA: a node that is a full replica of the network and blockchain. Receives updates from publisher nodes.

PUBLISHER: a node that has the ability to publish transactions (articles), mint blocks, and broadcast new blocks to the network. Requires ECDSA signing keys and permission from the blockchain to publish.

Choose run behavior

An avisen node can start up its own blockchain or join an existing network. This is handled by the optional BOOT_NODE environment variable. If it is set, the node will attempt to join the boot node’s network and download its blockchain. If it is not set, the node will start its own blockchain with a Genesis block.

Prepare the database

Running a non-utility node requires a running PostgreSQL database at version 17 or higher.

The chosen database user must have permissions to create tables, insert data, and select data in the default schema. This can be done by connecting directly to the database and running the following commands:

GRANT ALL PRIVILEGES ON DATABASE YOUR_DATABASE TO YOUR_USERNAME;

GRANT ALL ON SCHEMA public TO YOUR_USERNAME;

Fulfill environment variables

The client requires many environment variables. It is important to take note of which ones are required for the mode you are running your node in.

DB_URL: the url corresponding to the backing PostgreSQL database. There should only be one database per node. Not required in UTILITY mode.

DB_USER: the username when connecting to the database. This should not be the admin user. Not required in UTILITY mode.

DB_PASS: the password for the database user. Not required in UTILITY mode.

NODE_ADDRESS: the url address (host, port, etc.) for accessing the node. Broadcast to the other nodes in the network. Required. This should be a static IP address or url.

BOOT_NODE: the url address (host, port, etc.) for accessing another node to populate the blockchain and network pool. If not populated, the node will run in genesis mode. (See Network/Starting up for the first time) Not required in UTILITY mode.

NODE_MODE: the mode to run the node in:

PUBLISHER: a node that has the ability to publish transactions (articles), mint blocks, and broadcast new blocks to the network.

REPLICA: a node that is a full replica of the network and blockchain. Receives updates from publisher nodes.

UTILITY: a node that is running without a blockchain, network, or database. Useful for generating key-pairs and working with Avisen's local utilities. Most REST API endpoints are disabled in this mode. Database connection information is not required in this mode.

NETWORK_ID: a shared id that prevents cross-network activity. Not required in UTILITY mode.

PORT: the given port for the app to run on. Defaults to 8081 if not provided. When running in Docker, the port must be set to 8081.

PUBLISHER_SIGNING_KEY: A private ECDSA key used for signing blocks. Required if running a node in PUBLISHER mode. Not required in UTILITY mode.

PUBLISHER_PUBLIC_KEY: A public ECDSA key used as property of a block. Required if running a node in PUBLISHER mode. Not required in UTILITY mode.

Start the app!

Start the node using your preferred Docker method. Check the logs for errors and success. If you are having trouble starting a node, head over to our official Discord server for help.

Connect to the node

See this guide for more information on how to connect to a node. Log issues to our github page or our discord.