Installation from source code

This guide describes how to setup Lisk Service with PM2. Alternative options of how to install Lisk Service are described on the Setup page.

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

We recommend to use the latest LTS version. 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 the latest LTS version of Node.js using NVM:

Check for the latest LTS version
nvm ls-remote
[...]
v12.17.0   (LTS: Erbium)
v12.18.0   (LTS: Erbium)
v12.18.1   (LTS: Erbium)
v12.18.2   (LTS: Erbium)
v12.18.3   (Latest LTS: Erbium)
v13.0.0
v13.0.1
[...]
Install the latest LTS version
nvm install 12.18.3

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_12.x | sudo -E bash -
sudo apt-get install -y nodejs

macOS

For macOS, please execute the following command below:

brew install node@12

PostgreSQL

To install PostgresSQL follow the instructions below:

During this step it is possible to change your port if you wish to have more PostgresSQL instances in the future. Remember to adjust the environment variable POSTGRES_PORT accordingly in the configuration.

  • PostgresSQL with Docker

  • PostgresSQL system wide

Docker Setup

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

Installation

If you have other versions of PostgreSQL installed on your machine, ensure they are stopped before starting the Docker container.
How to install and start PostgreSQL with Docker
# Clone the Lisk Service repository
git clone https://github.com/LiskHQ/lisk-service.git
cd lisk-service/docker/postgres
# Start PostgreSQL
make up

The above commands should be enough to install PostgreSQL and set up the database ready to use with Lisk Service.

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

How to stop PostgreSQL with Docker
make down # to stop PostgreSQL
See instructions for macOS below.

Ubuntu

Firstly, install PostgreSQL on your machine as shown in the following commands listed below:

sudo apt-get purge -y postgres* (1)
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install -y postgresql-10
1 Remove all previously installed postgres versions.
In case of an EACCES error, it is recommended to check the following: Resolving EACCES permissions errors when installing packages globally. After the installation is completed it should be possible to see the Postgres database cluster by running the following commands listed below:
pg_lsclusters

Drop the existing database cluster, and replace it with a cluster with the locale en_US.UTF-8:

sudo pg_dropcluster --stop 10 main
sudo pg_createcluster --locale en_US.UTF-8 --start 10 main

Create a new database user called lisk and grant it rights to create databases. Then create the database lisk with the lisk user as owner. Finally, define the password for the lisk user:

sudo -u postgres -i createuser --createdb lisk
sudo -u postgres -i createdb lisk --owner lisk
sudo -u postgres psql -d lisk -c "alter user lisk with password 'password';"
Please change the password to a secure password of your choice. In addition, do not forget to update this password in the Lisk Service configuration afterwards.

macOS

To install the PostgreSQL version 10 execute the following command below:

brew install postgresql@10

The next step is to execute the following commands in order to have the PostgreSQL commands (e.g. psql), in your PATH:

echo 'export PATH="/usr/local/opt/postgresql@10/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Start the PostgreSQL, and create the lisk user and the database by executing the following commands below:

pg_ctl -D /usr/local/var/postgresql@10 start
createuser lisk
createdb --owner=lisk lisk
psql --dbname=lisk --command="ALTER USER lisk WITH PASSWORD 'password';"
Please change the password to a secure password of your choice. In addition, do not forget to update this password in the Lisk Service configuration afterwards.

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

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 vx.y.z

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