EOSCommunity.org Forums

Setting up a WAX Testnet API using our new docker-nodeos repository

Someone today asked “Does anyone have a guide on how to setup a WAX testnet API for local use?” on Telegram. I figured I’d take the opportunity to show how this could be done using one of our newer projects, docker-nodeos.

We manage a lot of nodeos API servers. Until recently they’ve been all pets and no cattle. Managing them often ends up taking significant chunks of our time away from other projects. So we are starting to experiment with converting our general purpose APIs into “cattle”, and this was the resulting work:

This github repository contains configurations for docker/docker-compose and the README.md describes generically how to set it up for any EOSIO blockchain. I’m going to go one step further in this post and outline how you would use this repository to setup a WAX testnet node and get it running in just a few steps.

What this setup requires:

  1. Adequate RAM: These containers will load the blockchains state directly into RAM (for performance reasons). Each nodeos container will consume RAM slightly greater than the size of the blockchain’s state. This guide is on the WAX testnet, the RAM usage is low, so you should be able to get away with a couple gigabytes for each container.
  2. Fast CPU: You are going to need a moderately fast CPU in order to both keep up with the blockchain and process incoming API requests. We generally target 4.5ghz+ machines for our APIs. Since this is a WAX testnet guide though, you’ll likely be able to get away with less. The lower the CPU speed is though, the longer builds will take and the harder time it will have keeping up.
  3. A good amount of disk space: For WAX specifically, we don’t yet have block log trimming. This is supported by these containers, but we’re going to have to disable it in this guide. That means that these containers will continue to grow in size as the blockchain continues to grow. However each time you start a new container it’ll reset to a baseline value. For WAX testnet this shouldn’t be a concern since its relatively small, for other networks you’ll need to keep on top of this.

What this setup does:

  1. Builds the nodeos binary based on the repository and branch/tag specified.
  2. Downloads a recent snapshot of the blockchain to initialize from.
  3. Starts nodeos with an optimal configuration for performance0.

With that out of the way, below are the instructions. Feel free to reply to this thread and ask questions!

Step 1 - Docker

This step is only required if your system is not running Docker and/or Docker Compose. You’ll need to make sure these two things are installed on your system and running moderately recent versions. Detailed instructions on getting these installed on Ubuntu can be found here and other guides for different distributions can likely be found by searching the internet for:

"install docker and docker-compose on [distribution name here]"

Feel free to adopt this code to other container solutions - but for this specific post we’re going to focus on Docker and Docker-compose.

Step 2 - Clone

Clone down the repository into the location you’d like to operate out of and navigate to it:

git clone https://github.com/greymass/docker-nodeos.git docker-waxtestnet
cd docker-waxtestnet

Step 3 - Configure

The first thing you’ll need to add is the environmental configuration file. This file needs to be placed in the root of the project as a file named .env, which serves basic information to the entire setup.

Use your favorite editor to open this file from the root of the project:

nano .env

With your editor open, paste in the following information:

# The name of the network this environment is for (must be unique on the host machine)

# The port to expose the nodeos api(s) on the host machine

# The port to expose the nodeos p2p procotol on the host machine

# The git repository of the nodeos (EOSIO) repository to use

# The branch/tag of nodeos to checkout during the build process

# A snapshot (compressed as tar.gz) to use during the startup of this node

# Peers to inject into the nodeos configuration
NODEOS_PEERS=peer.waxtest.alohaeos.com:9876 wax-testnet.cryptolions.io:7987 waxtest.eosn.io:9876 peer1.testnet.wax.pink.gg:16714 node-waxtest.eosauthority.com:9393

We will also need a nodeos configuration for the build. There’s a sample located in the project, configs/nodeos/example-minimal-api.config.ini, which we can use for a basic API server. Copy this into the configuration folder:

cp configs/nodeos/example-minimal-api.config.ini configs/config.ini

We do have to make one change to this file though, at least until we can use nodeos 2.1. Open up this config file:

nano config/config.ini

Find the following two lines:

blocks-log-stride = 100
max-retained-block-files = 1728

Either delete them or put a # in front of them to comment them out, like so:

# blocks-log-stride = 100
# max-retained-block-files = 1728

After 2.1 for WAX is available, we can add those lines back in to make the container trim its block log automatically to save disk space.

Step 4 - Build

With our configuration files in place, it’s time to tell Docker to build. Run the following command from the root of the project:

docker-compose build

This will take a while, it’s going to build everything out for you.

Step 5 - Run

There are a couple of ways to run these containers, and a few which we’re still experimenting with. For this guide we’re just going to run nodeos and put a simple nginx instance in front of the container(s).

To run the nginx profile in the background:

docker-compose --profile nginx up -d

It will start to come online and be available at localhost:38888 (based on the environmental file).

To check the logs and see what’s going on with the processes, you can tail the logs with:

docker-compose logs -f --tail="200"

And when you want to stop the processes, you just need to call down:

docker-compose down

Bonus: Load Balanced Instances

If you need to handle a large amount of requests, you can use the --scale option as you’re launching the containers to create more the one. The nginx process in the foreground will automatically load balance between them all.

docker-compose --profile nginx up --scale nodeos=2

Making changes and redeploying

If you need to make changes, either to the .env (for docker) or config/config.ini (for nodeos) files, you’ll need to rebuild afterwards. My typical workflow when I’m modifying these things looks like this:

  1. Make changes I need.
  2. Run docker-compose build again.
  3. Run docker-compose down to stop the already running services.
  4. Run docker-compose up ... to start them once more.

The build process will pull in any changes it detects and rebuild (if needed). If you change the nodeos version or URL, it’s going to be a longer build. If you’re just changing configuration values the build shouldn’t take too long.



Thanks for this guide, i’m trying to run mainnet node. If i do docker-compose down then up again it will redownload the snapshot. Any way to keep it persistant ?

I took some peers from https://github.com/worldwide-asset-exchange/wax-blockchain/tree/develop/samples/mainnet but some are outdated, is there another list with all peers for wax ?

Also what is the nginx server for ? Proxying request to nodeos ?

Edit : i got some error with nginx docker yaml, there is mistake on volume mount, trying to mount file instead of directory + i got this error from nginx.conf so for now i commented the include mime.types line nginx_1 | 2021/12/02 03:15:10 [emerg] 1#1: open() "/etc/nginx/mime.types" failed (2: No such file or directory) in /etc/nginx/nginx.conf:21 nginx_1 | nginx: [emerg] open() "/etc/nginx/mime.types" failed (2: No such file or directory) in /etc/nginx/nginx.conf:21

It’s possible, but it’d require some modification of the github repository to make it happen. You’d need to use volumes and do some moving of data during startup/shutdown probably.

If it’s only the download you’re concerned about - you could always use a local snapshot for the NODEOS_SNAPSHOT in the .env file, and have it point to a server you’re running on the local network or host. It’ll still start from a snapshot, but won’t need to download.

This is an automatically updated list: https://validate.eosnation.io/wax/reports/config.html

Yep, nginx is better suited for SSL management, caching, and a number of other things instead of directly exposing nodeos. It also allows you to load balance between multiple nodeos instances.

We’ll have to look at that one - that should exist as part of the nginx container :thinking:

Indeed, i can use the snapshot as i intend to run it h24, otherwise i understand i would need to copy /ramdisk into a volume before shutdown then restore it on startup. I’ll setup a local http server to cache the snapshot during my tests.

Thanks for the peers list, gonna update mine. Regarding the good amount of disk space needed, right now i have only 32GB of space used and the node is running but i haven’t history api nor chain api enabled, i guess that’s why. I could try to enable the chain api but i heard i will need 10TB ssd for the history one, maybe next year when i will get more hardware.

Those two strategies may not work well together, since the contents of the ramdisk are reset if you restore a snapshot. You realistically should only have to do one or the other (I think), either restore the state on the ramdisk or start from a snapshot.

The blocks log may fill that up pretty quick. If you use nodeos 2.1 you can enable the block log trimming and maintain it at a reasonable size though, and that should work. With only 32gb of space you may need to lower these values:

That’s one days worth of blocks to store in the container - which I wouldn’t be surprised if pushes 30gb at times.