Install Autonity Oracle Server in your environment

How to install an Autonity Oracle Server on your host machine.

Overview

The Autonity Oracle Server can be installed in several ways:

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

We assume that the Autonity Oracle Server will run on a host machine (a VPS or other host that is always-on and persistently available), and a distinct host machine will be used for Autonity Go Client the oracle serves via the WSS endpoint.

Note

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

Before installing verify the correct Autonity Oracle Server release version to use 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 Oracle Server, 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	1.9GHz with 4CPU’s	1.9GHz with 4CPU’s
RAM	2GB	4GB
Storage	32GB	64GB
Network interface	64Mbit/s	128Mbit/s

Network

A public-facing internet connection with static IP is required. Incoming traffic must be allowed on the following:

TCP 8546 to make WebSocket RPC connections to the node.

Note

Your validator node’s installation must also allow traffic on your validator node’s port TCP 8546 to allow the Oracle Server’s WebSocket RPC connection to the node.

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

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 Oracle Server Releases Archive and download the latest stable release version of the Autonity Oracle Server autoracle-linux-amd64-<RELEASE_VERSION>.tar.gz from the Assets section.
Create a working directory for installing Oracle Server. For example:
```
mkdir autonity-oracle
cd autonity-oracle
```
Unpack the downloaded tarball to your working directory:
```
tar -xf <PATH_TO_DOWNLOADS_DIRECTORY>/autoracle-linux-amd64-<RELEASE_VERSION>.tar.gz
```
This will unpack the pre-compiled executable, a /plugins subdirectory containing data source plugins packaged in the release, and a plugins-conf.yml configuration file.
(Optional) Add data source plugins. Navigate to the plugins sub-directory of your working directory and add sub-directories for additional plugins you are installing.
(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 autoracle /usr/local/bin/autoracle
```

Info

You can now configure and launch Autonity Oracle Server.

Build from source code

Prerequisites

The following should be installed in order to build the Autonity Oracle Server:

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 Oracle Server repo:

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

Enter the autonity-oracle directory and build autonity oracle server. ```

This will build the executable (./build/bin/autoracle) and create a subdirectory containing data source plugins packaged in the release (./build/bin/plugins/).

Adjust the make command according to the testnet you are connecting to.

If connecting to Piccadilly Testnet, run:
```
cd autonity-oracle
make autoracle
```
If connecting to Bakerloo Testnet, run:
```
cd autonity-oracle
make autoracle-bakerloo
```
(Optional) Add data source plugins. Navigate to the plugins sub-directory of your working directory and add sub-directories for additional plugins you are installing. See Installing data source plugins.
(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/autoracle /usr/local/bin/autoracle
```

Info

You can now configure and launch Autonity Oracle Server.

Installing the Docker image

Note

Follow the official Docker documentation to install Docker onto the host machine and follow the post-installation steps to customize 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

Create a working directory and CD to your working directory:
```
mkdir autonity-oracle && cd autonity-oracle
```
Pull the Autonity Oracle Server image from the GitHub Container Registry.

If you are deploying to the Bakerloo Testnet:
```
docker pull ghcr.io/autonity/autonity-oracle-bakerloo:latest
```
If you are deploying to the Piccadilly Testnet:
```
docker pull ghcr.io/autonity/autonity-oracle-piccadilly:latest
```
(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 Oracle Server Docker images against the official image digests:

If you are deploying to the Bakerloo Testnet:

docker images --digests ghcr.io/autonity/autonity-oracle-bakerloo
REPOSITORY                                  TAG       DIGEST                                                                    IMAGE ID       CREATED       SIZE
ghcr.io/autonity/autonity-oracle-bakerloo   latest    sha256:f37cdf332bab761426f94a6b6f8e670efc7b95e4470bc9a4ce1151d48baff791   d6cc39e078f6   2 weeks ago   111MB

If you are deploying to the Piccadilly Testnet:

docker images --digests ghcr.io/autonity/autonity-oracle-piccadilly
REPOSITORY                                    TAG       DIGEST                                                                    IMAGE ID       CREATED        SIZE
ghcr.io/autonity/autonity-oracle-piccadilly   latest    sha256:aa0192ce1d72b1a6d5ad971e8d10a8dbc32004f4ea1d3da7217b80ec8b6a363e   78446bd6c4b6   2 weeks ago    111MB

Data source plugins. Note that the data source plugins are included as part of the Docker image at the directory path /usr/local/bin/plugins.

Info

You can now configure and launch oracle server.

Verify the installation

You should now be able to execute the autoracle command. Verify your installation by executing autoracle version to return the oracle version and configuration:

$ ./build/bin/autoracle version

v0.1.9

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

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

v0.1.9

Note

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

Installing data source plugins

Oracle server will need to provide price data for FX and ATN and NTN currency pairs utilized in the Auton Stabilization Mechanism.

A basic set of data adaptor plugins for sourcing this data is provided out the box with oracle server for testnet pre-Mainnet:

Forex plugins: for connecting to public FX data sources. See the forex_ prefixed adaptors in /plugins. Four forex plugins are currently provided.
ATN and NTN plugins:
- For connecting to Piccadilly Testnet. See the pcgc_cax adaptor in /plugins. This provides ATN and NTN data from the Centralized Auton Exchange deployed to Piccadilly for the Piccadilly Circus Games Competition. See game.autonity.org.
- For connecting to Bakerloo Testnet. See the sim_plugin adaptor in /plugins. This provides simulated ATN and NTN data.

These out the box plugins are built and included by default according to the installation method and Autonity testnet chosen. They are:

Built by the make process when building from source. Run the make command appropriate for the Testnet you are connecting to as described in Build from source code. You can view the built plugins in the directory ./build/bin/plugins.
Included pre-built as part of the pre-built executable. You can view the built plugins in the directory /plugins. The executable is built for Piccadilly Testnet only.
Included pre-built as part of oracle server Docker image and the pre-built executable. Install the Docker image for the Testnet you are connecting to as described in Installing the Docker image. The built plugins are included in the Docker container at the path /usr/local/bin/plugins.

Note

The Simulator plugin for simulated ATN and NTN price data is built when building from source for Bakerloo Testnet. You can also build the Simulator plugin independently by running the command make simulator. This will build the sim_plugin in the /plugins directory. A local testnet could be a scenario for setting up and using a simulator.

If you have developed your own plugins for external data sources using the oracle server’s plugin template architecture, then you will need to build them and add to the /plugins directory.

For how to do this, see Developing data plugins.

Next steps

Info

You can now configure and launch the oracle server.

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