Source code setup
This is designed for anyone wishing to develop on the Lisk Core codebase.
It also comes with an extensive test-suite which is described in the following README.md
.
An installation performed from source code enables a developer to work on the latest codebase for Lisk Core, which may not have been tagged for a release yet.
Pre-install
To complete the installation it is necessary to fulfill some prerequisites. If you have already performed these, please proceed to the Installation chapter.
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 make your node’s API reachable. For more information, see the diagram on the Interact with the API page. |
To connect to the desired network with Lisk Core, please ensure that the corresponding ports listed below are open:
Network | HTTP | WebSocket |
---|---|---|
Mainnet |
8000 |
8001 |
Testnet |
7000 |
7001 |
Devnet |
4000 |
5000 |
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:
The |
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: https://support.apple.com/en-gb/guide/mac-help/mtusr001/mac
Git
Git is used for cloning and updating Lisk.
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. |
See instructions for MacOS 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 already installed PostgresSQL versions. |
After installation, it should be possible to see the PostgresSQL database cluster by executing the following command:
pg_lsclusters
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 as shown below:
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.
Change password to a secure password of your choice.
Do not forget to update this password in the Lisk Core configuration later on.
|
MacOS
Install PostgresSQL version 10 by executing the following command below:
brew install postgresql@10
Execute the following to have PostgreSQL commands, (e.g. psql
) in your PATH as shown below:
echo 'export PATH="/usr/local/opt/postgresql@10/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
Start PostgreSQL, create the lisk
user and the database by executing the following commands:
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.
Change password to a secure password of your choice.
Do not forget to update this password in the Lisk Core configuration later on.
|
Running PostgresSQL inside a Docker container will setup the correct version of PostgresSQL, and containerize it away from any existing versions you may have 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 perform the command below successfully, install Docker as described in the Lisk Core Docker image set up.
If you have other versions of PostgreSQL installed on your machine, 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
The command above will install PostgreSQL version 10 (postgres:10
) in a container with the name lisk_core_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_<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, execute the following commands 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 case it is required to access PostgresSQL inside the container via the CLI, execute the following command below:
docker exec --tty --interactive lisk_core_db psql -h localhost -U lisk -d postgres
Node.js
Node.js serves as the underlying engine for code execution. There are several different methods and version managers to install Node.js on your system. It is recommended to utilise one of the following two options shown below:
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.
-
Install NVM by following these official instructions.
-
Install the correct version of Node.js using NVM by executing the following command below:
nvm install 10.15.3
If it is not required to use NVM or other package managers, it is possible to install the node package globally on your system as shown below:
Ubuntu
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt-get install -y nodejs
MacOS
brew install node@10.15.3
PM2 (optional)
Install PM2 for managing the start and stop of the application process in the background by executing the following command:
npm install pm2 -g
Redis (optional)
sudo apt install redis-server
Start Redis:
sudo service redis-server start
Stop Redis:
sudo service redis-server stop
brew install redis
Start Redis:
brew services start redis
Stop Redis:
brew services stop redis
Lisk does not run on the Redis default port of |
In the next installation phase, 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:
-
Stop the Redis-server
-
Edit the file
redis.conf
and change:port 6379
toport 6380
-
Ubuntu/Debian:
/etc/redis/redis.conf
-
MacOS:
/usr/local/etc/redis.conf
-
-
Start the Redis-server
Now confirm that Redis is running on port 6380
:
redis-cli -p 6380
ping
The following result should now be visible: PONG
.
If all of the above steps have been successfully completed, then your system is ready for the installation of Lisk Core.
Installation
This section covers how to install Lisk Core from Source code. When completed, you will have a functioning node on the Lisk Network. If it is required to upgrade 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 this following step:
sudo -u lisk -i
Installing Lisk from Source code
git clone https://github.com/LiskHQ/lisk-core.git (1)
cd lisk-core (2)
git checkout v2.1.7 -b v2.1.7 (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 commands 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), alphanet
, betanet
, testnet
or mainnet
.
It is recommended to overwrite the config values with environment variables if necessary.
Useable variables will always start with LISK_
prefix.
Alternatively, the user may define a custom config.json
, as described in Configuration of Lisk Core .
You can view a list of available environment variables here.
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 [network]
might be either devnet
(default), alphanet
, betanet
, testnet
or mainnet
.
If you are not running Lisk locally, you will need to follow the API access guide 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)
-
Recommended: Set up a logrotation