Installation from source code

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

Install from source code if you want to customize the codebase of Lisk 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 Lisk Service codebase.

Pre-requisite

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

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

  • Alternatively, you can set up a sidechain node to connect to Lisk 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 Lisk 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.

Lisk Service, by default, expects a MySQL user lisk with the password password and a database lisk.

The MySQL user lisk 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 Lisk 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 mysql@8.0
brew services start mysql@8.0
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 Lisk 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 Lisk Service repository.

The above commands should be enough to start Redis which is ready to use with Lisk 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 Lisk Service and also offers easy log rotation (Highly Recommended).

npm install -g pm2

Installation

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

Clone Lisk Service repository
git clone https://github.com/LiskHQ/lisk-service.git
Change directory to the new repository
cd lisk-service
Switch to the recent stable as a base
git checkout v0.7.0
...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 Lisk Service.

Start Lisk 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 Lisk Service are described on the PM2 commands page.