EOSIO Single Node Testnet Setup

1. Overview

EOSIO comes with a number of programs. The primary ones are:

  • nodeos: server-side blockchain node component
  • cleos: command line interface to interact with the blockchain and to manage wallets
  • keosd: component that manages EOSIO wallets

The basic relationship between these components is illustrated in the following diagram.

2. Getting the Code

To download all of the code, clone the eos repository and its submodules.

git clone https://github.com/EOSIO/eos --recursive

3. Building EOSIO

There is an automated build script that can install all dependencies and build EOSIO. The build places content in the eos/build folder. The executables can be found in subfolders within the eos/build/programs folder.

3.1. System requirements

  • 8GB RAM free required
  • 20GB Disk free required

3.2. Run the build script

cd eos


3.3. Build validation

Optionally, a set of tests can be run against your build to perform some basic validation. To run the test suite after building, start mongod and the run make test.

/usr/local/bin/mongod -f /usr/local/etc/mongod.conf &
cd build
make test

3.4. Install the executables

sudo make install

4. Creating and Launching a Single Node Testnet

After successfully building the project, the nodeos binary should be present in the build/programs/nodeos folder. nodeos can be run directly from the build folder using programs/nodeos/nodeos, or you can cd build/programs/nodeos to change into the folder and run the nodeos command from there.

You can start your own single-node blockchain with this single command:

cd build/programs/nodeos
./nodeos -e -p eosio --plugin eosio::wallet_api_plugin --plugin eosio::chain_api_plugin --plugin eosio::account_history_api_plugin

When running nodeos you should get log messages similar to below. It means the blocks are successfully produced.

At this point, nodeos is running with a single producer, eosio. You can press ctr + c to stop producing.

4.1. Advanced steps

nodeos uses a custom configuration folder. The location of this folder is determined by your system.

For Mac OS: ~/Library/Application Support/eosio/nodeos/config

nodeos will need a properly configured config.ini file in order to do meaningful work. On startup, nodeos looks in the config folder for config.ini. If one is not found, a default config.ini file is created. If you do not already have a config.ini file ready to use, run nodeos and then close it immediately with Ctrl-C. A default configuration (config.ini) will have been created in the config folder. Edit the config.ini file, adding/updating the following settings to the defaults already in place:

# Load the testnet genesis state, which creates some initial block producers with the default key. E.g. genesis-json = "/Users/LiuYang/Library/Application Support/eosio/nodeos/config/genesis.json"
genesis-json = /path/to/eos/source/genesis.json

# Enable production on a stale chain, since a single-node test chain is pretty much always stale
enable-stale-production = true

# Enable block production with the testnet producers
producer-name = eosio

# Load the block producer plugin, so you can produce blocks
plugin = eosio::producer_plugin

# Wallet plugin
plugin = eosio::wallet_api_plugin

# As well as API and HTTP plugins
plugin = eosio::chain_api_plugin
plugin = eosio::http_plugin

# This will be used by the validation step below, to view account history
plugin = eosio::account_history_api_plugin

Now it should be possible to run nodeos in /eos/programs folder or eos/build/programs folder, and see it begin producing blocks.