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 pages Bakerloo Testnet, Release 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
OS	Ubuntu 20.04 LTS	Ubuntu 20.04 LTS
CPU	3.10 GHz with 8 CPU’s	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 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.

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 20203 for node p2p (DEVp2p) communication for consensus gossiping (required if you are operating a validator node).
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/v0.14.1 -b v0.14.1
```
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 Bakerloo Testnet:
```
docker pull ghcr.io/autonity/autonity-bakerloo:latest
```
If you are deploying to the Piccadilly Testnet:
```
docker pull ghcr.io/autonity/autonity:v0.14.1
```
(where latest can be replaced with another version)

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 Bakerloo Testnet:

docker images --digests ghcr.io/autonity/autonity-bakerloo
REPOSITORY                           TAG       DIGEST                                                                    IMAGE ID       CREATED      SIZE
ghcr.io/autonity/autonity-bakerloo   latest    sha256:9927fc07f0db07e3d18d9c290fd1fbfc509558adf0250dec97b8d630fc7febc7   342dbfb45641   5 days ago   57MB

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   v0.14.1   sha256:0c2716615e47f22a5fb8b28f29f5b796ed45aaf75aa592ebed07f98de0a43374   c3e1d60a1853   22 hours ago    57.8MB

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: 0.14.1
Git Commit: a5d0ecda73fab7ea81c5eaf648f83f393f1728ec
Git Commit Date: 20240911
Architecture: amd64
Protocol Versions: [66]
Go Version: go1.22.0
Operating System: linux
GOPATH=
GOROOT=

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

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

Autonity
Version: 0.14.1
Architecture: amd64
Protocol Versions: [66]
Go Version: go1.22.0
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!