How to setup a Q Root Node
Setup your Server
The Q Root Node is required to run on a server or (virtual) machine on linux. One possibility is to use a local machine, alternatively you can use a cloud instance on AWS for example. A good external tutorial on how to get started with Ethereum on AWS can be found here. Any other linux machine will work as well if it meets the following requirements:
- Linux machine with SSH access
- Min. 2(v)Cores (x86), 20 GB storage and 2 GB RAM
- Installed applications: docker, docker-compose, git (optional)
If you are running Ubuntu, use these commands to install all mentioned required applications using
$ sudo apt-get update
$ sudo apt-get install git
$ sudo apt-get install docker
$ sudo apt-get install docker-compose
Please check corresponding online resources for your operating system and the third party application you want to install for further questions.
Clone the repository
$ git clone https://gitlab.com/q-dev/testnet-public-tools
and go to the
$ cd testnet-public-tools/testnet-rootnode
This directory contains the
docker-compose.yaml file for quick launching of the root node with preconfigurations using
.env (which can be created from
Note: If git is not installed on your machine, you can manually copy all files from public repo
testnet-public-toolsonto your machine. Using git is much more comfortable, since it allows pulling file updates with one single command.
Set Password for Keystore File
To act as a root node, your node needs a keypair to sign transactions and L0 governance messages. First, create a
/keystore directory with
$ mkdir keystore
then create a file
$ nano keystore/pwd.txt
then set a password that will be used for future account unlocking by entering it into
pwd.txt. The password needs to be entered at the beginning of the file. Save your changes with
CTRL+O, then close nano with
CTRL+X (if you use a different editor, commands might be different).
Generate a Keypair
Assuming you are in
/testnet-rootnode directory, issue this command in order to generate a keypair:
$ docker-compose run --rm --entrypoint "geth account new --datadir=/data --password=/data/keystore/pwd.txt" testnet-rootnode
The output of this command should look like this:
Your new key was generated Public address of the key: 0xb3FF24F818b0ff6Cc50de951bcB8f86b52287dac Path of the secret key file: /data/keystore/UTC--2021-01-18T11-36-28.705754426Z--b3ff24f818b0ff6cc50de951bcb8f86b52287dac - You can share your public address with anyone. Others need it to interact with you. - You must NEVER share the secret key with anyone! The key controls access to your funds! - You must BACKUP your key file! Without the key, it's impossible to access account funds! - You must REMEMBER your password! Without the password, it's impossible to decrypt the key!
This way, a new private key is generated and stored in docker container in
data/keystore directory encrypted with password from
pwd.txt file. In our example, 0xb3FF24F818b0ff6Cc50de951bcB8f86b52287DAc (you will have a different value) is the address corresponding to the newly generated private key.
Alternatively, you can generate a secret key pair and corresponding file here and save it to the
/keystore directory manually.
Also you may use
create-geth-private-key.js script in
Whether you chose to provide your own vanity keys or use the above command to create a keypair, please ensure that the directory
/keystore contains the following files:
testnet-rootnode | ... | ... └ keystore | UTC--2021-01-18T11-36-28.705754426Z--b3ff24f818b0ff6cc50de951bcb8f86b52287dac | pwd.txt
Note: Following our example, pwd.txt contains the password to encrypted file "UTC--2021-01-18T11-36-28.705754426Z--b3ff24f818b0ff6cc50de951bcb8f86b52287dac" in clear text.
If you want to change the password in the future, you need to stop the node first.
$ docker-compose down
Then start password reset procedure with
$ docker-compose run testnet-rootnode --datadir /data account update 0xb3ff24f818b0ff6cc50de951bcb8f86b52287dac
Note: You need to remove address 0xb3ff24f818b0ff6cc50de951bcb8f86b52287dac and add your account address instead.
.env and edit this file in
$ cp .env.example .env $ nano .env
Enter your (newly created) root node address without leading 0x here:
# your q address here (without leading 0x) ADDRESS=b3FF24F818b0ff6Cc50de951bcB8f86b52287DAc
Then add your machines public IP address (please make sure your machine is reachable at the corresponding IP since it's required for discoverability by other network participants) here:
# your public IP address here IP=220.127.116.11
Optionally choose a port for p2p protocol or just leave default value (use different ports for every node you are running):
# the port you want to use for p2p communication (default is 30313) EXT_PORT=30313
.env file should look somehow like this:
# docker image for q client QCLIENT_IMAGE=qblockchain/q-client:1.2.1 # your q address here (without leading 0x) ADDRESS=b3FF24F818b0ff6Cc50de951bcB8f86b52287DAc # your public IP address here IP=18.104.22.168 # the port you want to use for p2p communication (default is 30313) EXT_PORT=30313 # the initial root node set if never connected before INITIALROOTS=0xB6fs1878e60B7D9152695c1b3D190c3a3DC,0x3313ba4c7EbDa55C038316C77679b2909da7a5 # only root lists later than this will be considered for updates ROOTTIMESTAMP=1647418453
Add your Root Node to https://stats.qtestnet.org
If you want your root node to report to the network statistics, you can add an additional flag to the node entrypoint within file
/rootnode/docker-compose.yaml, it should look like this:
testnet-rootnode: image: $QCLIENT_IMAGE entrypoint: ["geth", "--ethstats=<Your_RootNode_Name>:<Testnet_access_key>@stats.qtestnet.org", "--datadir=/data", ...]
<Your_RootNode_Name> can be chosen arbitrarily. It will be displayed in the statistics and could be something like "OurCoolCompany - 0xABC123". You can use special characters, emojis as well as spaces. We would appreciate to include the beginning of your Root Node Q address, so there is a link between your client and your address.
Launch Root Node
Now launch your root node using docker-compose file in rootnode directory:
$ docker-compose up -d
Check your nodes real-time logs with the following command:
$ docker-compose logs -f --tail "100"
Find additional peers
In case your client can't connect with the default configuration, we recommend that you add an additional flag referring to one of our additional peers (
testnet-rootnode: image: $QCLIENT_IMAGE entrypoint: ["geth", "--bootnodes=$BOOTNODE1_ADDR,$BOOTNODE2_ADDR,$BOOTNODE3_ADDR", "--datadir=/data", ...]
Get Q Tokens
In order to become a root node, you will need to make an onchain proposal to add yourself to the root node panel. You need Q tokens for this. For Q testnet, you can get some Q using the faucet. Check the faucet documentation for more information. Finally, please verify that tokens were sent by looking up your address within Block Explorer.
Put Stake in Rootnodes Contract
As was mentioned previously, you should put stake to rootnodes contract in order to become a rootnode.
You can use the dApp "Your HQ" that can be found at https://hq.qtestnet.org. Go to
Consensus Services ->
Root Node Staking for stake management. Also, you may want to check our Consensus Services documentation.
Updating Q-Client & Docker Images
To upgrade the node follow the instructions Upgrade Node