Introduction

The Avalanche Platform supports TPS in the thousands, approximately 1 second finality on a permissionless network, proof of stake sybil protection, and an extensible architecture that enables assets to be created and exchanged quickly and with ease. The crypto community has been curious to see what Avalanche developers have been building this year. With the Borealis release of the Avalanche Gecko client, the code is now open to run and test.

New users want to get up and running; the Avalanche community is here to help. This tutorial is a guide to running a local network so anyone can immediately begin testing against the upcoming Avalanche Platform. To assist in this, we’re going to step through the process of installing Gecko (the Avalanche Go client) and Avash (the Avalanche node launcher).

Prerequisites

In order to run the software it is required that users are comfortable with navigating command line environments. The heaviest testing on this release has been done on Ubuntu 18.04, but there are several options available for other operating systems on http://docs.ava.network. Please check out those docs for frequent updates as well. As node software is upgraded, changes will be reflected in the docs.

Requirements for a single node are:

Hardware: 2 GHz or faster CPU, 3 GB RAM, 250 MB hard disk.

OS: Ubuntu >= 18.04 or Mac OS X >= Catalina.

Software: Go version == 1.13.X and set up $GOPATH. (Official Instructions)

Network: IPv4 or IPv6 network connection, with an open public port.

Support for higher versions of Go is not present in this release, though this is something that is planned to be patched in a later build.

To launch a local network on one machine we’ll be using 4 nodes so a machine around twice as powerful is advisable.

The machine also needs the following tools and libraries installed:

libssl-dev

libuv1-dev

cmake

make

curl

g++/clang++ that supports c++14 (to build salticidae C++ library)

The command to install these dependencies on Ubuntu 18.04 is:

sudo apt-get install curl build-essential libssl-dev libuv1-dev cmake make

Install Gecko — The Avalanche Go Client

The Go implementation of the Avalanche client, Gecko, is included in this code release. It’s the node we’ll be using for launching a network on the local machines. It’s very feature-rich with a wide list of APIs available, documented here: https://docs.ava.network/v1.0/en/api/intro-apis/.

Go get Gecko

To install Gecko we’re going to grab the software directly using the “go get” command:

go get -d -v github.com/ava-labs/gecko/...

This should pull down the entire Gecko client into our $GOPATH .

Note: There may be a warning presented:

package github.com/ava-labs/gecko: no Go files in /home/ccusce/.gvm/pkgsets/go1.13/global/src/github.com/ava-labs/gecko

If this warning appears, it can be ignored. It is not an error, just Go telling the user there’s no `*.go` files in the root of Gecko. This is because Gecko uses its own build script. Future releases should suppress this warning.

Build from source code

Now that we have Gecko pulled down, we need to build the client. To do that, just hop into our “gecko” folder and build the source:

cd $GOPATH/src/github.com/ava-labs/gecko

./scripts/build.sh

If all goes well we should see something like this when checking the “build” directory:

ccusce@AVAccusce:~/.gvm/pkgsets/go1.13/global/src/github.com/ava-labs/gecko$ cd build/

ccusce@AVAccusce:~/.gvm/pkgsets/go1.13/global/src/github.com/ava-labs/gecko/build$ ls -al

total 58644

drwxr-xr-x 2 ccusce ccusce 4096 Mar 3 19:48 .

drwxr-xr-x 20 ccusce ccusce 4096 Mar 3 19:48 ..

-rwxr-xr-x 1 ccusce ccusce 34411024 Mar 3 19:48 ava

-rwxr-xr-x 1 ccusce ccusce 25625592 Mar 3 19:48 xputtest

ccusce@AVAccusce:~/.gvm/pkgsets/go1.13/global/src/github.com/ava-labs/gecko/build$ cd ..

But if we want to verify that all went well, we can also run the following:

./scripts/build_test.sh

If all tests pass, we’re good to go! If not, pop into our Discord and say hello to the Avalanche dev team to let us help with the process.

Install Avash — The Avalanche Node Launcher

Avash is a tool specifically made to make launching a node an easy and repeatable process. Avash splits local node’s databases and log files into their own stashes. Using Avash we can author scripts that enable launching networks of various custom templates. Avash even cleans up the launched nodes once the client exits.

We’re going to use Avash to deploy a four-node network on our local machine, so let’s install it!

Go get Avash

Much like our Gecko install, we’re going to use the “go get” command to install Avash:

go get github.com/ava-labs/avash

Build from source

Now that we pulled the source down for Avash, we’re going to build the source code.

cd $GOPATH/src/github.com/ava-labs/avash

go build

That should be it! We’ll see the “avash” executable in “$GOPATH/src/github.com/ava-labs/avash”.

Configure the client

The first time Avash is run, it will create an empty configuration file in our home directory.

$ ./avash

Config file not found: .avash.yaml

Created empty config file: /home/ccusce/.avash.yaml

Config file set: /home/ccusce/.avash.yaml

Avash successfully configured.

avash>

Starting Avash

Once those configurations are set up, Avash is launched by calling:

./avash

To see the commands available, at the Avash prompt type:

avash> help

To see help for a specific command, type “help” followed by that command name. For example, to learn more about the “procmanager” command, type:

avash> help procmanager

If any of this does not work, hop into the Avalanche Discord and ask the devs for assistance.

Test the Setup

Congratulations! We now have everything we need to launch a network on our local machine. This network will last as long as the Avash console is open. As soon as we call “exit” in the Avash console, Avash’s process will close and clean up all the nodes, leaving behind only their logs and databases.

Launch a local network with Avash

In order to make launching a test network simple, Avash has a set of example scripts which will enable the user to quickly deploy a network. We can build our own scripts as well, but for the purpose of this tutorial we’re going to create a network using the premade script “four_node_network.lua”. To execute this script, run the following command in the Avash console:

avash> runscript scripts/four_node_network.lua

Amazing! Four nodes, one machine, all ready to process transactions and node requests through our handy-dandy APIs described on https://docs.ava.network .

Let’s take a glimpse at our running nodes in the Avash console by calling:

avash> procmanager list

We should see something like the following:

Identify the RPC node and send a test command

Now that we have our local network running, let’s identify the API node. One of these nodes is called “apinode”. All of the APIs support JSON-RPC to send requests. More information about JSON-RPC 2.0 can be learned at: https://www.jsonrpc.org/

Notice that the script we ran used “127.0.0.1” as our IP address, otherwise known as “localhost” on most systems. It also opened the “http-port” to 9650. This will be the IP and Port combination we’ll use for the API endpoints. To test this, we’ll fire off our first command, “peers()” which should return the other three nodes with which we’re connected. To do this, we open another terminal window separate from Avash, and using “curl”, we’ll send the following request to our API node:

curl -X POST --data '{

"jsonrpc":"2.0",

"id" :1,

"method" :"admin.peers"

}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin

Which should return a complete list of peers:

{

"jsonrpc":"2.0",

"result":{

"peers":[

"127.0.0.1:9155",

"127.0.0.1:9156",

"127.0.0.1:9157"

]

},

"id":1

}

Congratulations! We’ve launched our first Avalanche Network! There’s much more that can be done with the Avalanche Platform listed in our documentation: https://docs.ava.network

A graceful exit

One of the best parts of Avash is that it cleans our environment for us. We just have to type “exit” and all of our nodes exit gracefully, cleaning up after themselves and not leaving hanging processes around. The logs of our session remain in our log directory, as well as the database of our nodes that we ran.

Next Steps

Now that we can reliably launch nodes, we can start sending assets. In the next tutorials we’ll go over installing the Avalanche Wallet, the Avalanche Faucet, and explain how to learn more about working with our Javascript library, Slopes.

We hope this tutorial gives you a solid foundation for running and building on AVA. Please reach out via Discord if you need help getting AVA running and seeing what’s possible.