🐳Docker

Authors: [ Ankur | Dapplooker]

System Requirements

CPU
OS
RAM
DISK

8 vCPU

Ubuntu 22.04

32 GB

2 TB (SSD)

The IoTeX node has a size of 602 GB on 12, February, 2025.

Pre-requisite

Before starting, clean the setup then update and upgrade. Install following:

  • Docker

  • Git

  • Go v1.23+

Commands

sudo apt update -y && sudo apt upgrade -y && sudo apt auto-remove -y
sudo apt install docker.io git ufw -y jq -y

Firewall Settings

Check status & enable UFW 

sudo ufw enable
sudo ufw status verbose

Set explicit default UFW rules

sudo ufw default deny incoming
sudo ufw default allow outgoing

Allow SSH, HTTP, and HTTPS

sudo ufw allow 22/tcp
sudo ufw allow 80
sudo ufw allow 443

Allow Remote connection

sudo ufw allow from ${REMOTE.HOST.IP} to any port 15014 # Ethereum JSON API

Setup Instructions

  1. Set the environment 

mkdir -p ~/iotex
cd ~/iotex

export IOTEX_HOME=$~/iotex

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

curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.1.2/config_mainnet.yaml > $IOTEX_HOME/etc/config.yaml
curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.1.2/genesis_mainnet.yaml > $IOTEX_HOME/etc/genesis.yaml
curl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.1.2/trie.db.patch > $IOTEX_HOME/data/trie.db.patch

  1. Edit `config.yaml` file

Edit $IOTEX_HOME/etc/config.yaml, look for externalHost and producerPrivKey, uncomment the lines and fill in your external IP and private key. If you leave producerPrivKey empty, your node will be assgined with a random key.

  1. Download Data 

curl -L https://t.iotex.me/mainnet-data-latest > $IOTEX_HOME/data.tar.gz
tar -xzf data.tar.gz

  1. If you plan to run your node as a gateway, please use the snapshot with index data: https://t.iotex.me/mainnet-data-with-idx-latest .

  2. If you only want to sync chain data from 0 height without relaying on legacy delegate election data from Ethereum, you can setup legacy delegate election data with following command:

curl -L https://storage.googleapis.com/blockchain-golden/poll.mainnet.tar.gz > $IOTEX_HOME/poll.tar.gz; tar -xzf $IOTEX_HOME/poll.tar.gz --directory $IOTEX_HOME/data

  1. If you want to sync the chain from 0 height and also fetching legacy delegate election data from Ethereum, please change the gravityChainAPIs in config.yaml to use your infura key with Ethereum archive mode supported or change the API endpoint to an Ethereum archive node which you can access.

  1. Start the node 

docker run -d --restart on-failure --name iotex \
        -p 4689:4689 \
        -p 14014:14014 \
        -p 15014:15014 \
        -p 16014:16014 \
        -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:v2.1.2 \
        iotex-server \
        -config-path=/etc/iotex/config_override.yaml \
        -genesis-path=/etc/iotex/genesis.yaml \
        -plugin=gateway

Monitoring

Check Ports

Ensure that TCP ports 4689 and 8080 are open on your firewall and load balancer (if applicable). Additionally, if you intend to use the node as a gateway, make sure the following ports are open:

  • 14014 for the IoTeX native gRPC API

  • 15014 for the Ethereum JSON API

  • 16014 for the Ethereum WebSocket

Monitor Logs of Docker Container 

docker ps 
docker logs iotex

Sync Status

Run a query to check the latest synchronized L2 block:

curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber",
"params":[],"id":83}' http://localhost:15014

Response should look like:

{"jsonrpc":"2.0","id":83,"result":"0x2112b2d"}

REFERENCES

PreviousIoTeXNextBare Metal

Last updated