Installation with Docker

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

Pre-requisite

Lisk Service is a web application middleware that allows interaction with various blockchain networks based on the Lisk protocol. It is recommended to set up a blockchain node first, before setting up Lisk Service.

  • To set up a Lisk-Core node, see any of our setup guides, such as NPM setup.

  • Alternatively, you can setup up a sidechain node to connect to Lisk Service.

  • Please make sure to set system.keepEventsForHeights: -1 in the node config before synchronizing the node with the network.

1. Setting up Lisk Service

It is strongly recommended to synchronize your blockchain node with the network before starting the Lisk Service.

1.1. Prerequisites

1.1.1. Requirements

Supported Platforms

  • Ubuntu 20.04 (LTS) x86_64

  • Ubuntu 22.04 (LTS) x86_64

  • MacOS x86_64

Node.js

  • 18

The following system requirements are recommended:

Memory

  • Machines with a minimum of 8 GB RAM for the Mainnet.

  • Machines with a minimum of 8 GB RAM for the Testnet.

Storage

  • Machines with a minimum of 40 GB HDD.

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

1.1.2. Development tools

  • Ubuntu / Debian

  • MacOS

Install the build-essential package alongside 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.

Update current brew installation
brew update
Verify the brew installation
brew doctor

Xcode

Install Xcode essentials coming from Apple.

xcode-select --install

1.1.3. Docker & Docker compose

  • Ubuntu / Debian

  • MacOS

  1. Please refer to the 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.

1.1.4. Open necessary ports

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

  • The default API port for HTTP & WebSocket is: 9901

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

1.2. Installation of Lisk Service

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

git clone https://github.com/LiskHQ/lisk-service.git
cd lisk-service

Switch to the latest release branch.

git checkout v0.7.0

2. Build Lisk Service

To build Lisk Service from local files, first, navigate to the lisk-service repository on your system:

Working directory: 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 with aforementioned command: sudo make build

3. Connecting Lisk Service to a blockchain node

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

Working directory: lisk-service/
cp docker/example.env .env

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

Working directory: lisk-service/
vim .env
.env
# Lisk ecosystem configuration
LISK_APP_WS=ws://host.docker.internal:7887

The example.env assumes that the blockchain node e.g. Lisk Core node is running on the host machine, and not inside of a Docker container.

When running a blockchain node inside of a Docker container, the following variable needs to refer to the container. For this to work, the container running the blockchain node and the Lisk Service Blockchain Connector container must share the same docker network:

.env
# Lisk ecosystem configuration
LISK_APP_WS="ws://<your_docker_container>:7887"
For a complete list of supported environment variables check the Lisk Service Configuration Reference.

4. Starting Lisk Service

Run the following command to start Lisk Service:

Working directory: lisk-service/
make up

5. Stopping Lisk Service

You can stop Lisk Service again with the following command:

Working directory: lisk-service/
make down

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