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.


Recommended OS: Ubuntu 22.04


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

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


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.


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


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


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


1. Elasticsearch configuration

Edit the following lines on /etc/elasticsearch/elasticsearch.yml: CLUSTER_NAME
bootstrap.memory_lock: true

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


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.


A different approach is to disable swapping on your system.


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.


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:



Xms and Xmx must have the same value.


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:


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"


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: 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.


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


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


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


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


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


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



From Hyperion 3.3.10, RabbitMQ version 3.12+ is required.

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.


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 with the user and password you just created.


sudo apt install redis-server

Redis will also start automatically after installation.


1. Update Redis supervision method

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


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


curl -fsSL | sudo -E bash -
sudo apt-get install -y nodejs


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


npm install pm2@latest -g


1. Configure for system startup
pm2 startup


sudo apt install ./leap_3.2.1-ubuntu22.04_amd64.deb


Add the following configuration to the config.ini file:

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


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

To do that, simply run the following commands:

git clone
cd hyperion-history-api
npm install

Proceed with Hyperion Configuration

Hyperion Setup