Aptos Validator and Fullnode Install Guide

First Published August 26th, 2022

This is a guide for setting up a validator and a full node for the Third Aptos Incentivized Testnet (AIT-3). This guide covers the installation and configuration methods needed for Docker. If you are interested in node monitoring please look at our Aptos Node Monitoring Guide.

A Testnet on any blockchain can be a very fluid situation and code, processes, and techniques can rapidly evolve. We will take steps to keep this guide updated with critical changes, however we can not promise that this will be up to date at all times. Furthermore, once AIT-3 is complete, this guide will likely be irrelevant. Please leave comments if you have questions!

The first step is to create a validator, then you can create a fullnode and attach the fullnode to your validator. It is highly recommended that you run the validator and fullnode on separate servers. If you try and run both on the same server you will need to adjust for port collisions and you may have severe performance degradation due to heavy resource loads.

A Note on Aptos Keys

Aptos has a truly unique key architecture which allows for very flexible configurations. There are three primary keys Owner, Voter, and Operator. A validator requires all three of these keys, however each key can be controlled by separate entities. This represents the simplest case of an independently operated validator that is staking its own tokens.

The purpose and scope of this guide is to get operators up and running in AIT3 as simply and quickly as possible, so we will only cover the simple case discussed above. We have provided two more complex key configurations for your reference:

A slightly more complex key configuration is that of an Investor and an Operator. In this case an Investor has hired a third party to operate a validator on their behalf. In this case, an investor would own their own Aptos coins and would generate and control the owner and voter keys, never sharing any private keys with their operator. The operator would then generate their own operator key, never sharing their private keys with their Investor client.

The most complex key configuration is that of an Investor, Voter, and Operator. In this case three independent parties each control one of the three keys and never share their private keys among the group.

For both complex cases, setup and configuration of a validator requires coordination between all parties and is more complex than the simple case.

Prerequisites

We strongly recommend that you run your node from a cloud provider or from a data center. Under no circumstances should you attempt to run a node from your home. The vast majority of homes do not have redundant power and internet connectivity, which means that it is likely that your node will be disconnected from the network at some point in time and you will not earn rewards.

A Quick Note on Cloud Providers

Generally speaking the major cloud providers such as AWS, Google (GCP), and Azure are heavily used by validators across the entire cryptoverse. Feel free to use a major provider, but in the interest of decentralization we ask you to consider a mid-tier cloud provider such as VULTR, OVH, Contabo, Digital Ocean, MEVSPACE, or Linode.

Hardware Requirements

As of the time of this writing, the hardware requirements for AIT-3 have noticeably increased from AIT-2. Please check the official documentation for the most up to date information.

• CPU: 8 cores 2.8GHz or faster (Intel Xeon Skylake or newer).
• Memory: 23GiB RAM.
• At least 300GB SSD (2TB NVMe is preferred)

Operating System

This guide has been tested on Ubuntu 20.04.

User Permissions

This guide is designed to run from the root user. Generally speaking running any production processes from the root user is a bad idea. If you decide to run Aptos from a non-root user (which we recommend) then you will likely need to modify the directory structures in the docker-compose.yaml validator.yaml and fullnode.yaml files to point to the appropriate user directories.

Install the Petra Wallet Extension

Visit the Petra Wallet extension page and install the plugin. Then generate a new wallet and write down and save your mnemonic key.

Alternatively, you can follow the official install instructions:

Install Petra Extension | Aptos Docs

Now that the wallet is created you can close it and move on to the next section. You will need to go back to your wallet later in this process.

Initial Setup for Validator

Start by launching a server for your validator.

Once you have logged into your Ubuntu 20.04 virtual server as root, the first step is to update your OS and install packages:

sudo apt-get update -y && sudo apt-get upgrade -y && sudo apt-get install libssl-dev -y && sudo apt-get install fail2ban -y && sudo apt-get install jq -y && sudo apt-get install zip unzip

You will see some purple screens pop up every now again. Just press the ENTER key.

Install Docker

sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"

apt-cache policy docker-ce
sudo apt install docker-ce -y

Now check the status of the docker service to ensure that it installed correctly

sudo systemctl status docker

Install Docker Compose

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Check the version of Docker Compose to ensure that it installed correctly. As long as you do not get an error message, it worked.

docker-compose --version

Validator Setup

First, open your firewall so that the node can pass health checks. For this walkthrough we are using UFW (Uncomplicated FireWall). Press Ywhen prompted to restart the firewall.

sudo ufw allow proto tcp from any to any port 6180
sudo ufw allow proto tcp from any to any port 6181
sudo ufw allow proto tcp from any to any port 8080
sudo ufw enable

Then, decide what you will name your node. You will then replace <node name> with your node name and run the commands below.

export WORKSPACE=testnet
export USERNAME=<node name>
mkdir ~/$WORKSPACE
cd ~/$WORKSPACE

Here is an example of what the commands would be if you named your node “kingfisher”.

export WORKSPACE=testnet
export USERNAME=kingfisher
mkdir ~/$WORKSPACE
cd ~/$WORKSPACE

Download docker-compose and validator yaml files

wget -qO docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/main/docker/compose/aptos-node/docker-compose.yaml
wget -qO validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/main/docker/compose/aptos-node/validator.yaml

Edit the docker-compose.yaml and modify the docker image from testnet to testnet_88f936bf40a56768e2dac420e953a0307281c1ba

cd ~/$WORKSPACE
nano docker-compose.yaml

Download and unzip the precompiled Aptos CLI tool

wget https://github.com/aptos-labs/aptos-core/releases/download/aptos-cli-v0.3.2/aptos-cli-0.3.2-Ubuntu-x86_64.zip
unzip aptos-cli-0.3.2-Ubuntu-x86_64.zip

Generate your Aptos validator keys

./aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys

Validator Config

Set the validator configuration. You will need to change the --validator-host and --full-node-host to be either the external IP of each server, or a domain name that is mapped to each server’s IP address.

If you are not running a full node, then remove the --full-node-host line in the set-validator-configuration command.

With Fullnode

./aptos genesis set-validator-configuration \
    --local-repository-dir ~/$WORKSPACE \
    --username $USERNAME \
    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml\
    --validator-host <validator_external_IP_or_domain>:6180 \
    --full-node-host <fullnode_external_IP_or_domain>:6182 \
    --stake-amount 100000000000000

Without Fullnode

./aptos genesis set-validator-configuration \
    --local-repository-dir ~/$WORKSPACE \
    --username $USERNAME \
    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml\
    --validator-host <validator_external_IP_or_domain>:6180 \
    --stake-amount 100000000000000

Generate the layout template

./aptos genesis generate-layout-template --output-file ~/$WORKSPACE/layout.yaml

Edit the layout.yaml file

nano ~/$WORKSPACE/layout.yaml

Then change the root_key: to “D04470F43AB6AEAA4EB616B72128881EEF77346F2075FFE68E14BA7DEBD8095E”

Now change the users: to [“<node-name”]. In the previous example we used kingfisher as our node name.

Then change the chain_id: parameter to 47

To exit nano: press CTL + X then press Y then press ENTER

Check your layout.yaml file one more time

cat ~/$WORKSPACE/layout.yaml

It should look like this:

Download the Move Smart Contract Framework:

wget https://github.com/aptos-labs/aptos-core/releases/download/aptos-framework-v0.3.0/framework.mrb -P ~/$WORKSPACE

Now, initialize your owner profile

./aptos init --profile ait3-owner --rest-url http://ait3.aptosdev.com

You will be prompted for a faucet address, type skip and press ENTER. Then you will be asked for your private wallet key.

Go to the Petra Wallet -> Settings -> Credentials

Then click on your private key. NEVER SHARE THIS KEY WITH ANYONE or they can hijack your wallet.

Now paste the wallet private key into the command prompt and press ENTER.

Initialize Stake Owner

First you will need to locate your operator-address and your voter-address.

To find operator address:

cat ~/$WORKSPACE/$USERNAME/operator.yaml

Copy the address for operator_account_address:

To find voter address:

cat ~/$WORKSPACE/$USERNAME/owner.yaml

Copy the address for voter_account_address:

Now replace <operator-address> and <voter-address> with your addresses in the following command, then execute it. This will bind the operator address and the voter address to your private owner key.

./aptos stake initialize-stake-owner \
  --initial-stake-amount 100000000000000 \
  --operator-address <operator-address> \
  --voter-address <voter-address> \
  --profile ait3-owner

Create Operator Account

Find your operator_account_address (different than the account you used in the previous step).

cat ~/$WORKSPACE/$USERNAME/operator.yaml

Replace the <operator-account> with operator_account_addressin the following command and then execute it.

./aptos account create --account <operator-account> --profile ait3-owner

Now transfer some gas money into this account, do not forget to update the <operator-account> in this command

./aptos account transfer \
--account <operator-account> \
--amount 10000 \
--profile ait3-owner

Bootstrap the Validator

The next step is to download the waypoint.txt and genesis.blob.

cd ~/$WORKSPACE
wget -qO genesis.blob https://raw.githubusercontent.com/aptos-labs/aptos-ait3/main/genesis.blob
wget -qO waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-ait3/main/waypoint.txt

Now you need to update your validator-identity.yaml file by replacing the account_address with your Petra wallet address. You can find the address at the top of the Home menu, or in Settings->Credentials.

cd ~/$WORKSPACE/keys
nano validator-identity.yaml

Replace the account_address: in the yaml file with the wallet address of your Petra wallet.

To exit nano: press CTL + X then press Y then press ENTER

Join the Validator Set

Copy your account_private_key NEVER SHARE THIS KEY!!

cat ~/$WORKSPACE/keys/private-keys.yaml

Initialize your operator profile

./aptos init --profile ait3-operator --rest-url http://ait3.aptosdev.com

You will be prompted for a faucet address, type skip and press ENTER. Then you will be asked for your account_private_key

Now paste the account_private_key into the command prompt and press ENTER.

Check the balance of the operator account.

./aptos account list --profile ait3-operator

If you do not have funds, then send some from your owner account into your operator account.

You will need your Petra wallet address for the next few commands. You can find the address at the top of the Home menu, or in Settings->Credentials.

Replace <owner-address> in the command below with your Petra wallet address and then execute the command.

./aptos node update-validator-network-addresses  \
  --pool-address <owner-address> \
  --operator-config-file ~/$WORKSPACE/$USERNAME/operator.yaml \
  --profile ait3-operator

Replace <owner-address> in the command below with your Petra wallet address and then execute the command.

./aptos node update-consensus-key  \
  --pool-address <owner-address> \
  --operator-config-file ~/$WORKSPACE/$USERNAME/operator.yaml \
  --profile ait3-operator

Replace <owner-address> in the command below with your Petra wallet address and then execute the command.

./aptos node join-validator-set \
  --pool-address <owner-address> \
  --profile ait3-operator \
  --max-gas 4000

Check the chain to see if your node has been added to the wait list to join the active set. Your validator will be added to the set at the beginning of the next epoch. This wait can take up to 2 hours.

To check only your validator, replace <account_address>

./aptos node show-validator-set --profile ait3-operator | jq -r '.Result.active_validators' | grep <account_address>

To see the entire queue

./aptos node show-validator-set --profile ait3-operator | jq -r '.Result.pending_active'

Launch your Validator

Launch your validator with the following commands

cd ~/$WORKSPACE
sudo docker-compose up -d

Check Docker Logs

sudo docker logs -f testnet_validator_1 --tail 60

Setup Complete!

Now you can add node monitoring by following our Aptos Node Monitoring Guide.

Initial Setup for Fullnode

Start by launching a server for your fullnode.

Once you have logged into your Ubuntu 20.04 virtual server as root, the first step is to update your OS and install packages:

sudo apt-get update -y && sudo apt-get upgrade -y && sudo apt-get install fail2ban -y && sudo apt-get install jq -y && sudo apt-get install zip unzip

You will see some purple screens pop up every now again. Just press the ENTER key.

Install Docker

sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
apt-cache policy docker-ce
sudo apt install docker-ce -y

Now check the status of the docker service to ensure that it installed correctly

sudo systemctl status docker

Install Docker Compose

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Check the version of Docker Compose to ensure that it installed correctly. As long as you do not get an error message, it worked.

docker-compose --version

Fullnode Setup

You will need to run through the Initial Setup for Validator and Fullnode at the top of this walkthrough. After initial setup is complete, then come back to this section.

Firewall Config

Open your firewall so that the node can pass health checks. For this walkthrough we are using UFW (Uncomplicated FireWall). Press Ywhen prompted to restart the firewall.

sudo ufw allow proto tcp from any to any port 6181
sudo ufw allow proto tcp from any to any port 6182
sudo ufw allow proto tcp from any to any port 8080
sudo ufw enable

Set up your workspace directory

export FULLNODENAME=<fullnode name>
export WORKSPACE=testnet
mkdir ~/$WORKSPACE
cd ~/$WORKSPACE

Download and unzip the precompiled Aptos CLI tool

wget https://github.com/aptos-labs/aptos-core/releases/download/aptos-cli-v0.3.2/aptos-cli-0.3.2-Ubuntu-x86_64.zip
unzip aptos-cli-0.3.2-Ubuntu-x86_64.zip

Download Fullnode config files

wget -qO docker-compose-fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/main/docker/compose/aptos-node/docker-compose-fullnode.yaml
wget -qO fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/main/docker/compose/aptos-node/fullnode.yaml

Edit the docker-compose-fullnode.yaml and modify the docker image from testnet to testnet_88f936bf40a56768e2dac420e953a0307281c1ba

cd ~/$WORKSPACE
nano docker-compose.yaml

Update the fullnode.yaml file and replace <Validator IP Address> with your validator’s IP address (do not use a domain name if you have one).

sudo nano fullnode.yaml

To exit nano: press CTL + X then press Y then press ENTER

Generate your Aptos Fullnode keys

./aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys

Download the waypoint.txt and genesis.blob.

cd ~/$WORKSPACE
wget -qO genesis.blob https://raw.githubusercontent.com/aptos-labs/aptos-ait3/main/genesis.blob
wget -qO waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-ait3/main/waypoint.txt

The next step is to copy validator-full-node-identity.yaml from your validator over to your fullnode. You want to overwrite this file on your Fullnode.

From Validator

~/$WORKSPACE/keys/validator-full-node-identity.yaml

To Fullnode

~/$WORKSPACE/keys/validator-full-node-identity.yaml

Connect your Fullnode to your Validator

Replace the Validator IP and Fullnode IP with the appropriate IPs and then execute the following command.

./aptos genesis set-validator-configuration \
    --local-repository-dir ~/$WORKSPACE \
    --username $FULLNODENAME \
    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml\
    --validator-host <YOUR_VALIDATOR_IP>:6180 \
    --stake-amount 100000000000000 \
    --full-node-host <YOUR_FULLNODE_IP>:6182

Launch your Fullnode

Launch your Fullnode with the following commands

cd ~/$WORKSPACE
cp docker-compose-fullnode.yaml docker-compose.yaml
sudo docker-compose up -d

Check Docker Logs

sudo docker logs -f testnet_fullnode_1 --tail 60