Skip to content

Manual Installation

This section describes how to manually install Hyperion and its environment. If you want more control of your installation, this is the way to go.

Attention

Recommended OS: Ubuntu 20.04

Dependencies

Below you can find the list of all Hyperion's dependencies:

On the next steps you will install and configure each one of them.

Note

The Hyperion Indexer requires Node.js and pm2 to be on the same machine. All other dependencies (Elasticsearch, RabbitMQ, Redis and EOSIO) can be installed on different machines, preferably on a high speed and low latency network. Keep in mind that indexing speed will vary greatly depending on this configuration.

Elasticsearch

Follow the detailed installation instructions on the official Elasticsearch documentation and return to this guide before running it.

Info

Elasticsearch is not started automatically after installation. We recommend running it with systemd.

Note

It is very important to know the Elasticsearch directory layout and to understand how the configuration works.

Configuration

1. Elasticsearch configuration

Edit the following lines on /etc/elasticsearch/elasticsearch.yml:

cluster.name: CLUSTER_NAME
bootstrap.memory_lock: true

The memory lock option will prevent any Elasticsearch heap memory from being swapped out.

Warning

Setting bootstrap.memory_lock: true will make Elasticsearch try to use all the RAM configured for JVM on startup ( check next step). This can cause the application to crash if you allocate more RAM than available.

Note

A different approach is to disable swapping on your system.

Testing

After starting Elasticsearch, you can see whether this setting was applied successfully by checking the value of mlockall in the output from this request:

curl -X GET "localhost:9200/_nodes?filter_path=**.mlockall&pretty"
2. Heap size configuration

For a optimized heap size, check how much RAM can be allocated by the JVM on your system. Run the following command:

java -Xms16g -Xmx16g -XX:+UseCompressedOops -XX:+PrintFlagsFinal Oops | grep Oops

Check if UseCompressedOops is true on the results and change -Xms and -Xmx to the desired value.

Note

Elasticsearch includes a bundled version of OpenJDK from the JDK maintainers. You can find it on /usr/share/elasticsearch/jdk.

After that, change the heap size by editting the following lines on /etc/elasticsearch/jvm.options:

-Xms16g
-Xmx16g

Note

Xms and Xmx must have the same value.

Warning

Avoid allocating more than 31GB when setting your heap size, even if you have enough RAM.

3. Allow memory lock

Override systemd configuration by running sudo systemctl edit elasticsearch and add the following lines:

[Service]
LimitMEMLOCK=infinity

Run the following command to reload units:

sudo systemctl daemon-reload
4. Start Elasticsearch

Start Elasticsearch and check the logs:

sudo systemctl start elasticsearch.service
sudo less /var/log/elasticsearch/CLUSTE_NAME.log

Enable it to run at startup:

sudo systemctl enable elasticsearch.service

And finally, test the REST API:

curl -X GET "localhost:9200/?pretty"

Note

Don't forget to check if memory lock worked.

The expected result should be something like this:

{
  "name": "ip-172-31-5-121",
  "cluster_name": "CLUSTER_NAME",
  "cluster_uuid": "FFl8DNcOQV-dVk3p1JDNMA",
  "version": {
    "number": "7.14.1",
    "build_flavor": "default",
    "build_type": "deb",
    "build_hash": "606a173",
    "build_date": "2021-08-26T00:43:15.323135Z",
    "build_snapshot": false,
    "lucene_version": "8.9.0",
    "minimum_wire_compatibility_version": "6.8.0",
    "minimum_index_compatibility_version": "6.0.0-beta1"
  },
  "tagline": "You Know, for Search"
}
5. Set up minimal security

The Elasticsearch security features are disabled by default. To avoid security problems, we recommend enabling the security pack.

To do that, add the following line to the end of the /etc/elasticsearch/elasticsearch.yml file:

xpack.security.enabled: true

Restart Elasticsearch and set the passwords for the cluster:

sudo systemctl restart elasticsearch.service
sudo /usr/share/elasticsearch/bin/elasticsearch-setup-passwords auto

Keep track of these passwords, we’ll need them again soon.

Note

You can alternatively use the interactive parameter to manually define your passwords.

Attention

The minimal security scenario is not sufficient for production mode clusters. Check the documentation for more information.

Kibana

Follow the detailed installation instructions on the official Kibana documentation. Return to this documentation before running it.

Info

Kibana is not started automatically after installation. We recomend running it with systemd.

Note

Like on Elasticsearch, it is very important to know the Kibana directory layout and to understand how the configuration works.

Configuration

1. Elasticsearch security

If you have enabled the security pack on Elasticsearch, you need to set up the password on Kibana. Edit the folowing lines on the /etc/kibana/kibana.yml file:

elasticsearch.username: "kibana_system"
elasticsearch.password: "password"
2. Start Kibana

Start Kibana and check the logs:

sudo systemctl start kibana.service
sudo less /var/log/kibana/kibana.log

Enable it to run at startup:

sudo systemctl enable kibana.service

RabbitMQ

Follow the detailed installation instructions on the official RabbitMQ documentation.

RabbitMQ should automatically start after installation. Check the documentation for more details on how to manage its service.

Configuration

1. Enable the WebUI
sudo rabbitmq-plugins enable rabbitmq_management
2. Add vhost
sudo rabbitmqctl add_vhost hyperion
3. Create a user and password
sudo rabbitmqctl add_user USER PASSWORD
4. Set the user as administrator
sudo rabbitmqctl set_user_tags USER administrator
5. Set the user permissions to the vhost
sudo rabbitmqctl set_permissions -p hyperion USER ".*" ".*" ".*"
6. Check access to the WebUI

Try to access RabbitMQ WebUI at http://localhost:15672.

Redis

sudo apt install redis-server

Redis will also start automatically after installation.

Configuration

1. Update Redis supervision method

Change the supervised configuration from supervised no to supervised systemd on /etc/redis/redis.conf.

Note

By default, Redis binds to the localhost address. You need to edit bind in the config file if you want to listen to other network.

2. Restart Redis
sudo systemctl restart redis.service

NodeJS

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

Attention

Make sure to configure npm not to use sudo when installing global packages.

PM2

npm install pm2@latest -g

Configuration

1. Configure for system startup
pm2 startup

EOSIO

wget https://github.com/eosio/eos/releases/download/v2.1.0/eosio_2.1.0-1-ubuntu-20.04_amd64.deb
sudo apt install ./eosio_2.1.0-1-ubuntu-20.04_amd64.deb

Configuration

Add the following configuration to the config.ini file:

state-history-dir = "state-history"
trace-history = true
chain-state-history = true
state-history-endpoint = 127.0.0.1:8080
plugin = eosio::chain_api_plugin
plugin = eosio::state_history_plugin

Hyperion

test If everything runs smoothly, it's time to install Hyperion!

To do that, simply run the following commands:

git clone https://github.com/eosrio/hyperion-history-api.git
cd hyperion-history-api
npm install