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

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

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

Prerequisites

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

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 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 expects a MySQL user lisk with password password and a database lisk.

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

These values can be updated by setting the environment variable SERVICE_CORE_MYSQL, see the Lisk Service Configuration Reference

  • Ubuntu

  • macOS

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

If you encounter issues to authenticate, and received the following error:

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

Try the following: Change the default_authentication_plugin using mysql_native_password.

Open up my.cnf .

If you are unsure where to find your my.cnf, use 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, you need to login via the terminal:

$ mysql -uroot

Then run the following command to update the root password:

ALTER USER 'root'@'localhost' 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
# Clone the Lisk Service repository
git clone https://github.com/LiskHQ/lisk-service.git
cd lisk-service/docker/redis
git checkout v0.6.6
make up # to start Redis

The above commands should be enough to install 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
make down # to stop Redis

Ubuntu

sudo apt-get install redis-server

macOS

brew install redis

PM2

PM2 manages the node process for Lisk Service and handles log rotation (Highly Recommended).

npm install -g pm2

Installation

It is strongly recommended that you synchronize your Lisk Core node with the network before starting the Lisk Service.

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

# ...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
npm run start

This will use the default configuration and connect Lisk Service to the Lisk Mainnet.

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.

Check the Usage section for examples of how to use and interact with Lisk Service.