Docker setup

This document describes how to run Lisk Core as a Docker image-based container. Lisk Core version 4 does not have any external dependencies and hence does not require using docker-compose.

Pre-installation

Hardware requirements

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[1].

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

The above command will 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.

Open ports

Please ensure, that the necessary ports are open to run Lisk Core as intended.

For example, in case ufw is used on Ubuntu to manage the firewall settings, the respective ports can be opened as follows:

7667 and 7887 are the default ports. If you configured custom ports in the node config file, adjust the examples to these specific ports.
Node P2P communication
ufw allow 7667
Node API
ufw allow 7887

Install Docker

To run Lisk Core in Docker, firstly it is necessary to install the Docker engine. Determine if your platform can run Docker as described below.

Please refer to the Docker installation page.

  • Ubuntu

  • MacOS

  • Windows

Please refer to the Docker installation for ubuntu.

Configure Docker, in order that it can be run without sudo rights: linux post install.

Install make using your package manager. For example, use apt-get if running Ubuntu as shown below:

sudo apt-get install curl make

Please refer to Docker installation for Mac. Install make using XCode.

Lisk Core download

The following commands below describe how to clone the repository, then how to navigate into the lisk-core root folder, and how to check out the latest release tag.

Clone the repository
git clone https://github.com/LiskHQ/lisk-core.git
Navigate into the "lisk-core" root folder
cd lisk-core
Check out the latest release tag
git checkout v4.0.0
Build the docker image
make build-image
Please check for the latest release in the Lisk Core releases list.

Run

Podman

It is also possible to use podman instead of docker by simply replacing the occurrences of docker with podman, in the following examples or alternatively by creating an alias with alias docker=podman.

Create a "lisk-core" container:

  • Mainnet

  • Testnet

  • Devnet

docker run --volume lisk-data:/home/lisk/.lisk \
           --publish 7887:7887 \
           --name lisk-core \
           lisk/core:4.0.0 \
           start --network=mainnet

The default log levels for Mainnet are:

"logger": {
    "fileLogLevel": "error",
    "LogLevel": "none"
},

So if you start the node, it won’t show any logs in the console. This is the recommended setting for reducing the number of logs for a running node. However, to verify that the node started correctly, update the log levels in the config to info or lower.

Alternatively, start the node with the following flag:

start --network mainnet --console-log=info
docker run --volume lisk-data:/home/lisk/.lisk \
           --publish 7887:7887 \
           --name lisk-core \
           lisk/core:4.0.0 \
           start --network=testnet
docker run --volume lisk-data:/home/lisk/.lisk \
           --publish 7887:7887 \
           --name lisk-core \
           lisk/core:4.0.0 \
           start --network=devnet
The passphrase for the genesis account(s) can be found here in the Lisk Core GitHub repository under the following path: config/devnet/passphrase.json.

Configuration

Further parameters can be passed after --network, for example, as shown below:

docker run --volume lisk-data:/home/lisk/.lisk \
           --publish 7667:7667 \
           --publish 127.0.0.1:7887:7887 \
           --name lisk-core \
           lisk/core:4.0.0 \
           start --network=testnet --api-ws --api-http --log=debug

Environment variables can be set with --env:

docker run --volume lisk-data:/home/lisk/.lisk \
           --publish 7667:7667 \
           --env LISK_CONSOLE_LOG_LEVEL=debug \
           --name lisk-core \
           lisk/core:4.0.0 \
           start --network=mainnet

Import blockchain snapshot

docker run --volume lisk-data:/home/lisk/.lisk -it --rm lisk/core:4.0.0 blockchain download --network=betanet --output=/home/lisk/.lisk/tmp/
docker run --volume lisk-data:/home/lisk/.lisk -it --rm lisk/core:4.0.0 blockchain import /home/lisk/.lisk/tmp/blockchain.db.tar.gz
docker run --volume lisk-data:/home/lisk/.lisk -it --rm --entrypoint rm lisk/core:4.0.0 -f /home/lisk/.lisk/tmp/blockchain.db.tar.gz
docker start lisk-core
docker logs -f lisk-core

1. These recommendations are derived from the log level settings, in the event that the user needs to increase storage to prevent limited memory access and potential memory-related problems with a node. Furthermore, as more transactions are processed and added to the blockchain, the size of the blockchain increases over time and this directly affects the HDD storage requirements for a blockchain node. Hence, adhering to the above listed requirements is highly recommended.