Docker image setup
Docker image adds support for additional platforms upon which to run a Lisk node. For example, running a Lisk node inside of a Docker image on Windows and connecting it via a custom node on Lisk Desktop to Lisk Core, without the necessity to rent an additional server.
Pre-install
This document covers how to prepare a system to run Lisk Core as a Docker image-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
Please refer to Docker installation for ubuntu
To install Docker Compose, please refer to the Docker Compose installation guide.
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.
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, to make your node’s API reachable. For more information, see the diagram on the Interact with the API 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 |
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, they 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:
The It is sufficient to create a group |
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 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: 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 master (4)
1 | Switch to Lisk user. |
2 | Clone the repository. |
3 | Navigate into the docker directory. |
4 | Checkout the master branch for the last stable version of Lisk Core. |
This contains a directory docker
with the following files:
-
.env.development
-
.env.mainnet
-
.env.testnet
-
docker-compose.make.yml
: used bymake coldstart
. -
docker-compose.override.yml
: use this file to overwriteLISK_
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>
stands for the Lisk network you want to connect 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 might take a significant amount of time until your local node will be fully synchronized with the blockchain network.
It is recommended to use |
make (1)
1 | This will synchronise from the genesis block on first startup. |
Verify
The final step is now to verify that your node is connected, and is synchronized with the network, e.g. inquiring 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": {
"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 synchronized, the values of networkHeight
and height
should be (nearly) equal.
To fully verify that your node is synchronized 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 necessary, use the different explorer tools for further verification, such as comparing the last forged blocks on the chain.
From this point your node should now be fully functional.
To proceed to the next step, please see Docker image management to learn how to manage your node.
Post-installation (optional)
Ubuntu
If it is required to set up a service for Lisk Core that takes care of restarting it automatically after the server restarts, this can be accomplished by creating /etc/systemd/system/docker-compose-lisk.service
file with contents:
# /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/ ExecStart=/usr/local/bin/docker-compose up TimeoutStartSec=0 Restart=on-failure StartLimitIntervalSec=60 StartLimitBurst=3 [Install] WantedBy=multi-user.target
Where WorkingDirectory
is a path to Lisk Core. If you run Lisk Core under lisk
user, add a line User=lisk
to [Service]
section. You may also wish to modify ExecStart
command.
For delegates: It is still required to enable forging manually after a restart of Lisk Core. |
To enable the service, execute the following command below:
systemctl enable docker-compose-lisk
Note: this command doesn’t start Lisk Core right now, but will enable autostart on reboot.
To check the service, execute the following command below:
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. |
Note: these commands work only if Lisk Core is started as a service.