Source code setup


To complete the installation some prerequisites need to be fulfilled. If you have already performed these, then please proceed to the Installation chapter.


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 in order to ensure your node’s API is reachable.

To connect to the desired network with Lisk Core, please ensure that the corresponding ports listed below are open:

Network HTTP WebSocket













These are the default ports for connecting with the network. They can be altered later in the config.json file.

Create a new user

To run and manage a Lisk Core node in the future, please create a separate lisk user as described below:

  • Ubuntu

  • MacOS

The lisk user itself does not need any sudo rights to run the Lisk Core.

sudo adduser lisk              (1)
1 Create a new user.

It is not necessarily required to set up a lisk user, especially when you are 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

These are used for compiling dependencies as displayed below:

  • Ubuntu

  • MacOS

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

Ensure that both XCode and Homebrew are installed.

brew install autoconf automake libtool


Git is used for cloning and updating Lisk as displayed below:

  • Ubuntu

  • MacOS

sudo apt install -y git
brew install git


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. Please ensure the latest LTS version is used. It is recommended to deploy one of the following two versions shown below:

  • 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 and follow the official instructions here.

  2. Install the latest LTS version of Node.js using NVM with the following command shown below:

nvm install 12.16.2

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:


curl -sL | sudo -E bash -
sudo apt-get install -y nodejs


For MacOS, please execute the following command below:

brew install node@12.16.2


To install PostgresSQL follow the instructions described below, dependent upon the operating system currently being used. In the case whereby problematic issues occur whilst setting up PostgreSQL on your machine, then it is recommended to try and install it inside of a docker container.

It is recommended to use PostgresSQL with Docker for a straight forward and fast setup of PostgresSQL.
  • PostgresSQL with Docker

  • PostgresSQL system wide

Running PostgresSQL inside a Docker container will setup the correct version of PostgresSQL and containerize it away from any existing versions that may exist locally on your machine. Choose this setup if you are unfamiliar with PostgresSQL, or if other issues occur with a previously installed version of PostgresSQL. To successfully perform the command shown below, install Docker as described in the Setup page of the Lisk Core Docker image.

If other versions of PostgreSQL are currently installed on your machine, please ensure they are stopped before starting the docker container.
docker run --name lisk_core_db -p 5432:5432 -e POSTGRES_USER=lisk -e POSTGRES_PASSWORD=password -e POSTGRES_DB=lisk_<NETWORK> -d postgres:10

This will install PostgreSQL version 10 (postgres:10) in a container with name lisk_core_db and binds the port 5432 of the container with the same port of the machine. As environment variables POSTGRES_USER=lisk is exposed in order to create the Lisk user, and POSTGRES_PASSWORD=password is used to set the password for the lisk user. Finally the environment variable POSTGRES_DB creates the database lisk_<NETWORK> with the lisk user as the owner.

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

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

In order to access PostgresSQL inside the container via CLI, execute the following command displayed below:

docker exec --tty --interactive lisk_core_db psql -h localhost -U lisk -d postgres
Please see the instructions for MacOS below.


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 $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
sudo apt install wget ca-certificates
wget --quiet -O - | sudo apt-key add -
sudo apt update
sudo apt install postgresql-10
1 Remove all previously installed postgresSQL versions.

After the installation is completed it should be possible to see the PostgresSQL database cluster by running the following commands listed below:


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

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 with the lisk user as the owner. In the last step, define the password for the lisk user:

sudo -u postgres -i createuser --createdb lisk
sudo -u postgres -i createdb lisk_<NETWORK> --owner lisk
sudo -u postgres psql -d lisk_<NETWORK> -c "alter user lisk with password 'password';"

<NETWORK> may be main for Mainnet, test for Testnet, or dev for Devnet.

Please change the password to a secure password of your choice. In addition, do not forget to update this password in the Lisk Core configuration afterwards.


Install PostgresSQL version 10 as shown below:

brew install postgresql@10

Execute the following code snippet to have PostgreSQL commands, (e.g. psql) in your PATH:

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

Start PostgreSQL, create the lisk user and the database as shown using the following commands listed below:

pg_ctl -D /usr/local/var/postgresql@10 start
createuser lisk
createdb --owner=lisk lisk_<NETWORK>
psql --dbname=lisk_<NETWORK> --command="ALTER USER lisk WITH PASSWORD 'password';"

<NETWORK> may be main for Mainnet, test for Testnet, or dev for Devnet.

Please change the password to a secure password of your choice. In addition, do not forget to update this password in the Lisk Core configuration afterwards.

PM2 (optional)

Install PM2 for managing the start and stop of the application process in the background as shown below:

npm install pm2 -g

Redis (optional)

  • Ubuntu

  • MacOS

sudo apt install redis-server

To start Redis execute the following command below:

sudo service redis-server start

To stop Redis execute the following command below:

sudo service redis-server stop
brew install redis

To start Redis execute the following command below:

brew services start redis

To stop Redis execute the following command below:

brew services stop redis

Please note that Lisk does not run on the Redis default port of 6379. Instead it is configured to run on port: 6380. Therefore in order to run Lisk, there are two options available which are listed below:

  • A - Change the Lisk configuration

  • B - Change the Redis launch configuration

In the next installation phase, please remember to update the Redis port configuration in config.json.

Update the launch configuration file on your system. Note that there are numerous methods to perform this.

The following is one example:

  1. Stop the Redis-server

  2. Edit the file redis.conf and change: port 6379 to port 6380

    • Ubuntu/Debian: /etc/redis/redis.conf

    • MacOS: /usr/local/etc/redis.conf

  3. Start the Redis-server

Now confirm that Redis is running on port 6380:

redis-cli -p 6380

The following result should be received: PONG.

If all of the above steps have been successfully completed, your system is now ready for the installation of Lisk Core.


This section details how to install Lisk Core from Source code. When completed, a functioning node on the Lisk network will exist. If you wish to update your current Lisk Core installation, please see Update Source code.

Login as the Lisk user

This user was created in the Pre-Installation steps. If you are already logged in to this user, please skip the following step:

sudo -u lisk -i

Installing Lisk from Source code

git clone (1)
cd lisk-core                  (2)
git checkout v3.0.0-beta.1 -b v3.0.0-beta.1 (3)
npm ci                        (4)
npm run build                 (5)
1 Clone the repository.
2 Navigate into the lisk-core root folder.
3 Check out the latest release tag.
4 Install dependencies.
5 Compile packages.
Please check for the latest release in core releases.

To test that Lisk Core is built and configured correctly, execute the following command below to connect to the network:

node dist/index.js (1)
LISK_NETWORK=[network] node dist/index.js (2)
node dist/index.js --network [network] (3)
1 Default: connect to Devnet.
2 Use environment variables to overwrite config values, (recommended).
3 Use flags to overwrite config values.

Where [network] might be either devnet (default), betanet, testnet or mainnet.

It is recommended to overwrite the config values with environment variables if required. Useable variables will always start with the LISK_ prefix. Alternatively, the user may define a custom config.json, as described in Configuration of Lisk Core . Please see the list of available environment variables.

If the process is running correctly, no errors are thrown in the logs. By default, errors will be logged in logs/[network]/lisk.log. Once the process is verified as running correctly, press CTRL+C and start the process with pm2. This will fork the process into the background and automatically recover the process if it fails.

pm2 start --name lisk dist/index.js -- --network [network]

Where the [network] might be either devnet (default), betanet, testnet, or mainnet.

If you are not running Lisk locally, it is required to follow the API access guide document in order to enable access.

In case you wish to configure your node further, e.g. if enabling forging is required, then please see the configuration documentation.

Post-installation (optional)