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

Update the RPC configuration to enable the WebSocket API of Lisk Core. To accomplish this, create a custom configuration file, for example by copying one of the default config files:

/home/lisk/lisk-core/
cp config/mainnet/config.json custom-config.json

Add the following option to custom-config.json:

custom-config.json
{
    // ...
    "rpc": {
        "enable": true,
        "mode": "ws",
        "port": 8080,
        "host": "0.0.0.0" (1)
    },
    // ...
}
1 Allows remote servers to connect to the Lisk Core WS API. If this option is not set, it defaults to 127.0.0.1.

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

The --network flag determines the blockchain network Lisk Core connects to.

--api-ws enables the WebSocket API of the node, if not already enabled in the config.json file.

lisk-core start --network mainnet --api-ws --config=/home/lisk/lisk-core/custom-config.json --overwrite-config

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

3. Setting up Lisk Service

It is strongly recommended to synchronize your Lisk Core node with the network before starting the 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

  1. Please refer to docker installation for ubuntu.

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

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

  1. Please refer to Docker installation for Mac. Please note that Docker for Mac already includes Docker Compose.

  2. 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.5.0

4. Build Lisk Service

Build Lisk Service from local files:

/lisk-service/
make build

Lisk Service is now ready to use on your machine.

If you skipped the step to configure Docker to run without sudo rights, you need to prepend sudo: sudo make build

5. Connecting Lisk Service to Lisk Core

Before running the application copy the default docker-compose environment file:

cp docker/example.env .env

In the next step, open .env and set the required environment variables.

vim .env
.env
# Lisk ecosystem configuration
export LISK_CORE_WS="ws://host.docker.internal:8080" (1)
1 The example assumes that the Lisk Core node is running on the host machine, and not inside of a Docker container. When running Lisk Core inside of a Docker container, the variable needs to refer to the container: LISK_CORE_WS="ws://<your_docker_container>:8080".
For a complete list of supported environment variables check the Lisk Service Configuration Reference.

6. Starting Lisk Service

Run the following command to start Lisk Service:

make up

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