[doc] add validator doc (aptos-labs#968)

waxwezloo · May 13, 2022 · 1aad128 · 1aad128
1 parent 405a662
commit 1aad128
Show file tree

Hide file tree

Showing 7 changed files with 824 additions and 0 deletions.
diff --git a/developer-docs-site/docs/tutorials/validator-node/_category_.json b/developer-docs-site/docs/tutorials/validator-node/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Run a Validator Node",
+  "position": 8
+}
diff --git a/developer-docs-site/docs/tutorials/validator-node/connect-to-testnet.md b/developer-docs-site/docs/tutorials/validator-node/connect-to-testnet.md
@@ -0,0 +1,37 @@
+---
+title: "Connecting to Aptos Incentivized Testnet"
+slug: "connect-to-testnet"
+sidebar_position: 14
+---
+
+# Connecting to Aptos Incentivized Testnet
+
+Only do this if you got confirmation email from Aptos team for your eligibility. Nodes not selected will not be included in the genesis, thus not be able to connecting to incentivized testnet as a validator node. You can still run public fullnode in this case if you want.
+
+## Using source code
+
+- Stop your node and remove the data directory.
+- Download the `genesis.blob` and `waypoint.txt` file published by Aptos Labs team.
+- Restarting the node
+
+## Using Docker
+
+- Stop your node and remove the data volumes, `docker-compose down --volumes`
+- Download the `genesis.blob` and `waypoint.txt` file published by Aptos Labs team.
+- Restarting the node: `docker-compose up`
+
+## Using Terraform
+
+- Increase `era` number in your Terraform config, this will wipe the data once applied.
+- Apply Terraform: `terraform apply`
+- Download the `genesis.blob` and `waypoint.txt` file published by Aptos Labs team.
+- Recreate the secrets:
+    ```
+    export WORKSPACE=<your workspace name>
+
+    kubectl create secret generic ${WORKSPACE}-aptos-node-genesis-e2 \
+        --from-file=genesis.blob=genesis.blob \
+        --from-file=waypoint.txt=waypoint.txt \
+        --from-file=validator-identity.yaml=validator-identity.yaml \
+        --from-file=validator-full-node-identity.yaml=validator-full-node-identity.yaml
+    ```
diff --git a/developer-docs-site/docs/tutorials/validator-node/intro.md b/developer-docs-site/docs/tutorials/validator-node/intro.md
@@ -0,0 +1,70 @@
+---
+title: "Introduction"
+slug: "intro"
+sidebar_position: 10
+---
+
+# Run a Validator Node
+
+Validator nodes runs a distributed consensus protocol, execute the transaction, and store the transaction and the execution results on the blockchain. Validator nodes decide which transactions will be added to the blockchain and in which order. Read more about [Validator node concepts](/basics/basics-validator-nodes).
+
+For incentivized testnet, we're recommending every node operator to run a validator with a fullnode, so all the reference implementation used here will have both nodes installed by default.
+
+This tutorial explains how to configure a validator node to run on test mode, which will be used during the registration stage to validate your eligibility, and how to connect to incentivized testnet once you're selected to run a validator node. Users not selected to run a validator node can still run a public fullnode to connect to incentivized testnet.
+
+## Before you proceed
+
+Before you get started with this tutorial, read the following sections:
+
+* [Validator node concepts](/basics/basics-validator-nodes).
+* [FullNode concepts](/basics/basics-fullnodes).
+* [Node networks and synchronization](/basics/basics-node-networks-sync).
+
+## Hardware requirements
+
+We recommend the following hardware resources:
+
+- For running an aptos node on incentivized testnet we recommend the following:
+
+  - **CPU**: 4 cores (Intel Xeon Skylake or newer).
+  - **Memory**: 8GiB RAM.
+
+## Storage requirements
+
+The amount of data stored by Aptos depends on the ledger history (length) of the blockchain and the number
+of on-chain states (e.g., accounts). These values depend on several factors, including: the age of the blockchain,
+the average transaction rate and the configuration of the ledger pruner.
+
+We recommend to bootstrap with 300GB of disk space to leave room for load testing, but if you want to save disk space you can start with smaller size and expand when reaching limit, and you will be responsible for monitoring the disk usage of your node, adjusting it as needed to ensure the node uptime. 
+
+## Networking configuration requirements
+
+For Validator node:
+
+- Open TCP port 6180, for validators to talk to each other.
+- Open TCP port 9101, for getting validator metrics to validate the health stats. (only needed during registration stage)
+
+For Fullnode:
+
+- Open TCP port 6182, for fullnodes to talk to each other.
+- Open TCP port 9101, for getting fullnode metrics to validate the health stats. (only needed during registration stage)
+- Open TCP port 80/8080, for REST API access.
+
+## Getting started
+You can configure an Aptos node in many ways: using Aptos source code, using docker, and using Terraform. For best availability and stability, we recommend you to deploy your node on the Cloud. We provided Terraform support for deploying the node on three cloud providers: GCP, AWS and Azure.
+
+In order to participate in the incentivized testnet, participants must demonstrate the ability to configure and deploy a node as well as pass KYC (know your client) sanctions requirements.
+
+High level steps for joining Aptos Incentivized Testnet:
+- Follow the instruction to deploy a node (including a validator node and a fullnode) with test mode.
+- Navigate to registration page, enter informations about your node (pub-keys, IP/DNS address).
+- If you're selected to run a node, follow instructions to join incentivized testnet.
+- Keep the node in healthy state for the entire testing period and follow operational requests as needed.
+
+### Installation
+Running a validator node in test mode is required to be eligible for incentivized testnet. This is a method we use to verify that a node operator can successfully start a validator node, and have it properly configured with Aptos network identity. In test mode, you will be running a local network with one single node, it should be functioning like a normal blockchain. You can follow those guide to install your node in test mode:
+
+* [Using Aptos source code](run-validator-node-using-source)
+* [Using docker](run-validator-node-using-docker)
+* [Using GCP](run-validator-node-using-gcp)
+* [Using AWS](run-validator-node-using-aws)
diff --git a/developer-docs-site/docs/tutorials/validator-node/using-aws.md b/developer-docs-site/docs/tutorials/validator-node/using-aws.md
@@ -0,0 +1,205 @@
+---
+title: "Run Validator Node Using AWS"
+slug: "run-validator-node-using-aws"
+sidebar_position: 11
+---
+
+## Run on AWS
+This guide assumes you already have AWS account setup.
+
+Install pre-requisites if needed:
+
+   * Aptos CLI: https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos/README.md
+   * Terraform 1.1.7: https://www.terraform.io/downloads.html
+   * Kubernetes CLI: https://kubernetes.io/docs/tasks/tools/
+   * AWS CLI: https://aws.amazon.com/cli/
+
+1. Create a working directory for your configuration.
+
+    * Choose a workspace name e.g. `testnet`. Note: This defines Terraform workspace name, which in turn is used to form resource names.
+    ```
+    export WORKSPACE=testnet
+    ```
+
+    * Create a directory for the workspace
+    ```
+    mkdir -p ~/$WORKSPACE
+    ```
+
+2. Create a S3 storage bucket for storing the Terraform state on AWS, you can do this on AWS UI or by the command: 
+
+    ```
+    aws s3api create-bucket --bucket <bucket name> --region <region name>
+    ```
+
+3. Create Terraform file called `main.tf` in your working directory:
+  ```
+  cd ~/$WORKSPACE
+  vi main.tf
+  ```
+
+4. Modify `main.tf` file to configure Terraform, and create fullnode from Terraform module. Example content for `main.tf`:
+  ```
+  terraform {
+    required_version = "~> 1.1.0"
+    backend "s3" {
+      bucket = "terraform.aptos-node"
+      key    = "state/aptos-node"
+      region = <aws region>
+    }
+  }
+
+  provider "aws" {
+    region = <aws region>
+  }
+
+  module "aptos-node" {
+    # download Terraform module from aptos-labs/aptos-core repo
+    source        = "github.com/aptos-labs/aptos-core.git//terraform/aptos-node/aws?ref=main"
+    region        = <aws region>  # Specify the region
+    # zone_id     = "<Route53 zone id>"  # zone id for Route53 if you want to use DNS
+    era           = 1              # bump era number to wipe the chain
+    chain_id      = 23
+    image_tag     = "testnet" # Specify the docker image tag to use
+    validator_name = "<Name of Your Validator>"
+  }
+  ```
+
+    For the full customization options, see the variables file [here](https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/aws/variables.tf), and the [helm values](https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml).
+
+5. Initialize Terraform in the same directory of your `main.tf` file
+  ```
+  terraform init
+  ```
+This will download all the terraform dependencies for you, in the `.terraform` folder in your current working directory.
+
+6. Create a new Terraform workspace to isolate your environments:
+  ```
+  terraform workspace new $WORKSPACE
+  # This command will list all workspaces
+  terraform workspace list
+  ```
+
+7. Apply the configuration.
+  ```
+  terraform apply
+  ```
+  This might take a while to finish (~20 minutes), Terraform will create all the resources on your cloud account.
+
+8. Once terraform apply finishes, you can check if those resources are created:
+
+    - `aws eks update-kubeconfig --name aptos-$WORKSPACE` to configure access for your k8s cluster.
+    - `kubectl get pods` this should have haproxy, validator and fullnode. with validator and fullnode pod `pending` (require further action in later steps)
+    - `kubectl get svc` this should have `validator-lb` and `fullnode-lb`, with an external-IP you can share later for connectivity.
+
+9. Get your node IP info:
+
+    ```
+    export VALIDATOR_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-validator-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
+
+    export FULLNODE_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-fullnode-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
+    ```
+
+10. Generate key pairs (node owner key, consensus key and networking key) in your working directory.
+
+    ```
+    aptos genesis generate-keys --output-dir ~/$WORKSPACE
+    ```
+
+    This will create three files: `private-keys.yaml`, `validator-identity.yaml`, `validator-full-node-identity.yaml` for you. **IMPORTANT**: Backup your key files somewhere safe. These key files are important for you to establish ownership of your node, and you will use this information to claim your rewards later if eligible. Never share those keys with anyone else.
+
+11. Configure validator information.
+
+    ```
+    aptos genesis set-validator-configuration --keys-dir ~/$WORKSPACE --local-repository-dir ~/$WORKSPACE --username <pick a username for your node> --validator-host $VALIDATOR_ADDRESS:6180 --full-node-host $FULLNODE_ADDRESS:6182
+
+    ```
+
+    This will create a YAML file in your working directory with your username, e.g. `aptosbot.yaml`, it should looks like below:
+
+    ```
+    ---
+    account_address: 7410973313fd0b5c69560fd8cd9c4aaeef873f869d292d1bb94b1872e737d64f
+    consensus_key: "0x4e6323a4692866d54316f3b08493f161746fda4daaacb6f0a04ec36b6160fdce"
+    account_key: "0x83f090aee4525052f3b504805c2a0b1d37553d611129289ede2fc9ca5f6aed3c"
+    network_key: "0xa06381a17b090b8db5ffef97c6e861baad94a1b0e3210e6309de84c15337811d"
+    validator_host:
+      host: 30247cc34f270cb8.elb.us-west-2.amazonaws.com
+      port: 6180
+    full_node_host:
+      host: abc5b9734d4cc418.elb.us-west-2.amazonaws.com
+      port: 6182
+    stake_amount: 1
+    ```
+
+12. Create layout YAML file, which defines the node in the validatorSet. For test mode, we can create a genesis blob containing only one node.
+
+    ```
+    vi layout.yaml
+    ```
+
+    Add root key, node username, and chain_id in the `layout.yaml` file, for example:
+
+    ```
+    ---
+    root_key: "0x5243ca72b0766d9e9cbf2debf6153443b01a1e0e6d086c7ea206eaf6f8043956"
+    users:
+      - <username you created in step 5>
+    chain_id: 23
+    ```
+
+13. Download AptosFramework Move bytecodes into a folder named `framework`.
+
+    Download the Aptos Framework from the release page: https://github.com/aptos-labs/aptos-core/releases/tag/aptos-framework-v0.1.0
+
+    ```
+    wget https://github.com/aptos-labs/aptos-core/releases/download/aptos-framework-v0.1.0/framework.zip
+
+    unzip framework.zip
+    ```
+
+    You should now have a folder called `framework`, which contains move bytecodes with format `.mv`.
+
+14. Compile genesis blob and waypoint
+
+    ```
+    aptos genesis generate-genesis --local-repository-dir ~/$WORKSPACE --output-dir ~/$WORKSPACE
+    ``` 
+
+    This should create two files in your working directory, `genesis.blob` and `waypoint.txt`
+
+15. To recap, in your working directory, you should have a list of files:
+    - `main.tf` the Terraform files to install aptos-node module.
+    - `private-keys.yaml` Private keys for owner account, consensus, networking
+    - `validator-identity.yaml` Private keys for setting validator identity
+    - `validator-full-node-identity.yaml` Private keys for setting validator full node identity
+    - `<username>.yaml` Node info for both validator / fullnode
+    - `layout.yaml` layout file to define root key, validator user, and chain ID
+    - `framework` folder which contains all the move bytecode for AptosFramework.
+    - `waypoint.txt` waypoint for genesis transaction
+    - `genesis.blob` genesis binary contains all the info about framework, validatorSet and more.
+
+16. Insert `genesis.blob`, `waypoint.txt` and the identity files as secret into k8s cluster.
+
+    ```
+    kubectl create secret generic ${WORKSPACE}-aptos-node-genesis-e1 \
+        --from-file=genesis.blob=genesis.blob \
+        --from-file=waypoint.txt=waypoint.txt \
+        --from-file=validator-identity.yaml=validator-identity.yaml \
+        --from-file=validator-full-node-identity.yaml=validator-full-node-identity.yaml
+    ```
+
+    If you changed the era number, make sure it matches when creating the secret.
+
+17. Check all pods running.
+
+    ```
+    kubectl get pods
+
+    NAME                                        READY   STATUS    RESTARTS   AGE
+    node1-aptos-node-fullnode-e9-0              1/1     Running   0          4h31m
+    node1-aptos-node-haproxy-7cc4c5f74c-l4l6n   1/1     Running   0          4h40m
+    node1-aptos-node-validator-0                1/1     Running   0          4h30m
+    ```
+
+Now you have completed setting up your node in test mode. You can continue to our [community](https://community.aptoslabs.com/) website for registration.