Prerequisites

Dependencies

The following dependencies must be installed in order to run applications created with the Lisk SDK:

Dependencies Version

Node.js

v12 (LTS)

PostgreSQL

10+

Redis (optional)

5+

Python

2

Ports

Mandatory: Always open the WebSocket port of your desired network, to enable communication with other peer nodes.

Optional: Open the corresponding HTTP port for your network, to ensure your node’s API is reachable.

To connect to the desired network, ensure that the corresponding ports are open:

Network HTTP WebSocket

Devnet

4000

5000

These ports can be altered later in the configuration file.

Prerequisites

Create a new user

To install the required prerequisites, it is necessary to have a user with sudo rights on the server. The lisk user itself does not need any sudo rights to run the node.

How to run and manage a node in the future, and create a separate lisk user:

  • Ubuntu

  • MacOS

sudo adduser lisk

It is not mandatory to set up a lisk user, especially when running a local instance for development purposes. However, if it is required then it is recommended to create the user using the macOS GUI.

Toolchain components

This is used for compiling dependencies.

  • Ubuntu

  • MacOS

sudo apt install -y libtool automake autoconf curl python-minimal build-essential

Ensure that both XCode and Homebrew are installed.

brew install autoconf automake libtool

PostgreSQL

To install PostgreSQL please follow the instructions described below.

It is recommended to use PostgreSQL with Docker for a quick and straight forward setup of PostgreSQL, and also PostgreSQL system-wide for production environments.
  • PostgreSQL system wide

  • PostgreSQL with Docker

Please see the instructions for the MacOS listed below.

Ubuntu

Firstly, install PostgreSQL on your machine as shown 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'
sudo apt install wget ca-certificates
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install postgresql-10
1 Remove all previously installed postgres versions.

After the installation is completed, it will be possible to see the PostgreSQL database cluster by running the following command:

pg_lsclusters

Drop the existing database cluster as shown below, 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 access rights to create databases. Then create the database with the lisk user as the owner. Finally, define the password for the lisk user as shown below:

If the following error occurs: could not change directory to "/root": Permission denied this can be ignored. The command will be executed regardless.

sudo -u postgres -i createuser --createdb lisk
sudo -u postgres -i createdb lisk_dev --owner lisk
sudo -u postgres psql -d lisk_dev -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 SDK configuration later.

MacOS

How to install the PostgreSQL version 10:

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:

pg_ctl -D /usr/local/var/postgresql@10 start
createuser lisk
createdb --owner=lisk lisk_dev
psql --dbname=lisk_dev --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 SDK configuration later.

Running PostgreSQL inside a Docker container will set up the correct version of PostgreSQL and containerize it away from any existing versions that may be present locally on your machine. Please choose this set up if you are unfamiliar with PostgreSQL, or if problematic issues with a previously installed version of PostgreSQL have occured.

Supported platforms: For further information please refer to the following link: Docker installation

Install Docker

To install Docker please refer to the applicable link listed below for your operating system:

Mac OS X

Please refer to Mac installation. Please note that Docker for Mac already includes Docker Compose. Install make using XCode

Linux

Please refer to Linux installation

Start the Docker container.

If you have other versions of PostgreSQL installed on your machine, please ensure to stop them before starting the docker container.
docker run --name lisk_db -p 5432:5432 -e POSTGRES_USER=lisk -e POSTGRES_PASSWORD=password -e POSTGRES_DB=lisk_dev -d postgres:10

This will install PostgreSQL version 10 (postgres:10) in a container with name lisk_db and binds the port 5432 of the container with the same port of the machine. As environment variables we expose POSTGRES_USER=lisk to create the lisk user and POSTGRES_PASSWORD=password to set the password for the lisk user. Finally the environment variable POSTGRES_DB creates the database lisk_dev with the lisk user as owner.

The above should be enough to set up the database ready to use with the Lisk SDK. To manage the Docker container, use the following commands:

docker stop lisk_db (1)
docker start lisk_db (2)
docker restart lisk_db (3)
docker rm lisk_db (4)
1 Stop the container.
2 Start the container.
3 Restart the container.
4 Remove the container.

The following command will enable access to PostgreSQL inside the container via the CLI:

docker exec --tty --interactive lisk_db psql -h localhost -U lisk -d postgres

Node.js

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

Change to the lisk user to install Node.js by executing the following command:

sudo -u lisk -i
  • 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 which enables the management of multiple active Node.js versions.

  1. To install nvm, please follow these instructions.

  2. Install the latest LTS version of Node.js:

nvm install 12.18.4

Alternatively, instead of using the NVM or other package managers, the node package can be installed globally as shown below:

Ubuntu

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

MacOS

Please install node@12.18.4 with brew to complete the installation, as shown below:

brew install node@12.18.4
echo 'export PATH="/usr/local/opt/node@10/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

PM2 (optional)

How to install PM2 for managing the start/stop process of the application in the background:

npm install pm2 -g

Installation

How install the NPM package lisk-sdk:

npm install lisk-sdk@4.0.0

After successful completion of all the above steps, the Lisk SDK and all required dependencies should now be installed.

The next step is to head to the Guides section to learn how to build a blockchain application with the Lisk SDK, or directly head to the Tutorials to learn how to build proof of concept blockchain applications for real industry use cases.