Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NIP 11 - Symbol Configuration Utility CLI #35

Open
CrackTheCode016 opened this issue Feb 3, 2020 · 5 comments
Open

NIP 11 - Symbol Configuration Utility CLI #35

CrackTheCode016 opened this issue Feb 3, 2020 · 5 comments

Comments

@CrackTheCode016
Copy link

@CrackTheCode016 CrackTheCode016 commented Feb 3, 2020

NIP 11 - Symbol Configuration Utility (CLI)

Summary

    NIP: 11
    Layer: Application
    Title: Symbol Configuration Utility (CLI)
    Author: Bader Youssef <bader@iodlt.com>
    Discussions-To: #sig-client
    Comments-URI: ?
    Status: Draft
    Type: Process
    Created: 2020-02-03
    License: MIT

Introduction

The current configuration process of a Symbol blockchain leaves much to be desired. To configure a Symbol instance, there is either the option of using one of the many pre-configured Docker images, which does not work on all systems (ARM-based devices, older systems), or completely configuring from scratch.

A Symbol (peer) instance requires a series of steps that must be taken before it is able to be functional and launched:

  • Symbol dependencies must be downloaded, compiled, and installed. This process can be quite time-consuming.

  • A total of 19 config files must be properly configured for a new chain instance. For joining an existing chain, the proper config for that chain (e.g a testnet) must be downloaded and placed in the correct path.

  • Depending on the user's goals, they may wish to further configure their node's settings in config-node.properties, e.g a philanthropic node setup.

  • Load properly configured config-extension files based on node role: DUAL, API, or PEER.

  • For developers, switching and testing different network configurations is often part of the daily workflow.

There is currently no streamlined, easily installable tool to accomplish the above. An attempt was made with cat-config-scripts, but it does not offer a high level of functionality or portability.

This NIP solves this problem by offering a CLI utility that streamlines the above into an easy-to-use tool.

Feature Prioritization / Future Features

Certain features will be more prioritized than others.

The most notable issues as of this NIP are with the configuration of a node, node role switching, and loading other network configurations. These features are to be considered priority in this NIP. This repository here demonstrates some of this functionality.

Other features, such as the portable compilation / installation of Symbol and its dependencies and generating new network templates are more complex and will come at a later time. However, they will be considered for the future of the CLI, and if other contributors get involved.

Future feature ideas are welcome in the comments of this NIP.

Specification

Additional Configuration File

For more advanced configuration, an optional scu-config.json can be passed into the CLI as an argument. This file would contain user-related values:

  • Boot private key
  • Harvester key
  • Node name
  • Node max fee
  • An array of paths that lead to different network templates (registeredTemplates).
  • an "active" path, which points to the current network configuration that the user is using (selectedTemplate).

scu-config.json

{
  "friendlyName": "",
  "bootPrivateKey": "",
  "harvesterKey": "",
  "maxFee": 0,
  "selectedTemplate": "/usr/local/scu-cli/templates/tesnet",
  "registeredTemplates": [other paths...]
}

The user would have the option of editing this file themselves, or changing the values via the CLI.

Command Layout Outline

The following is a proposed command tree for the CLI. Each command should contain a parent command, along with required parameters.

Command Table

Subcommand Args Description
install* <path-to-new-config> Installs Symbol and its dependencies.
start none Starts a Symbol instance with the selected network template. This will most likely depend on the Symbol binaries being in the user's PATH.
add none Adds a new network template.
select <template-name> Selects a saved network template.
reset none Resets the selected node.
changerole <dual / peer / api> Changes the node role of the selected network template.
configure <config-parameter> Changes node-specific parameter in selected network template (e.g bootPrivateKey).

Example --help output:

$ scu-cli --help
Welcome to the Symbol Configuration Utility

USAGE: scu-cli <command>

SUBCOMMANDS:

install* - Installs Symbol and its dependencies.

start - Starts a Symbol instance with the selected network template. This will most likely depend on the Symbol binaries being in the user's PATH.

add <path-to-new-config> - Adds a new network template.

select <template-name> - Selects a saved network template.

reset - Resets the selected node.

changerole <dual | peer | api> - Changes the node role of the selected network template.

configure - Changes node-specific parameter in selected network template (e.g bootPrivateKey).

* Will most likely not be implemented in the first version(s) of the CLI.

Network Template Specification

The notion of network "templates" exists within cat-config-scripts. A user should be able to download the resources and nemesis for a specific network as a "template", and specify the path to this template in the configuration file, or via the CLI. A template should follow the following file structure:

example-network-template/
.
├── seed
├── data
└── resources

Where data/ contains the active directory for the node to store new chain information, seed/ contains original nemesis data in the case of a node reset, and resources contains network-specific files. Users will be able to download network configurations in this format, and load them via the CLI.

These files are required to start and join a Symbol instance.

Install Method

As the CLI will use Typescript / NodeJS, it will be published as an NPM package, and thus installation is the same as any NPM global module: npm i -g scu-cli.

Motivation

This NIP intends to help with the testing and development of Symbol. By providing a standard tool that enables developers to easily switch configurations, install dependencies, and provide a better Symbol devops and configuration experience.

Design Decisions

  • The form of a cross-platform, CLI application makes the most sense for chain configuration. GUI applications cannot always be used in remote server configuration, and bash scripts can be cumbersome.

  • The Symbol Configuration Utility will be written in Typescript and use the Command Design Pattern. This pattern suits CLI-style applications very well, as it allows for the command logic to be encapsulated for later use depending on the program's state.

  • It will be published as an NPM module to be installed globally on the user's machine. This will allow for easy installation.

  • It's possible that this implementation could be integrated into nem2-cli - see Alternatives

Implementation

N/A at the time of the initial draft. Once more feedback and community input is gathered, a Github repo will be hosted with the code. It's possible that this functionality will be added to nem2-cli.

Drawbacks

  • It may cause redundancy with the existing nem2-cli, and the efforts between this CLI and nem2-cli may be split. It may also be a minor inconvenience, as developers will have to download two different tools.

Alternatives

  • Integration of the above features could be integrated into the existing nem2-cli, which also happens to use the same software design pattern as proposed above.

    In this case, the functionality will implemented as part of a new subcommand: node.

    This approach may save time in development, as well as further existing tools in the ecosystem.

References

History

Date Version
Feb 3 2020 Initial Draft
@decentraliser

This comment has been minimized.

Copy link

@decentraliser decentraliser commented Feb 4, 2020

In terms of user experience, I think it is essential for node operators to be able to operate without having to modify files with a text editor.

I think that it would make sense to leverage nem2-cli.
There could be a node-settings command section that could be shown according to a variable stored in a .ENV file

@jontey

This comment has been minimized.

Copy link

@jontey jontey commented Feb 4, 2020

Build a set of ansible scripts, use runbook as gui to run said scripts. Just my half a cent

@CrackTheCode016

This comment has been minimized.

Copy link
Author

@CrackTheCode016 CrackTheCode016 commented Feb 5, 2020

Build a set of ansible scripts, use runbook as gui to run said scripts. Just my half a cent

That is actually a good idea for a GUI. This NIP is for a CLI, but in the future a solid GUI with the same principles will be nice to have as well, even though a CLI should be prioritized (imo).

Thanks for the input.

@dgarcia360

This comment has been minimized.

Copy link
Member

@dgarcia360 dgarcia360 commented Feb 10, 2020

Thanks @CrackTheCode016 for submitting this NIP!
Please, submit a new PR assigning the number 11 to this NIP.

Integration of the above features could be integrated into the existing nem2-cli, which also happens to use the same software design pattern as proposed above.

I'd prefer to integrate it in the same nem2-cli so that we have a single command-line tool.

To configure a Symbol instance, there is either the option of using one of the many pre-configured Docker images, which does not work on all systems (ARM-based devices, older systems) or completely configuring from scratch.

Right now we have also the problem that the current config scripts do not work with every operative system. Would it be possible to support Windows as well with this approach?

use runbook as gui to run said scripts

+1 While having a good looking GUI might be helpful, I would give it less priority since normally VPS and IoT devices normally interact through the command line.

@dgarcia360 dgarcia360 changed the title NIP ? - Symbol Configuration Utility CLI NIP 11 - Symbol Configuration Utility CLI Feb 10, 2020
@CrackTheCode016

This comment has been minimized.

Copy link
Author

@CrackTheCode016 CrackTheCode016 commented Feb 10, 2020

I'd prefer to integrate it in the same nem2-cli so that we have a single command-line tool.

I agree 👍 seems that this is the consensus on this specific.

Right now we have also the problem that the current config scripts do not work with every operative system. Would it be possible to support Windows as well with this approach?

Yes, having a portable solution across both Linux, macOS, and Windows is imperative for this NIP. There are a few useful NPM libraries that we can use to also provide Windows support for things like shell commands, i.e using git for installing dependencies. (see shelljs).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.