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:
- 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.
- 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.
- 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:
- Builds the nodeos binary based on the repository and branch/tag specified.
- Downloads a recent snapshot of the blockchain to initialize from.
- 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)
NETWORK_NAME=wax
# The port to expose the nodeos api(s) on the host machine
NETWORK_PORT_API=38888
# The port to expose the nodeos p2p procotol on the host machine
NETWORK_PORT_P2P=39876
# The git repository of the nodeos (EOSIO) repository to use
NODEOS_REPOSITORY=https://github.com/cc32d9/wax2.0.git
# The branch/tag of nodeos to checkout during the build process
NODEOS_VERSION=v2.0.12wax02
# A snapshot (compressed as tar.gz) to use during the startup of this node
NODEOS_SNAPSHOT=https://snapshots.testnet.waxsweden.org/snapshots/e35d29/2.0/latest
# 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:
- Make changes I need.
- Run
docker-compose buildagain. - Run
docker-compose downto stop the already running services. - 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.
