- You have Ubuntu 18.04 or 20.04 installed
- You're just a wee bit comfortable with the command line
The installation steps below will help you setup a synced (depending on your internet connection and hardware) Chainweb node in under 1 hour. Please follow the steps as outlined below. If you know what you're doing, then you don't need to follow to a T.
First things first -- we want to update our server. We do this with the following command:
sudo apt-get update -y && sudo apt-get upgrade -y
Once that's done, we can proceed to node installation.
Chainweb node requires some dependencies that will need to be installed. We will install them with the command below:
sudo apt-get install -y librocksdb-dev zlib1g-dev libtinfo-dev libsqlite3-dev libz3-dev
The next step is to create a directory where chainweb-node binary will reside.
mkdir ~/kadena && cd ~/kadena
We will need to download the chainweb-node binary for Ubuntu 18.04 / 20.04 from the Kadena Github repository. Note that the link I will be using for this download may not work when you read this. To get the link to the latest binary release, click here, copy the direct link to the Chainweb binary for Ubuntu 18.04 or 20.04 (Ubuntu version) and replace the link after wget (below) with it.
NOTE: download the appropriate binary for your OS version. If you're on 18.04, download the binary for that version. If you're on 20.04, do same.
wget https://github.com/kadena-io/chainweb-node/releases/download/2.12/chainweb-2.12.ghc-8.10.7.ubuntu-18.04.0aba2d1.tar.gz
Remember to change the link in the command above to the latest release you copied from here.
Next, we will extract the newly downloaded file
tar -xvzf chainweb-2.12.ghc-8.10.7.ubuntu-18.04.0aba2d1.tar.gz
The next step is to create a YAML config file that contains preferences, settings and options that the chainweb-node will run off of.
touch ~/kadena/config.yaml && nano ~/kadena/config.yaml
The command above will create a file with the name config.yaml and subsequently open that file in a text editor (nano).
Paste the content below in nano.
# noted otherwise values are set to the default.
#
# The default configuration file of any of chainweb-node can be generated by
# calling chainweb-node with the option '--print-config'.
#
# An existing, possibly outdated, configuration file 'myconfig.yaml' can be upgraded to match a
# new chainweb-node version by running chainweb-node as:
#
# 'chainweb-node --config-file=myconfig.yaml --print-config > newconfig.yaml'
#
# A documented list of command line options can be optained by calling
# chainweb-node with the command line option '--help'.
# --- General Settings --- #
chainweb:
# The defining value of the network. To change this means being on a
# completely independent Chainweb.
chainwebVersion: mainnet01
# All unrestricted database read access in in local pact calls.
allowReadsInLocal: false
# Enables the Rosetta API
rosetta: false
# The number of requests allowed per second per client to certain endpoints.
# If these limits are crossed, you will receive a 429 HTTP error.
throttling:
# Overall limit.
global: 200.0
# Pact `/local` calls.
local: 0.1
# `/mining/work` calls.
mining: 10
# `PUT /cut/peer` calls.
putPeer: 21
# Revalidate payload hashes when replaying pact history. This can be used to
# verify the consistency of the chain database with respect to payload
# validation when rebuilding the pact database.
validateHashesOnReplay: false
# The length of the pact service queue (per chain).
pactQueueSize: 2000
# Settings for how a Node can provide work for remote miners.
mining:
# Settings for how a Node can provide work for remote miners.
coordination:
enabled: false
# `private` or `public`. `public` is considered deprecated.
mode: private
# The number of `/mining/work` calls that can be made in total over a 5
# minute period.
limit: 1200
# limits the number of open mining update streams
updateStreamLimit: 2000
# timeout after which mining update stream are closed by the server.
# The connection is left open so that clients can reconnect without
# overhead.
updateStreamTimeout: 240
# When `mode: private`, this is a list of miner account names who are
# allowed to have work generated for them.
miners:
- account: k:yourAccountHere
predicate: keys-all
public-keys:
- yourPublicKeyHere
# Enables single-core mining in the node process. ONLY USED FOR TESTING.
# This feature may be removed in future versions.
nodeMining:
miner:
account: ''
predicate: keys-all
public-keys: []
enabled: false
p2p:
# Your node's network identity.
peer:
# Filepath to the `fullchain.pem` of the certificate of your domain.
# If `null`, this will be auto-generated.
# Only one of `certifcateChain` or `certificateChainFile` is used.
certificateChainFile: null
# The certificate chain of your domain. If `null`, this is auto-generated.
# Only one of `certifcateChain` or `certificateChainFile` is used.
certificateChain: null
# Filepath to the `privkey.pem` of the certificate of your domain.
# If `null`, this will be auto-generated. Only one of `key` or `keyFile` is used.
keyFile: null
# The private key of the certificate of your domain. If `null`, this will
# be auto-generated. Only one of `key` or `keyFile` is used.
key: null
# Network interface that the node listens on. `*` means that the node
# listens on all available interfaces.
interface: '*'
# You. Your node must be reachable from the public internet. If the node
# is in a local network behind a NAT device / router, you must configure
# appropriate port forwarding and the external and internal ports must be
# the same.
hostaddress:
# This should be your public IP or domain name. It must be reachable
# from the internet.
hostname: xxx.xxx.xxx.xxx
# The port you'd like to run the Node on. Any port is fine as long as it
# is publicly available.
port: 2022
# the maximum number of peers that this node maintains
maxPeerCount: 50
# When `true`, only communicates with peers specified in the `peers` list.
# Intended for "focused" catch up.
private: false
# When this is set to true, any builtin bootstrap nodes are ignored. In that
# case you must configure a set of initial peers. Otherwise the node won't
# be able to join the network.
ignoreBootstrapNodes: false
# The maximum number of peers to connect to at any one time.
maxSessionCount: 10
# The number of seconds to spend connected to a single peer.
# Don't alter this unless you know what you're doing.
sessionTimeout: 240
# Initial peers to connect to in order to join the network for the first time.
# These will share more peers and block data to your Node.
peers:
# This is the list of bootstrap nodes that is operated by Kadena. We
# recommend to use these nodes as trusted initial entry points into the P2P
# network. But any other *trusted* node in the network will work.
- address:
hostname: us-w1.chainweb.com
port: 443
id: null
- address:
hostname: us-w2.chainweb.com
port: 443
id: null
- address:
hostname: us-w3.chainweb.com
port: 443
id: null
- address:
hostname: us-e1.chainweb.com
port: 443
id: null
- address:
hostname: us-e2.chainweb.com
port: 443
id: null
- address:
hostname: us-e3.chainweb.com
port: 443
id: null
- address:
hostname: fr1.chainweb.com
port: 443
id: null
- address:
hostname: fr2.chainweb.com
port: 443
id: null
- address:
hostname: fr3.chainweb.com
port: 443
id: null
- address:
hostname: jp1.chainweb.com
port: 443
id: null
- address:
hostname: jp2.chainweb.com
port: 443
id: null
- address:
hostname: jp3.chainweb.com
port: 443
id: null
# Enables the transaction index. This is required for all production nodes.
transactionIndex:
enabled: true
configuration: {}
# The gas limit for newly mined blocks. Only relevant for mining nodes and
# pools.
gasLimitOfBlock: 150000
# A limit of the number of blocks per chain that this node is willing to
# discard during a chain reorg. Any reorg with a fork point of larger depth
# would cause the node process to exit and would require manual intervention.
reorgLimit: 480
# If `true`, allow your node to feed data to a block explorer.
headerStream: false
# Configuration of the P2P network for mempools
mempoolP2p:
enabled: true
configuration:
pollInterval: 30
maxSessionCount: 6
sessionTimeout: 300
# Whether the mempool reintroduces orphaned transactions.
reintroTxs: true
# Related to Cut DB management and synchronization between peers.
cuts:
# If `true`, delete block data that is not part of the main chain on node
# startup. Possible values are:
# - none: no data is deleted
# - headers: orphan block headers are deleted, but payloads are kept (fast)
# - headers-checked: like headers, but also verifies the complete chain
# Merkle tree, including payloads. (several minutes)
# - full: like headers, but also deletes unused payloads (30 min)
pruneChainDatabase: none
# The amount of microseconds to wait before abandoning an attempt to fully
# sync a Cut from some peer.
# Don't alter this unless you know what you're doing.
fetchTimeout: 3000000
# Force your node back to a certain Cut height, and have it resync from there.
# This requires disabling the rewind protection and shouldn't be used in
# production.
initialCutHeightLimit: null
# --- Logging --- #
logging:
# All structural (JSON, etc.) logs.
telemetryBackend:
enabled: true
configuration:
# the output handle
handle: stdout
# enable colored logs. 'auto' uses colors when the output handle is a
# terminal.
color: auto
# `text` or `json`
format: text
# Simple text logs.
backend:
# the output handle
handle: stdout
# enable colored logs. 'auto' uses colors when the output handle is a
# terminal.
color: auto
# `text` or `json`
format: text
logger:
# The overall log level.
log_level: info
# The size of the log message queue.
queue_size: 1000
# Time to wait in milliseconds after a logger backend failure occured
exception_wait: 1000
# Timeout for flushing the log message queue on exit
exit_timeout: 1000000
# Additional log scope tags that are added to all log messages
scope: []
# Maximal number of backend failures before and exception is raised
exception_limit: 10
# What to do with log messages when the logger queue is full. The default is
# to discard messages and log the number of discarded messages. Alternative
# values are 'block' and 'raise'.
policy: discard
# An indentifier for the node that is added to all log messages
clusterId: null
# Additional filter for log messages
filter:
# Rules for filtering logs. The filter rules apply only to already generated
# log messages. For instance, if the global log level is 'warn', a filter rules
# with level 'info' has no effect.
rules:
# The following are a set of example rules
- key: component
value: cut-monitor
level: info
- key: component
value: pact-tx-replay
level: info
- key: component
value: connection-manager
level: warn
- key: component
value: miner
level: info
- key: component
value: mempool-sync
level: info
- key: component
value: local-handler
level: info
# the default log level that is used for all log messages that don't match
# any of the rules.
default: info
# --- Miscellaneous Settings --- #
# The directory location of the databases. The default is operating system dependent.
databaseDirectory: null
# If `true`, deletes your entire database upon startup.
resetChainDatabases: false
NOTE: Do not add extra spaces or delete spaces in the config file above; this most likely will result in an error.
The main parts of this config you're going to modify are:
-
mining coordination to true -- if you're going to be mining on / to your node
-
Also, if you're going to be mining on / to this node, you need to enter values for account and public-keys.
- account: k:yourAccountHere- yourPublicKeyHere -
hostname - change this to your public facing IP address get your IP address here
-
Deffault port is 443. I want my node to use a different port, so I'll use port 2022. You can choose a different port, it's just a matter of preference.
Save the file CTRL + O, then press ENTER and then exit nano with CTRL + X
At this point, we are pretty much done with the installation. We can choose to start the node with the command below. This will sync your node with the blockchain from scratch.
./chainweb-node --config-file=config.yaml
A fresh node will need to download the whole Kadena blockchain. This process can take several days to a week. Instead of downloading from scratch, we will download a snapshot database of the Kadena blockhain. This snapshot will save us a LOT of time.
Kadena blockhain data is stored in this directory: ~/.local/share/chainweb-node/mainnet01/0/. The chainweb-node stores and retrieves data from this directory.
We will create this directory by issuing the following command:
NOTE: if you started chainweb-node with the command above, you will need to stop it (CTRL + C) before continuing
mkdir -p ~/.local/share/chainweb-node/mainnet01/0/ && cd ~/.local/share/chainweb-node/mainnet01/0
From here, we will download a compressed DB snapshot file.
wget https://kadena-node-db.s3.us-east-2.amazonaws.com/db-chainweb-node-ubuntu.18.04-latest.tar.gz
As of the time I am writing this, the snapshot was around 36 gigabytes.
Once downloaded (about 10-30 minutes depending on your internet connection), we will extract.
tar -xvzf db-chainweb-node-ubuntu.18.04-latest.tar.gz
Depending on your hardware, this should take about 10 to 15 minutes, or longer if you're using commodity hardware with low specs.
After extracting the compressed file, you should have 3 files in this directory: db-chainweb-node-ubuntu.18.04-latest.tar.gz, rocksDb, and sqlite. If you didn't experience any errors extracting the DB snapshot, it is safe to delete this file to free up 36 gigabytes of space.
If you want to delete, do this:
rm db-chainweb-node-ubuntu.18.04-latest.tar.gz
Next, we will start our node. Instead of downloading the DB from scratch, it will begin at the point of the DB snapshot.
cd ~/kadena
START NODE
./chainweb-node --config-file=config.yaml
Give it about 1-2 minutes to fully get going. Then check your current height by going here: https://YOUR-IP-ADDRERSS:2022/chainweb/0.0/mainnet01/cut
You should be getting similar text / json as what I have below...
{"hashes":{"12":{"height":2293156,"hash":"RxSkvum-9PxEbZKUsYp_IJdwJtwo2BbumHLyEe0dB48"},"13":{"height":2293156,"hash":"ZL3J_RF3648kbMoyIHpH03C8buhH9U20MafrxoqqWTY"},"14":{"height":2293157,"hash":"txoQfBcq_JDo2giXaU3M19GYElc7cQutMKEGtCuy7ns"},"15":{"height":2293156,"hash":"qlvvYnC_Avp78v9-ClOK-DtTXpyMVvfcRPSDYDT8jUA"},"8":{"height":2293155,"hash":"oFasqD1y_OTBQvayAN25Pm9aRlS6MrLJB1bWGlF0E1Y"},... truncated by me
Every few second, you can refresh the page -- you should see the height value go up 1 or 2. This tells you your node is syncing. To verify that your node is fully synced, go here: https://explorer.chainweb.com/mainnet and compare the block height with yours. If your block height is lower than what's on explorer.chainweb.com, then your node isn't fully synced. If your block height tracks with the values on the explorer, then you're fully synced.
From experience, the snapshot DB is usually under 2000 blocks below current height. It usually takes under 30 minutes to fully sync.
Running chainweb-node as a service presents multiple advantages. Chief among these advantages is autostart at startup and crash.
To run chainweb-node as a service, do the following:
cd ~
sudo touch /etc/systemd/system/chainweb-node.service && sudo nano /etc/systemd/system/chainweb-node.service
Paste the following in nano -- make sure you replace "yourUsername" with your username.
[Unit]
Description=Kadena Chainweb Node
[Service]
User=yourUsername
Type=simple
WorkingDirectory=/home/yourUsername/kadena
ExecStart=/home/yourUsername/kadena/chainweb-node --config-file=/home/yourUsername/kadena/config.yaml
Restart=always
RestartSec=15
[Install]
WantedBy=multi-user.target
Save the file CTRL + O, then press ENTER and then exit nano with CTRL + X
The next step is to reload systemd and enable the service we just created. Do that with this command:
sudo systemctl daemon-reload && sudo systemctl enable chainweb-node
Now you can start chainweb-node as a service.
To start Chainweb node:
sudo systemctl start chainweb-node
To check status of Chainweb node:
sudo systemctl status chainweb-node
To stop Chainweb Node:
sudo systemctl stop chainweb-node
To restart Chainweb node:
sudo systemctl restart chainweb-node
sudo systemctl stop chainweb-node
cd ~/kadena && wget http://linkToBinaryFile.tar.gz
Get latest binary release from here.
tar -xvzf theFileNameOfNewlyDownoadedBinary.tar.gz
Once extracted, start the service again.
sudo systemctl start chaonweb-node
CTRL + C this will stop chainweb-node
cd ~/kadena && wget http://linkToBinaryFile.tar.gz
Get latest binary release from here.
tar -xvzf theFileNameOfNewlyDownoadedBinary.tar.gz
Start chainweb-node again
./chainweb-node --config-file=config.yaml
I wrote this step-by-step guide to provide an easy to understand approach to installing a Chainweb node. I tried to simplify things as much as I could. If you have any feedback on how I can improve this guide, I would be happy to hear from you.
**Olay - find me on Kadena Discord:
Thanos: https://github.com/Thanos420NoScope/node-setup
Leo Fitz Docker Guide (Ubuntu): https://medium.com/@solvman/docker-compose-setup-for-a-chainweb-mining-node-on-ubuntu-20-04-2ca0e13ea40b
Leo Fitz Docker Guide (Windows): https://medium.com/@solvman/docker-compose-setup-for-a-chainweb-mining-node-on-windows-10-3b11481e3aad