Installation with Docker

How to set up Lisk Service and connect it to a local Lisk Core node.

1. Setting up Lisk Core

Lisk Service is installed in addition to a Lisk blockchain application such as Lisk Core, in order to provide enriched network data for third-party services.

The first step is therefore to install Lisk Core.

It is recommended to use NPM to conveniently install Lisk Core through the command line:

npm install --global --production lisk-core

Check out the Lisk Core NPM setup guide for more information on how to install Lisk Core on your machine.

2. Configuring Lisk Core

Use the Lisk Core CLI to start Lisk Core with the desired configurations.

The --network flag defines which blockchain network Lisk Core will connect to.

--api-ws enables the WebSocket API of the node.

--api-ws-port allows the user to define the port for the WebSocket connection.

lisk-core start --network testnet --api-ws --api-ws-port=8080 --overwrite-config

To connect to a different network, replace testnet with either mainnet or devnet.

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

If you followed the Binary setup of Lisk Core, it is also necessary to add the following option to the config.json file:

"rpc": {
    "enable": true,
    "mode": "ws",
    "port": 8080,
    "host": "0.0.0.0" (1)
},
1 Add this line to the rpc option in the config.json file.

3. Setting up Lisk Service

3.1. Prerequisites

The following dependencies are required to install and run Lisk Service with Docker.

3.1.1. Development tools

  • Ubuntu / Debian

  • MacOS

Install the build-essential package alongside with several development tools.

For example, use apt if running Ubuntu as shown in the following command below:

apt install build-essential git

Brew

Install Brew by following the most recent instruction.

If you already have Brew installed, ensure it is working and is the latest version.

brew update
brew doctor

Xcode

Install Xcode essentials coming from Apple.

xcode-select --install

3.1.2. Docker & Docker compose

  • Ubuntu / Debian

  • MacOS

To install Docker Compose, please refer to install docker compose.

To configure Docker so it can be run without sudo rights, follow: linux post install.

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

3.1.3. Open necessary ports

Ensure the port which allows external services communication with the Lisk Service APIs is open.

  • 9901: Default API port (HTTP & WebSocket)

Example: Opening the port 9001 with ufw on Ubuntu
sudo ufw allow 9901

3.2. Installation of Lisk Service

Clone the lisk-service GitHub repository and then navigate into the project folder.

In the directory where you want to store Lisk Service
git clone https://github.com/LiskHQ/lisk-service.git
cd lisk-service
git checkout v0.4.5

4. Build Lisk Service

Build Lisk Service from local files:

/lisk-service/
make build

Lisk Service is now ready to use on your machine.

5. Connecting Lisk Service to Lisk Core

To connect Lisk Service to a local Lisk Core node, set the environment variable LISK_CORE_WS before starting Lisk Service as shown below:

Inside of the lisk-service root folder
export LISK_CORE_WS=ws://host.docker.internal:8080 (1)
make up (2)
1 LISK_CORE_WS: Path to the Lisk Core WS port.
2 Command to start Lisk Service.

Export environment variables to override the default config options which are located under docker/network/core3-default.env.

For a complete list of supported environment variables check the Lisk Service Configuration Reference.

Alternatively, it is possible to define a file with all the desired environment variables and use it to start Lisk Service as shown below:

/lisk-service/
cd docker/network
vim my-env.env

Define key-value pairs of all desired environment variables, for example:

Press i to enter the insert mode in vim.
/lisk-service/docker/network/my.env
LISK_CORE_WS=ws://host.docker.internal:8080
Save and quit vim again by first leaving the insert mode with Esc and then by typing :wq and Enter.

Now start Lisk Service with the following command:

/lisk-service/
make up-custom-my

This will start Lisk Service with all the environment variables previously defined in my-env.env.

6. Stopping Lisk Service

You can stop Lisk Service again with the following command:

make down

More commands about how to manage Lisk Service are described on the Docker commands page.

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