{"id":13569263,"url":"https://github.com/iotexproject/iotex-bootstrap","last_synced_at":"2026-04-02T18:48:58.742Z","repository":{"id":39989725,"uuid":"172628317","full_name":"iotexproject/iotex-bootstrap","owner":"iotexproject","description":"All necessary configuration files and step-by-step instructions for setting up and running a full-node on the IoTeX blockchain. Start contributing to the IoTeX network and explore advanced node features.","archived":false,"fork":false,"pushed_at":"2026-03-30T04:02:19.000Z","size":3989,"stargazers_count":96,"open_issues_count":14,"forks_count":43,"subscribers_count":22,"default_branch":"master","last_synced_at":"2026-03-30T05:36:11.697Z","etag":null,"topics":["delegate","full-node","instructions","iotx","mining"],"latest_commit_sha":null,"homepage":"https://iotex.io","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iotexproject.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/README.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-02-26T03:09:04.000Z","updated_at":"2026-03-30T02:51:37.000Z","dependencies_parsed_at":"2023-02-08T16:16:17.386Z","dependency_job_id":"90d007f3-e57a-4b3a-b9a4-2ad368e888d5","html_url":"https://github.com/iotexproject/iotex-bootstrap","commit_stats":null,"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/iotexproject/iotex-bootstrap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fiotex-bootstrap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fiotex-bootstrap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fiotex-bootstrap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fiotex-bootstrap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iotexproject","download_url":"https://codeload.github.com/iotexproject/iotex-bootstrap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iotexproject%2Fiotex-bootstrap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["delegate","full-node","instructions","iotx","mining"],"created_at":"2024-08-01T14:00:37.764Z","updated_at":"2026-04-02T18:48:58.734Z","avatar_url":"https://github.com/iotexproject.png","language":"Shell","readme":"# IoTeX Delegate Manual\n\u003ca href=\"https://iotex.io/devdiscord\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://github.com/iotexproject/halogrants/blob/880eea4af074b082a75608c7376bd7a8eaa1ac21/img/btn-discord.svg\" height=\"36px\"\u003e\n\u003c/a\u003e\n\n## Index\n\n- [Release Status](#status)\n- [Join MainNet](#mainnet)\n- [Join Mainnet without using Docker](#mainnet_native)\n- [Join TestNet](#testnet)\n- [Interact with Blockchain](#ioctl)\n- [Enable Logrotate](#log)\n- [Operate Your Node](#ops)\n- [Upgrade Your Node（One Line Upgrader）](#upgrade)\n- [AI Agent Upgrade (Non-Interactive)](#agent-upgrade)\n- [Q\u0026A](#qa)\n\n## \u003ca name=\"status\"/\u003eRelease Status\n\nHere are the software versions we use:\n\n- MainNet: v2.3.8\n\n## \u003ca name=\"testnet\"/\u003eJoin TestNet\nTo start and run a testnet node, please click [**Join Testnet**](https://github.com/iotexproject/iotex-bootstrap/blob/master/README_testnet.md)\n\n## \u003ca name=\"mainnet\"/\u003eJoin MainNet\nThis is the recommended way to start an IoTeX node\n\n\u003e All the steps have written in scripts/all_in_one_mainnet.sh, you can directly run `sh scripts/all_in_one_mainnet.sh`\n\n1. Pull the docker image:\n\n```\ndocker pull iotex/iotex-core:v2.3.8\n```\n\n2. Set the environment with the following commands:\n\n```\nmkdir -p ~/iotex-var\ncd ~/iotex-var\n\nexport IOTEX_HOME=$PWD\n\nmkdir -p $IOTEX_HOME/data\nmkdir -p $IOTEX_HOME/log\nmkdir -p $IOTEX_HOME/etc\n\ncurl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.3.8/config_mainnet.yaml \u003e $IOTEX_HOME/etc/config.yaml\ncurl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.3.8/genesis_mainnet.yaml \u003e $IOTEX_HOME/etc/genesis.yaml\ncurl https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/v2.3.8/trie.db.patch \u003e $IOTEX_HOME/data/trie.db.patch\n```\n\n3. 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.\n\n4. Start from a **baseline snapshot** (rather than sync from the genesis block), run the following commands:\n\n```\ncurl -L -C - -o $IOTEX_HOME/data.tar.gz https://t.iotex.me/mainnet-data-snapshot-core-latest\n```\n\n5. Extract the data package:\n\n```\ntar -xzf $IOTEX_HOME/data.tar.gz -C $IOTEX_HOME/data/\n```\n\nFor advanced users, there are three options to consider:\n\n- Option 1: If you plan to run your node as a [gateway](#gateway), please use the snapshot with index data:\n```\ncurl -L -C - -o $IOTEX_HOME/data_index.tar.gz https://t.iotex.me/mainnet-data-snapshot-gateway-latest\ntar -xzf data_index.tar.gz\n```\n\nIf you need to run your node in archive mode to provide full historical data, please go to [Archive Node](./archive-node.md).\n\n- Optional 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:\n```bash\ncurl -L -C - -o $IOTEX_HOME/poll.tar.gz https://storage.iotex.io/poll.mainnet.tar.gz; tar -xzf $IOTEX_HOME/poll.tar.gz --directory $IOTEX_HOME/data\n```\n\n- Optional 3: 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.\n\n6. Run the following command to start a node:\n\n```\ndocker run -d --restart on-failure --name iotex \\\n        -p 4689:4689 \\\n        -p 8080:8080 \\\n        -v=$IOTEX_HOME/data:/var/data:rw \\\n        -v=$IOTEX_HOME/log:/var/log:rw \\\n        -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \\\n        -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \\\n        iotex/iotex-core:v2.3.8 \\\n        iotex-server \\\n        -config-path=/etc/iotex/config_override.yaml \\\n        -genesis-path=/etc/iotex/genesis.yaml\n```\n\nNow your node should be started successfully.\n\nIf you want to also make your node be a [gateway](#gateway), which could process API requests from users, use the following command instead:\n\n```\ndocker run -d --restart on-failure --name iotex \\\n        -p 4689:4689 \\\n        -p 14014:14014 \\\n        -p 15014:15014 \\\n        -p 16014:16014 \\\n        -p 8080:8080 \\\n        -v=$IOTEX_HOME/data:/var/data:rw \\\n        -v=$IOTEX_HOME/log:/var/log:rw \\\n        -v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \\\n        -v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \\\n        iotex/iotex-core:v2.3.8 \\\n        iotex-server \\\n        -config-path=/etc/iotex/config_override.yaml \\\n        -genesis-path=/etc/iotex/genesis.yaml \\\n        -plugin=gateway\n```\n\n7. 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:\n- `14014` for the IoTeX native gRPC API\n- `15014` for the Ethereum JSON API\n- `16014` for the Ethereum WebSocket\n\n## \u003ca name=\"mainnet_native\"/\u003eJoin Mainnet without using Docker\nThis is not the preferred way to start an IoTeX node\n\n1. Set the environment with the following commands:\n\nSame as [Join MainNet](#mainnet) step 2\n\n2. Build server binary:\n\n```\ngit clone https://github.com/iotexproject/iotex-core.git\ncd iotex-core\ngit checkout v2.3.8\n\n// optional\nexport GOPROXY=https://goproxy.io\ngo mod download\nmake clean build-all\ncp ./bin/server $IOTEX_HOME/iotex-server\n```\n\n3. Edit configs\n\nSame as [Join MainNet](#mainnet) step 3. Also make sure you update all db paths in config.yaml to correct location if you don't put them under `/var/data/`\n\n4. Start from a snapshot\n\nSame as [Join MainNet](#mainnet) step 4\n\n5. Run the following command to start a node:\n\n```\nnohup $IOTEX_HOME/iotex-server \\\n        -config-path=$IOTEX_HOME/etc/config.yaml \\\n        -genesis-path=$IOTEX_HOME/etc/genesis.yaml \u0026\n```\n\nNow your node should be started successfully.\n\nIf you want to also make your node be a [gateway](#gateway), which could process API requests from users, use the following command instead:\n\n```\nnohup $IOTEX_HOME/iotex-server \\\n        -config-path=$IOTEX_HOME/etc/config.yaml \\\n        -genesis-path=$IOTEX_HOME/etc/genesis.yaml \\\n        -plugin=gateway \u0026\n```\n\n6. Make sure TCP ports 4689, 8080 (also 14014 if used) are open on your firewall and load balancer (if any).\n\n## \u003ca name=\"ioctl\"/\u003eInteract with Blockchain\n\n### ioctl\n\nYou can install `ioctl` (a command-line interface for interacting with IoTeX blockchain)\n\n```\ncurl https://raw.githubusercontent.com/iotexproject/iotex-core/master/install-cli.sh | sh\n```\n\nYou can point `ioctl` to your node (if you enable the [gateway](#gateway) plugin):\n\n```\nioctl config set endpoint localhost:14014 --insecure\n```\n\nOr you can point it to our API nodes:\n\n- MainNet secure: `api.iotex.one:443`\n- MainNet insecure: `api.iotex.one:80`\n\nIf you want to set an insecure endpoint, you need to add `--insecure` option.\n\nGenerate key:\n```\nioctl account create\n```\n\nGet consensus delegates of current epoch:\n```\nioctl node delegate\n```\n\nRefer to [CLI document](https://github.com/iotexproject/iotex-core/blob/master/ioctl/README.md) for more details.\n\n#### Other Commonly Used Commands\n\nClaim reward:\n```\nioctl action claim ${amountInIOTX} -l 10000 -p 1 -s ${ioAddress|alias}\n```\n\nExchange IoTeX native token to ERC20 token on Ethereum via Tube service:\n```\nioctl action invoke io1p99pprm79rftj4r6kenfjcp8jkp6zc6mytuah5 ${amountInIOTX} -s ${ioAddress|alias} -l 400000 -p 1 -b d0e30db0\n```\nClick [IoTeX Tube docs](https://github.com/iotexproject/iotex-bootstrap/blob/master/tube/tube.md) for detailed documentation of the tube service.\n\n### JSON RPC API (former \"Babel service\")\n\nOur node supports most methods of [Ethereum's JSON-RPC protocol](https://eth.wiki/json-rpc/API).  The local endpoint for the Ethereum API service is available at `localhost:15014`. WebSocket support is also available on `localhost:16014`. \n\nAdditional method support could be requested [here](https://github.com/iotexproject/iotex-core/issues).\n\n## \u003ca name=\"log\"/\u003eEnable Logrotate\n`logrotate` is pre-installed when building the image. But `crond` (daemon to execute scheduled commands) doesn't automatically start when the docker contaiter starts in alpine linux. \n\nTo enable log logrotation, `docker exec -it \u003ccontainer\u003e crond -b` is expected to be run after the container starts\n\n## \u003ca name=\"ops\"/\u003eOperate Your Node\n\n### Checking Node log\n\nContainer logs can be accessed with the following command. \n\n```\ndocker logs iotex\n```\n\nContent can be filtered with:\n\n```\ndocker logs -f --tail 100 iotex |grep --color -E \"epoch|height|error|rolldposctx\"\n```\n\n### Stop and remove container\n\nWhen starting the container with ```--name=iotex```, you must remove the old container before a new build.\n\n```\ndocker stop iotex\ndocker rm iotex\n```\n\n### Pause and Restarting container\n\nContainer can be \"stopped\" and \"restarted\" with:\n\n```\ndocker stop iotex\ndocker start iotex\n```\n\n## \u003ca name=\"upgrade\"/\u003eUpgrade Your Node(One Line Upgrader)\nMake sure that $IOTEX_HOME is already set up, and all necessary files (e.g., configs, databases, etc.) are placed in the correct locations.\n(Please refer to the Join MainNet section for detailed instructions.)\n\nTo upgrade your Mainnet node to the latest version, run the following command:\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/scripts/setup_fullnode.sh)\n```\nNote: If your Docker commands require root privileges, run the script with sudo like this:\n```\nsudo bash \u003c(curl -s https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/scripts/setup_fullnode.sh)\n```\n\nTo enable [gateway](#gateway) on mainnet\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/scripts/setup_fullnode.sh) plugin=gateway\n```\n\nTo stop auto upgdrade cron job and iotex server program, you can run\n```bash\nbash \u003c(curl -s https://raw.githubusercontent.com/iotexproject/iotex-bootstrap/master/scripts/stop_fullnode.sh)\n```\n## \u003ca name=\"agent-upgrade\"/\u003eAI Agent Upgrade (Non-Interactive)\n\nThe upgrade script supports a non-interactive mode for use with AI agents, CI/CD pipelines, or automation tools. Use the `--auto` flag to skip all interactive prompts.\n\n**Flags:**\n\n| Flag | Description |\n|---|---|\n| `--auto` | Non-interactive mode, skip all prompts |\n| `--home=/path` | Set `$IOTEX_HOME` directory |\n| `--version=v2.3.8` | Target version (default: latest release) |\n| `--force` | Reinstall even if already running the same version |\n| `--monitor` | Enable monitoring |\n| `plugin=gateway` | Enable gateway plugin |\n\n**Upgrade to latest version:**\n```bash\nbash setup_fullnode.sh --auto --home=/path/to/iotex-var\n```\n\n**Upgrade to a specific version:**\n```bash\nbash setup_fullnode.sh --auto --home=/path/to/iotex-var --version=v2.3.8\n```\n\n**Force reinstall same version:**\n```bash\nbash setup_fullnode.sh --auto --home=/path/to/iotex-var --force\n```\n\n**Notes:**\n- The script auto-detects `IOTEX_HOME` from the running container if `--home` is not specified in interactive mode.\n- Existing `producerPrivKey` and `externalHost` are preserved during upgrades. If no key is configured, the node will use a random key.\n- The old container is stopped as late as possible (after docker pull and config downloads) to minimize downtime.\n\n## \u003ca name=\"gateway\"/\u003e Gateway Plugin\nNode with gateway plugin enabled will perform extra indexing to serve API requests of more detail chain information, such as number of actions in a block or query actions by hash.\n\n## \u003ca name=\"qa\"/\u003eQ\u0026A\nPlease refer [here](https://github.com/iotexproject/iotex-bootstrap/wiki/Q\u0026A) for Q\u0026A.\n","funding_links":[],"categories":["IoTeX"],"sub_categories":["Chainstack","Infura"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiotexproject%2Fiotex-bootstrap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiotexproject%2Fiotex-bootstrap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiotexproject%2Fiotex-bootstrap/lists"}