Docker image setup

Pre-install

This document covers how to prepare a system in order to run Lisk Core as a Docker-based container. To run Lisk in Docker a user must first install the Docker engine. Additionally, it is recommended to install Docker Compose for convenience.

Firstly, determine if your platform can run Docker as described below.

Supported platforms

Please refer to https://docs.docker.com/engine/installation

  • Ubuntu

  • MacOS

  • Windows

Please refer to docker installation for Ubuntu.

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

Configure Docker, so 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 in the following command below:

sudo apt-get install curl make

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

Please refer to Docker installation for Windows. Please note that Docker for Windows includes Docker Compose.

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 in order to ensure your node’s API is reachable. For more information, see the diagram on the Interact with network 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

Betanet

5000

5001

Devnet

4000

5000

These are the default ports for connecting with the network. They can be altered later in the config.json file.

These are the default ports for connecting with the network, and can be altered later in .env.

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.

It is sufficient to create a group docker, and then add the newly created user to that group. In order to enable the user to use Docker, please see: https://docs.docker.com/install/linux/linux-postinstall/.

 
sudo adduser lisk              (1)
sudo groupadd docker           (2)
sudo usermod -aG docker lisk   (3)
1 Create a new user.
2 Create a docker group.
3 Add the user to the docker group.

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 as shown here: https://support.apple.com/en-gb/guide/mac-help/mtusr001/mac

Installation

Get configuration and Makefile

Clone the Lisk Core repository as shown below:

sudo -u lisk -i                                    (1)
git clone https://github.com/LiskHQ/lisk-core.git  (2)
cd lisk-core/docker                                (3)
git checkout v3.0.0-beta.0                         (4)
1 Switch to the lisk user.
2 Clone the repository.
3 Navigate into the docker directory.
4 Checkout the 3.0.0-beta.0 branch, to install Lisk Core version 3.0.0.

This contains a directory docker with the following files:

  • .env.development

  • .env.betanet

  • .env.mainnet

  • .env.testnet

  • docker-compose.make.yml: used by make coldstart.

  • docker-compose.override.yml: use this file to overwrite LISK_ variables, (empty by default).

  • docker-compose.redis.yml: enable cache, (optional).

  • docker-compose.yml

  • Makefile

The .env-files are templates with network specific environment variables which are described below:

Set environment variables

To connect to the Lisk network, the environment variables need to be set accordingly.

Before setting the variables, you may wish to edit them in the respective .env.<network> file.

It is recommended to change the password for the database, which is stored in ENV_LISK_DB_PASSWORD.

To install a specific version of Lisk Core, set the ENV_LISK_VERSION to the respective version.

After adjusting them, copy the environment variables to a file called .env as shown below:

cp .env.<network> .env

Where <network> refers to the Lisk network that you wish to establish a connection to.

Coldstart application

Option 1: Makefile

It is recommended to use the Makefile. Makefile provides a convenient way to synchronize from a snapshot:

make coldstart  (1)
1 This will download and restore from a recent blockchain snapshot.

If you wish to synchronize your node starting from the genesis block, it may take a significant amount of time until your local node will be fully synchronized with the blockchain network. It is recommend to use make coldstart in case your node is required to be used without delay.

 
make (1)
1 This will synchronize from the genesis block on the first startup.

Option 2: docker-compose

docker-compose up -d (1)
docker-compose ps    (2)
docker-compose logs  (3)
1 Initialize Lisk Core.
2 Enables the status of Lisk Core to be viewed.
3 Enables the logs to be viewed.

Verify

The final step is to verify that your node is connected and is synchronized with the network. For example, by enquiring about your node’s status from using the API as shown below:

docker-compose exec lisk curl http://localhost:<PORT>/api/node/status --header "accept: application/json"

Where <PORT> is the network specific httpPort of your node.

The result should appear as shown below:

{
  "meta": {},
  "data": {
    "consensus": 94,
    "currentTime": 1558358294074,
    "secondsSinceEpoch": 94249094,
    "height": 8306047,
    "loaded": true,
    "networkHeight": 8306047,
    "syncing": false,
    "transactions": {
      "confirmed": 928836,
      "unconfirmed": 0,
      "unprocessed": 0,
      "unsigned": 0,
      "total": 928836
    }
  },
  "links": {}
}

When your node is synchronized, the values of networkHeight and height should be either equal or almost equal.

To fully verify that your node is synchronized with the network, go to the Lisk Explorer (Betanet) and compare the network height in the explorer with the height of your node. Again, they should be either equal or almost equal.

If necessary, use the different Explorer tools for further verification, such as comparing the last forged blocks on the chain.

From this point onwards your node should be fully functional.

To proceed to the next step, please see the Docker image management to learn how to manage your node.

Post-installation (optional)

Ubuntu

You may wish to set up a service for Lisk Core that enables an automatic restart after the server restarts. This can be performed as shown below:

# /etc/systemd/system/docker-compose-lisk.service

[Unit]
Description=Docker Compose Application Service
Requires=docker.service
After=docker.service

[Service]
WorkingDirectory=/home/lisk/lisk-core/docker/testnet/
ExecStart=/usr/local/bin/docker-compose up
TimeoutStartSec=0
Restart=on-failure
StartLimitIntervalSec=60
StartLimitBurst=3

[Install]
WantedBy=multi-user.target

For delegates: It will still be necessary to enable forging manually after a restart of Lisk Core.

To enable this service, execute the following command:

systemctl enable docker-compose-lisk

Check the service by executing the following commands:

systemctl status docker-compose-lisk.service (1)
sudo journalctl -u docker-compose-lisk.service (2)
1 Displays the status of the service.
2 Displays the logs of the service.