Install Autonity in your environment

How to install an Autonity Go Client node on your host machine.

Overview

The Autonity Go Client can be installed in several ways:

as a pre-compiled Linux Executable File from the Release Archive
by building the client from source code
in a Docker container.

We assume that the Autonity Go Client will run on a host machine (a VPS or other host that is always-on and persistently available), and a distinct local machine will be used for creating transactions and queries which are then sent to the Autonity Go Client on the host via the RPC endpoint.

It is recommended not run Autonity using Docker containers outside of a test environment.

Note

Client source code is versioned on a 3-digit major.minor.patch versioning scheme, and hosted and maintained in the public GitHub repo autonity.

Before installing verify the correct Autonity Go Client release version to install for the network you are connecting to. See the Networks page and Piccadilly Testnet, Release for the versions deployed.

Requirements

Hardware

To run an Autonity Go Client node, we recommend using a host machine (physical or virtual) with the following minimum specification:

Requirement	At least	Recommended
CPU	x86_64 architecture, 3.10 GHz with 8 CPU’s	x86_64 architecture, 3.10 GHz with 16 CPU’s
RAM	8GB	16GB
Storage	1024GB free storage for full nodes and Validators	1024 GB free storage for full nodes and validators
Network interface	200 Mbit/s	200 Mbit/s

Network

A public-facing internet connection with static IP is required:

If you are using a cloud provider for node hosting, then a static IP address for your cloud space should be a stated hosting requirement. Cloud vendors typically don’t supply a static IP address unless it is purchased explicitly.

Why is a static IP Address required?

Running an Autonity node requires that you maintain a static ip address because the ip address forms part of the node’s network address, the enode URL. I.e. the IP address should not dynamically change due to resetting by the IP provider.

The enode provides the network location of the node client for p2p networking. Changing the ip address will change the node’s identity on the network, therefore. This is significant if you are operating a validator node as the enode is provided as part of the validator meta data when registering the node as a validator. If a validator node needs moving to a new IP address after registration, then follow the steps in the guide Migrating a validator node to an new IP/Port address.

Incoming traffic must be allowed on the following:

TCP, UDP 30303 for node p2p (DEVp2p) communication for transaction gossiping.

Incoming traffic must also be allowed on the following if you are operating a validator node:

TCP 20203 for node p2p (DEVp2p) communication for consensus gossiping.

Autonity’s networking layer separates transaction and consensus gossiping

Autonity logically and physically segregates P2P networking protocols into different channels for transaction and consensus gossiping. Transaction traffic runs on the ethereum wire protocol; consensus traffic runs alongside that as a separate Autonity Consensus Network (ACN). This ensures that queued transaction traffic does not delay consensus traffic.

If you are operating a validator node, then you will need to open the ports for both transaction and consensus gossiping channels to incoming traffic. See separate channels for transaction and consensus gossiping for more detail.

You may also choose to allow traffic on the following ports:

TCP 8545 to make http RPC connections to the node.
TCP 8546 to make WebSocket RPC connections to the node (for example, if you are operating a validator node and your oracle server is hosted on a separate dedicated machine).
TCP 6060 to export Autonity metrics (recommended but not required)

Securing ports allowing incoming traffic

It is assumed that most administrators will want to restrict access to these ports (unless they wish to support public access to the RPC calls for anonymous clients). However, you should ensure that you can connect to one of the RPC ports from your local machine (e.g. with IP whitelisting in your firewall rules, SSH port forwarding or other technique).

The description here covers only the basic network setup. Especially in a production setting, administrators should consider further security measures based on their situation.

Security of your node installation

As a software system publicly accessible over the Internet, your node installation must be adequately secured!

Standard best practices for securing software allowing incoming traffic from the Internet are assumed. For example, firewalls and the configuration of reverse proxies, as well as additional steps required by your own best practices and security policies, are assumed.

Installing the pre-compiled executable

Note

A Linux OS running on AMD64 architecture is required to run the pre-compiled executable.

Navigate to the Autonity Releases Archive and download the latest stable release version of the client autonity-linux-amd64-<RELEASE_VERSION>.tar.gz from the Assets section.
Create a working directory for installing Autonity. For example:
```
mkdir autonity-go-client
cd autonity-go-client
```

Unpack the downloaded tarball to your working directory:

tar -xzf <PATH_TO_DOWNLOADS_DIRECTORY>/autonity-linux-amd64-<RELEASE_VERSION>.tar.gz

(Optional) Copy the binary to /usr/local/bin so it can be accessed by all users, or other location in your PATH :
```
sudo cp -r autonity /usr/local/bin/autonity
```

Info

You can now configure and launch Autonity.

Build from source code

Prerequisites

The following should be installed in order to build the Autonity Go Client:

Git Follow the official GitHub documentation to install git. (Check if installed: git --version)
Golang (version 1.21 or later) - https://golang.org/dl (Check if installed: go --version or go version)
C compiler (GCC or another) (Check if GCC is installed: gcc --version)
GNU Make (Check if installed: make --version)

Clone/Copy the Autonity repo:

git clone git@github.com:autonity/autonity.git

Enter the autonity directory and ensure you are building from the correct release. This can be done by checking out the Release Tag in a branch:
```
git checkout tags/v1.0.2-alpha -b v1.0.2-alpha
```
Build autonity:
```
make autonity
```
(The cmd utilities, including the Clef account management tool, can be built using make all.)
(Optional) Copy the generated binary to /usr/local/bin so it can be accessed by all users, or other location in your PATH :
```
sudo cp build/bin/autonity /usr/local/bin/autonity
```

Troubleshooting

An error of the form

Caught SIGILL in blst_cgo_init, consult <blst>/bindings/go/README.md.

thrown on the Go blst package (Go package docs when running the make command indicates missing environment variables for CGO Flags.

To resolve:

Set environment variables for CGO Flags:

export CGO_CFLAGS="-O -D__BLST_PORTABLE__" 
export CGO_CFLAGS_ALLOW="-O -D__BLST_PORTABLE__"

Run make clean to cleanse object and executable files from the previous make run

Re-run your make command.

Installing the Docker image

Note

Follow the official Docker documentation to install Docker onto the host machine and follow the post-installation steps to customise for your environment.

By default Docker needs to be run with sudo. To avoid using root privileges in the terminal (and error messages if you forget to use sudo), consider following the step to Manage Docker as a non-root user.

Consider also configuring Docker to start on boot.

Optional but Recommended

To limit the size of the log files, add the following to the file /etc/docker/daemon.json (create it if it does not exist):

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "500m",
    "max-file": "20"
  }
}

Restart the Docker service to ensure the change is reflected:

sudo systemctl restart docker

Pull the Autonity Go Client image from the Github Container Registry.

If you are deploying to the Piccadilly Testnet:
```
docker pull ghcr.io/autonity/autonity:latest
```
(where latest can be replaced with a specific version, i.e. v1.0.2-alpha)

Note

For more information on using and pulling Docker images from GHCR, see GitHub docs Working with the container registry.

Verify the authenticity of the Autonity Docker images against the official image digests:

If you are deploying to the Piccadilly Testnet:

docker images --digests ghcr.io/autonity/autonity
REPOSITORY                  TAG            DIGEST                                                                    IMAGE ID       CREATED        SIZE
ghcr.io/autonity/autonity   latest         sha256:6fdbaf8174da61da40a1fb6fe5b3f69e694ccd45ff00a7a25b96049c2fc64fbb   77e50240ec28   3 months ago   57.7MB
ghcr.io/autonity/autonity   v1.0.2-alpha   sha256:6fdbaf8174da61da40a1fb6fe5b3f69e694ccd45ff00a7a25b96049c2fc64fbb   77e50240ec28   3 months ago   57.7MB

Info

You can now configure and launch Autonity.

Verify the installation

You should now be able to execute the autonity command. Verify your installation by executing autonity version to return the client version and executable build details:

$ ./autonity version

Autonity
Version: 1.0.2-alpha
Git Commit: 8be1825ca7409a1bfd4d361356b2437839d4c383
Architecture: amd64
Protocol Versions: [66]
Go Version: go1.22.9
Operating System: linux
GOPATH=
GOROOT=

If using Docker, the setup of the image can be verified with:

$ docker run --rm ghcr.io/autonity/autonity:latest version

Autonity
Version: 1.0.2-alpha
Architecture: amd64
Protocol Versions: [66]
Go Version: go1.21.7
Operating System: linux
GOPATH=
GOROOT=/usr/local/go

Note

The output above will vary depending on the version of the Autonity Go Client you have installed. Confirm that the “Version” field is consistent with the version you expect.

Next steps

Info

You can now configure and launch Autonity.

If you need help, you can chat to us on Autonity Discord Server!