Objective: KIRA Network deployment software compatibility between different host operating systems, architectures and environments
Prerequisites:
- Minimum 32GB of the free storage space
- Disposable cloud instance, or VM
- Minimum 3GB of RAM
- Ubuntu 20.04 LTS installed on the host instance or VM
- Stable internet connection with at least 10 Mbps download speed
Source code:
Warning: Do not use your primary operating system to test any software releases as they can cause irreversible data loss. While using a personal computer and not a dedicated instance a virtualization software should be used such as VMWare. When using cloud instances along SSH ensure that you will not get locked out when firewall rules change, see list of exposed ports later in the document. While running tests in a home environment it is recommended that a VPN is used as certain firewall rules might prevent access to github and other dependencies hosted online.
Overview
Milestone one will be used to test “Demo Mode” of the network operations in which a local validator node will be deployed on the host machine using a deployment management system called KIRA Manager. Goal of this particular testnet exercise is to ensure stable operation of deployment software across different computer architectures, configurations and NOT functionality of the blockchain application.
KIRA Manager uses Docker to isolate and manage multiple parts of the infrastructure such as docker registry, validator nodes, sentries, private sentries, frontend, KIRA INTERX™ (interchain-nginx) service as well as backup service, recovery service and all other parts of the software stack.
Software Stack (Demo Mode)
Validator
Validator node is a software which produces “blocks” containing transactions, signed and submitted by the users (client software). Validator node is a type of “full node” which executes the blockchain state machine and allows the decentralized ledger to achieve consensus on what the state of that ledger should be. Each block must be signed by minimum ⅔ of all validators for it to be included to the blockchain. In the demo mode there will be just one validator node (running locally on your machine) and new blocks will be produced every few seconds regardless if new transactions are present or not.
Sentry
Sentry node is a type of “full node” which preserves, shares and synchronises the state of the decentralized ledger with other full nodes in the network. Sentry node’s purpose is to propagate blocks, signed transactions and enable query of the blockchain state by the client applications while at the same time protecting validator nodes from potentially malicious queries which might cause software to halt, restart or otherwise fail. If the sentry node fails, the validator node running behind it will remain operational as invalid blocks or malicious messages will never be propagated. In the Demo Mode there will be just a single sentry node while in the later stages a private sentry node will be introduced allowing validators to stay connected in the private network regardless what happens on the publicly exposed node.
INTERX
KIRA Interchain Nginx is a software which acts as an API sitting between the blockchain and frontend applications. INTERX not only enables the frontend to easily query the blockchain state but also secures the connection regardless of the communication protocol used (HTTP/HTTPS) as all responses to queries are signed. This solution was used so that the frontend applications do not have to manage light-clients of hundreds of individual parachains while giving users the ability to fully verify and easily audit the integrity of the “static” website they use to interact with the blockchain. One of the INTERX features is also support of the faucet from where users can claim free test tokens. Additionally INTERX caches all responses which greatly decreases resources utilization and number of queries to sentries via RPC as the same request can be shared with thousands of clients without a need to repeat the full-node query.
Interchain nginx is extremely useful in the context of interacting with hundreds of decentralized networks (especially heterogeneous parallel chains). Otherwise frontend application would have to support multiple different light clients making the development process and long term support extremely difficult while slowing down the user experience and potentially decreasing security by making it more difficult to audit or otherwise verify integrity of the frontend application.
Frontend
Frontend container is only available in the Demo Mode and will not be utilized in the milestone one. KIRA Frontend application is a static page enabling ease of interaction with the blockchain application through publicly available INTERX nodes. In the production environment frontend will be statically hosted via github pages, available as a mobile app or can be run locally, this means users can verify hash of the application they use to interact with the blockchain without fear of malicious code or potential DNS hijacking. Presence of the frontend container in the infra Demo Mode serves a purpose of making it easy to test latest software releases and is not intended for use in production.
Registry
Docker registry container is used to host all docker images locally which speeds up the build process. Every part of the infrastructure is built on your own machine which might take quite some time, however helps to preserve integrity of the code and decreases bandwidth utilization.
Network Layout (Demo Mode)
Docker networking facilitates connectivity between all parts of the KIRA software stack within dedicated subnets. The firewalld is used to protect the host machine from unauthorised access to deployed containers. All firewall rules are applied to a single configurable network interface. For this reason it is recommended that you should not attach more than one internet-connected network interface to your machine. In the Demo Mode following ports are exposed by default:
- 22 — SSH, allows for remote communication with the host
- 80 — HTTP, access to the KIRA Frontend (only in demo mode)
- 9090 — GRPC, access to the public sentry (only in demo mode)
- 26656 — P2P, allows public sentry to propagate blocks
- 26657 — RPC, allows blockchain query (only in demo mode)
- 11000 — INTERX API, allows for the state query, caching & file hosting
In the Demo Mode docker networks are isolated into 3 individual subnets
- regnet — dedicated to the local docker registry
- kiranet — accessible by validator and sentry
- servicenet — accessible by all public facing containers
All containers have a dynamic IP associated with the local DNS, all DNS names follow the pattern <container-name>.<subnet-name>.local for example ”validator.kiranet.local”, making it easy to test and communicate from within the host.
Note: Containers (Software stack running within virtualized OS) can only communicate with other containers if they are part of the same network. This solution greatly improves security of the validator node which can’t be influenced (accessed) by unrelated software stacks.
kira
KIRA Manager (kira) is a console tool enabling management and deployment of the whole software stack. In the milestone one, we will be testing a “Demo Mode” operation of that tool. The only supported operating system is Ubuntu 20.04 LTS and it has to be fully installed and updated before setup is attempted.
Setup
When setting up a kira tool for the first time you should SSH or otherwise access your host machine, open the console/terminal as sudo user (sudo -s) and execute the following instructions by copy-pasting it into your terminal. It is recommended that you should use an SSH terminal supporting colours such as termius otherwise the user interface might be distorted or entirely unusable.
sudo -scd /tmp && rm -fv ./i.sh && wget https://raw.githubusercontent.com/KiraCore/kira/master/workstation/init.sh -O ./i.sh && chmod 555 -v ./i.sh && H=$(sha256sum ./i.sh | awk '{ print $1 }') && read -p "Is '$H' a [V]alid SHA256 ?: "$'\n' -n 1 V && [ "${V,,}" == "v" ] && ./i.sh master || echo "Hash was NOT approved by the user"
Instruction above will first navigate your console to the tmp directory, download infrastructure initialization script, read a checksum of the file and display Accept/Deny prompt before executing it. Checking of the sha256 hash is used to ensure integrity of the downloaded initialization file. Although it is not necessary during testnet, in production you should always verify if the hash of downloaded file matches hash provided by the trusted source before attempting to execute the script.
If execution of the initialization script was successful you will see installation process taking place (essential dependencies), followed by TERMS & CONDITIONS communicate.
After continuing, you will be presented with a “Demo Mode” available as a single deployment option. (In the future milestones modes such as “Validator Mode” and “Sentry Mode” will be available).
Select option [1] to proceed then Quick Setup [1] again in the following submenu. The advanced setup [2] can be used to change github branches from which code of the software stack is downloaded as well as default internet facing network interface against which all firewall rules are applied.
Depending on your internet connection the very first setup might take between 45 minutes and multiple hours. It is possible that due to insufficient network connection speed the process might fail. In such a case you can start again proceeding with the step 1 of the setup instructions. Every time setup is executed it should be faster as dependencies are installed only once and their changes tracked.
If the final result is a “FINISHED: LAUNCH SCRIPT” notification followed by exit code 0, then the execution was successful and after clicking continue the KIRA Manager tool will appear (it might take a couple of seconds to load). If you accidentally close the window you will always be able to access the manager by simply typing “kira” in the window of your console or terminal.
KIRA Network Manager
The first section the Network Manger (kira ) home screen provides information such as resource utilization, network name, current blockchain height, local IP address, public IP address, name of the default network adapter (eth0 in our example) and status. If the network is healthy the status is green, if the network fails any of the health checks the status will turn red.
Second section presents a list of deployed containers, their names, status and health. Selecting a numeric opton [0], [1] … [n] will automatically open KIRA Container Manager, allowing for managing, inspecting and previewing detailed information in regards to individual containers.
Third section allows for interacting with ALL containers at once, that is stopping them, staring, pausing (freezing) and re-starting. If by any chance any parts of your infrastructure failed it is recommended to use [R]estart option as it will also re-initialize networking.
Final section of the kira manager allows to save all logs and configurations into a single ZIP file which can be used for the purpose of debugging. You should never share those logs with untrusted parties as they can contain sensitive information about your machine such as configuration files, IP addresses and potentially passwords and other secrets. Option [I] has the same effect as executing the setup command and makes it simpler to rebuild your entire setup if something goes wrong and you manage to irreversibly break the infrastructure.
KIRA Container Manager
Container manager is a tool which appears after selecting a numeric option [0], [1] … [n] within the KIRA Network Manager tool its purpose is to provide detailed information in regards to individual containers.
First section provides information such as container name including prefix and suffix of the container ID, repository (optional) and branch relevant to the software stack deployed within the container, port map which details how internal ports are mapped to the external ports (accessible from the host) and IP addresses of the container in each of the subnet they belongs to.
Second section provides detailed status such as host name, state of the container and the health information.
Final section enables control of the individual containers, that is restart, start, stop, dumping all logs and inspecting the virtualized operating system. In the case where the node fails, [L]ogs option enables previewing docker logs without need to enter (inspect) the virtual operating system within the container and making it very easy to report the potential issues.
Inspecting containers can be treated as accessing a virtualized operating system, that is entering the OS from within the OS (inception). By selecting that option you will find yourself within a virtualized ubuntu shell that allows access to the file system and all applications installed within that isolated OS.
Milestone Challenges
We are presenting here a list of potential test cases which can be performed by the Selected Phase 0 Participants and their successful or unsuccessful execution reported to the pinned form in the KIRA Testers Private group. Completing any of the test case suggestions is optional for all participants. The scope of your report can widely differ from any of the mentioned test cases as long as it is valuable and insightful in the context of improving the software and the future user experience.
There are no limitations in terms of how many reports you can submit however their content must be sufficiently detailed. All your findings have to be submitted to the report submission form before the 8’th January 2020 and no other channels of communication will be taken into account. Helping other testnet participants in solving their issues is allowed however will not result in higher scores.
Test Case Suggestions
- Install kira manger and deploy infrastructure in the Demo Mode
- Test all available options in the Network and Container manager
- Attempt to cause total or partial infrastructure failure while interacting with the machine remotely (from outside of the host)
- Test maximum duration of the infrastructure operation without failure
- Provide insight and suggestions in regards to user experience and how it can be improved
- Provide insight and suggestions in regards to improving security
- Provide insight and suggestions (or create a tutorial) how to deploy KIRA Infrastructure on your unique (unusual or low power) hardware setup such as Raspberry PI 4 (including all prerequisites such as memory flashing, upgrading etc..)
- Create PR to the kira github repository which improves performance, user experience, console interface, security or other aspects of the infrastructure operation
Foreword
We want to thank everyone for supporting KIRA and wish everyone Happy New Years 2021! We aim to continue delivering exciting developments and hope to bring even more decentralized joy in the coming months : )
…
Website: https://kira.network
Telegram: https://tg.kira.network
Twitter: https://twitter.kira.network
Support: https://support.kira.network
Medium: https://medium.kira.network
