Installation from source code

As an alternative to the Docker image setup, it is also possible to install Klayr Service from source code.

Install from source code if you want to customize the codebase of Klayr Service, e.g. if you want to adjust the API to be fully compatible with your blockchain application.

This setup requires more steps than the Docker image installation, however this provides the developer with the possibility to customize the Klayr Service codebase.

Pre-requisite

Klayr Service is a web application middleware that allows interaction with various blockchain networks based on the Klayr protocol. It is recommended to set up a blockchain node first, before setting up Klayr Service.

  • To set up a Klayr-Core node, see any of our setup guides, such as NPM setup.

  • Alternatively, you can set up a sidechain node to connect to Klayr Service.

  • Please make sure to set system.keepEventsForHeights: -1 in the node config before synchronizing the node with the network.

Prerequisites

The following dependencies are required to install and run Klayr Service from Source.

Requirements

Supported Platforms

  • Ubuntu 20.04 (LTS) x86_64

  • Ubuntu 22.04 (LTS) x86_64

  • MacOS x86_64

Node.js

  • 18

The following system requirements are recommended:

Memory

  • Machines with a minimum of 16 GB RAM for the Mainnet.

  • Machines with a minimum of 16 GB RAM for the Testnet.

Storage

  • Machines with a minimum of 40 GB HDD.

Update packages

  • Ubuntu

  • macOS

In Ubuntu and its derivatives APT is the base package management application. Ensure your local APT registry is up-to-date.

apt update

Install Brew by following the latest instructions.

Next, ensure your package sources are up to date:

brew update
brew doctor

Tool chain components

  • Ubuntu

  • macOS

Install the build-essential package alongside with several development tools.

sudo apt-get install -y build-essential git make
xcode-select --install

Node.js

Node.js serves as the underlying engine for code execution. There are several different methods and version managers used to install Node.js on your system. It is recommended to use one of the following two options:

  • Option A - Node version manager

  • Option B - Node.js package

It is recommended to use a Node version manager such as NVM. NVM is a bash script that enables the management of multiple active Node.js versions.

  1. Install NVM by following the official instructions.

  2. Install v18 of Node.js using NVM.

Check for the latest LTS version
nvm ls-remote
Install the latest LTS version
nvm install 18

If NVM or other package managers are not required, it is possible to install the Node package globally as shown in the following commands below:

Ubuntu

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

macOS

For macOS, please execute the following command below:

brew install node@18

MySQL

MySQL is used for storing persistent data.

Klayr Service, by default, expects a MySQL user klayr with the password password and a database klayr.

The MySQL user klayr needs to be manually created after installing MySQL.

You can choose to create a custom database with a different user and password. These values can be updated by setting the following environment variables (specific to each microservice): SERVICE_INDEXER_MYSQL, SERVICE_APP_REGISTRY_MYSQL and SERVICE_STATISTICS_MYSQL with the appropriate MySQL connection string. See the Klayr Service Configuration Reference

  • Ubuntu

  • macOS

sudo apt update
sudo apt install mysql-server=8.0*
sudo mysql_secure_installation
brew tap homebrew/services
brew install [email protected]
brew services start [email protected]
Authentication

If you encounter issues authenticating, and you received the following error:

caching_sha2_password' cannot be loaded: dlopen(/usr/local/lib/plugin/caching_sha2_password.so, 2): image not found

Try to perform the following: Change the default_authentication_plugin using the mysql_native_password.

Open up my.cnf .

If you are unsure where to find your my.cnf, run the following command:

mysql --verbose --help | grep my.cnf

Add the following at the end of the file:

default_authentication_plugin=mysql_native_password

Save and exit.

Next, login via the terminal:

mysql -uroot

Then run the following command to update the root password:

ALTER USER 'root'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY '';

Now you should be able to login to your MySQL 8 via your MySQL Client.

Redis

Redis is used for caching temporary data.

  • Redis with Docker

  • Redis system-wide

Docker Setup

Follow the steps described in the Prerequisites > Docker section of the "Installation with Docker" page.

Installation

How to install and start Redis with Docker
docker run --name redis_service --port 6379:6379 -d redis:7-alpine
How to use the custom redis.conf file
docker run --name redis_service -v /path/to/custom_redis.conf:/usr/local/etc/redis/redis.conf --port 6379:6379 -d redis:7-alpine
Starting with the Klayr Service version 0.7.2, we strongly recommend using custom authentication in Redis. To learn more about it, please check the Redis Authentication README in the Klayr Service repository.

The above commands should be enough to start Redis which is ready to use with Klayr Service.

To stop the Docker container again, execute the following commands below:

How to stop Redis with Docker
docker stop redis_service

Ubuntu

To install Redis on Ubuntu, please follow the official Redis installation guide.

macOS

To install Redis on MacOS, please follow the official Redis installation guide.

PM2

PM2 helps manage the node processes for Klayr Service and also offers easy log rotation (Highly Recommended).

npm install -g pm2

Installation

If you have not already done so, clone the klayr-service GitHub repository and then navigate into the project folder and check out the latest release.

Clone Klayr Service repository
git clone https://github.com/KlayrHQ/klayr-service.git
Change directory to the new repository
cd klayr-service
Switch to the recent stable as a base
git checkout v0.7.8
...or use the development branch
git checkout development

Install all npm dependencies from the root directory.

make build-local

Now it is possible to start Klayr Service.

Start Klayr Service from Source code
yarn run start

The default configuration in ecosystem.config.js should suffice in most of the cases. If necessary, please modify the file to configure the necessary environment variables for each microservice as per your requirements.

To change the default configuration, check out the page Configuration with PM2.

More commands about how to manage Klayr Service are described on the PM2 commands page.