Last Updated: 2019-07-23

This codelab serves as a comprehensive step-by-step guide on how to set up a full node for delegates on either IoTeX Mainnet alpha or Testnet.

What is a full node?

Full nodes are devices that support the IoTeX network by maintaining a full copy of our blockchain. Full nodes can help to validate transactions, accept transactions, and communicate with other nodes.

What you'll learn

What you'll need

Install Docker

We use Docker images to automate our application deployment. Install Docker following instructions from the Docker's website

Verify Docker is working properly

Run the following command to check that Docker is successfully installed

$ docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

Install ioctl

ioctl is a command-line interface used to interact with the blockchain

$ curl https://raw.githubusercontent.com/iotexproject/iotex-core/master/install-cli.sh | sh

Verify ioctl is working correctly

Make sure you have the latest version of ioctl

$ ioctl version
Client:
packageVersion:"v0.6.2" packageCommitID:"2df78e9460dee3bd3d96526468472409ac36d615" gitStatus:"clean" goVersion:"go version go1.12 linux/amd64" buildTime:"2019-05-29-UTC/21:41:31"

Configure endpoint

To use ioctl, you must first point ioctl to a node endpoint. Depending on which network you want to join, set the endpoint in your config:

$ ioctl config set endpoint api.iotex.one:443
endpoint is set to api.iotex.one:443

Make account

You can create a new account using ioctl. This will be your delegate account on the blockchain.

$ ioctl account create

You should receive an output such as this.

{
  "accounts": [
    {
      "address": "io1s9dumlan7px6cwm9j2l79kveh4232nh5580e7k",
      "privateKey": "03e54ff92d8fed4277e6c48c0ff9ff572b98325720f5f5b89d9369664a4bdcde",
      "publicKey": "04ae9d22fd1c993198d0697eb770492e347c724797cada1ba32c0390da4f31d6fc31382423b53a79bdf87b23d4df460cb4806c40e19ee0a4dee56ca086ca795cbd"
    }
  ]
}

Important: Note down you private key as this will be useful later.

Pull docker image

Make sure to pull the latest iotex-core image

$ docker pull iotex/iotex-core:v.0.8.3

Setup node environment

The following commands will set up an environment to store node/config files for MainNet.

$ mkdir -p ~/iotex-var
$ cd ~/iotex-var

$ export IOTEX_HOME=$PWD

$ mkdir -p $IOTEX_HOME/data
$ mkdir -p $IOTEX_HOME/log
$ mkdir -p $IOTEX_HOME/etc

$ curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/config_mainnet.yaml > $IOTEX_HOME/etc/config.yaml
$ curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/genesis_mainnet.yaml > $IOTEX_HOME/etc/genesis.yaml

Setup config

You will need to set up your config file with your machine and account details.

Open the yaml file using vi or a text editor of your choice

$ vi $IOTEX_HOME/etc/config.yaml

You should see something like this

network:
  externalHost: 34.208.88.254
  externalPort: 4689
  bootstrapNodes:
    - /dns4/bootnode-0.testnet.iotex.one/tcp/4689/ipfs/12D3KooWFnaTYuLo8Mkbm3wzaWHtUuaxBRe24Uiopu15Wr5EhD3o
    - /dns4/bootnode-1.testnet.iotex.one/tcp/4689/ipfs/12D3KooWS7hkdFozeUqriUxv7zw8Y6NCeV8E5HUbgmVkGJUv4jHS

chain:
  producerPrivKey: dbbf36378635bc743f698f39913e95728934c3991b8997b742a22424aa33c
...

Replace the producerPrivKey field with your account private key and externalHost with your ip address

Running your node

To start your node, run the following command.

$ docker run -d --restart on-failure --name iotex \
        -p 4689:4689 \
        -p 8080:8080 \
        -v=$IOTEX_HOME/data:/var/data:rw \
        -v=$IOTEX_HOME/log:/var/log:rw \
        -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
        -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
        iotex/iotex-core:v0.8.3 \
        iotex-server \
        -config-path=/etc/iotex/config_override.yaml \
        -genesis-path=/etc/iotex/genesis.yaml

If you would like to run your node as a gateway: allow your node to process API requests from other users, use this command instead.

docker run -d --restart on-failure --name iotex \
        -p 4689:4689 \
        -p 14014:14014 \
        -p 8080:8080 \
        -v=$IOTEX_HOME/data:/var/data:rw \
        -v=$IOTEX_HOME/log:/var/log:rw \
        -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
        -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
        iotex/iotex-core:v0.8.3 \
        iotex-server \
        -config-path=/etc/iotex/config_override.yaml \
        -genesis-path=/etc/iotex/genesis.yaml \
        -plugin=gateway

Pull docker image

Make sure to pull the latest iotex-core TestNet image: v.0.8.3

$ docker pull iotex/iotex-core:v.0.8.3

Setup node environment

The following commands will set up an environment to store node/config files for MainNet.

$ mkdir -p ~/iotex-var
$ cd ~/iotex-var

$ export IOTEX_HOME=$PWD

$ mkdir -p $IOTEX_HOME/data
$ mkdir -p $IOTEX_HOME/log
$ mkdir -p $IOTEX_HOME/etc

$ curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/config_testnet.yaml > $IOTEX_HOME/etc/config.yaml
$ curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/genesis_testnet.yaml > $IOTEX_HOME/etc/genesis.yaml

Setup config

You will need to set up your config file with your machine and account details.

Open the yaml file using vi or a text editor of your choice

$ vi $IOTEX_HOME/etc/config.yaml

You should see something like this

network:
  externalHost: 34.208.88.254
  externalPort: 4689
  bootstrapNodes:
    - /dns4/bootnode-0.testnet.iotex.one/tcp/4689/ipfs/12D3KooWFnaTYuLo8Mkbm3wzaWHtUuaxBRe24Uiopu15Wr5EhD3o
    - /dns4/bootnode-1.testnet.iotex.one/tcp/4689/ipfs/12D3KooWS7hkdFozeUqriUxv7zw8Y6NCeV8E5HUbgmVkGJUv4jHS

chain:
  producerPrivKey: dbbf36378635bc743f698f39913e95728934c3991b8997b742a22424aa33c
...

Replace the producerPrivKey field with your account private key and externalHost with your ip address

Running your node

To start your node, run the following command.

$ docker run -d --restart on-failure --name iotex \
        -p 4689:4689 \
        -p 8080:8080 \
        -v=$IOTEX_HOME/data:/var/data:rw \
        -v=$IOTEX_HOME/log:/var/log:rw \
        -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
        -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
        iotex/iotex-core:v0.8.3 \
        iotex-server \
        -config-path=/etc/iotex/config_override.yaml \
        -genesis-path=/etc/iotex/genesis.yaml

If you would like to run your node as a gateway: allow your node to process API requests from other users, use this command instead.

docker run -d --restart on-failure --name iotex \
        -p 4689:4689 \
        -p 14014:14014 \
        -p 8080:8080 \
        -v=$IOTEX_HOME/data:/var/data:rw \
        -v=$IOTEX_HOME/log:/var/log:rw \
        -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
        -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
        iotex/iotex-core:v0.8.3 \
        iotex-server \
        -config-path=/etc/iotex/config_override.yaml \
        -genesis-path=/etc/iotex/genesis.yaml \
        -plugin=gateway

You can verify that your node is working by fetching the logs of the container

$ docker logs iotex

The logs can be filtered using

$ docker logs -f --tail 100 iotex |grep --color -E "epoch|height|error|rolldposctx"

If you started your node as a gateway, you should be able to connect to it as an endpoint and query the consensus delegates

$ ioctl config set endpoint localhost:14014
$ ioctl node delegate