Lisk Core Docker Setup

Pre-install

This document will detail how to prepare a system 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.

Determine if your platform can run Docker.

Supported Platforms

  • MacOS

  • Windows

  • Linux

Please refer to https://docs.docker.com/docker-for-mac/install/. Please note that Docker for Mac already includes Docker Compose. Install make using XCode.

Please refer to https://docs.docker.com/docker-for-windows/install/. Please note that Docker for Windows includes Docker Compose.

To install Docker Compose, please refer to https://docs.docker.com/compose/install/

Configure Docker, so it can be run without sudo rights: https://docs.docker.com/install/linux/linux-postinstall/

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

sudo apt-get install curl make

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, to make your node’s API reachable. For more info, see the diagram on the Interact with network page.

To connect to the desired network with Lisk Core, please ensure that the corresponding ports are open:

Network HTTP WebSocket

Mainnet

8000

8001

Testnet

7000

7001

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, these 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 like so:

  • Ubuntu

  • MacOS

The lisk user itself does not need any sudo rights to run Lisk Core.

It is sufficient to create a group docker and add the newly created user to that group, to enable the user to use Docker (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 docker group
3 add the user to docker group

It is not essentially needed to set up a lisk user, especially when you are runnign a local instance for development pruposes.

If you still want to do it, we recommend to create the user using the macOS GUI: https://support.apple.com/en-gb/guide/mac-help/mtusr001/mac

Installation

Get configuration and Makefile

sudo -u lisk -i                                    (1)
git clone https://github.com/LiskHQ/lisk-core.git  (2)
cd lisk-core/docker                                (3)
1 switch to lisk user
2 clone the repository
3 navigate into docker directory

It contains a directory docker with the following files:

  • .env.development

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

Set environment variables

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

Before setting the variables, you may want 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:

cp .env.<network> .env

Where <network> stands for the Lisk network you want to connect to.

Coldstart application

Option 1: Makefile

We recommend using the Makefile. Makefile provides a convenient way to sync your node from snapshot:

make coldstart  (1)
1 will download and restore from a recent blockchain snapshot for you

If you want to synchronize your node starting form the genesis block, it might take a significant amount of time until your local node will be fully syncronized with the blockchain network. We recommend to use make coldstart in case you want/need your node ready to use quickly.

make (1)
1 will sync from genesis block on first startup

Option 2: docker-compose

docker-compose up -d (1)
docker-compose ps    (2)
docker-compose logs  (3)
1 initialize Lisk Core
2 see the status of Lisk Core
3 see logs

Verify

As final step, verify your node is connected and in sync with the network, e.g. by asking about your nodes’ status by using the API:

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 look like this:

{
  "meta": {},
  "data": {
    "broadhash": "ca930994bc1a6a92a47afb7310e3d9903f5e98ce56a6c5fdf444ba34f24c1543",
    "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 synced, the values of networkHeight and height should be (nearly) equal.

To fully verify that your node is in sync with the network, go to the Lisk Explorer(Mainnet) or Lisk Explorer(Testnet) and compare the Network height in the explorer with the height of your node. Again, they should be (nearly) equal.

If needed, use the different Explorer tools for further verification, like comparing the last forged blocks on the chain.

From this point, your node should be fully functional.

As next step, check out Docker Administration to learn how to manage your Node.

Post-installation (optional)

Ubuntu

You may want to set up a service for Lisk Core, that takes care of restarting it automatically after server restarts:

# /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: You still need to enable forging manually after a restart of Lisk Core.

To enable the service, run:

systemctl enable docker-compose-lisk

Check the service by running:

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