Installation with Docker

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

Pre-requisite

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

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

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

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

1. Setting up Klayr 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 16 GB RAM for the Mainnet.

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

Storage

  • Machines with a minimum of 40 GB HDD.

The following dependencies are required to install and run Klayr 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 Klayr 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 Klayr Service

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

git clone https://github.com/KlayrHQ/klayr-service.git
cd klayr-service

Switch to the latest release branch.

git checkout v0.7.8

2. Build Klayr Service

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

Working directory: klayr-service/
make build-images

Klayr 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-images

3. Connecting Klayr Service to a blockchain node

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

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

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

Working directory: klayr-service/
vim .env
.env
# Klayr ecosystem configuration
KLAYR_APP_WS=ws://host.docker.internal:7887

The example.env assumes that the blockchain node e.g. Klayr 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 Klayr Service Blockchain Connector container must share the same docker network:

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

4. Starting Klayr Service

Run the following command to start Klayr Service:

Working directory: klayr-service/
make up

5. Stopping Klayr Service

You can stop Klayr Service again with the following command:

Working directory: klayr-service/
make down

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