技術
By うにやさん, 27 9月, 2020

Symbol bootstrap が公開されたのでテストネット構築

https://github.com/nemtech/symbol-bootstrap

symbol-bootstrap

シンボルのコマンドラインインターフェイスツール ( Symbol CLI tool ) で、既存のシンボルネットワークと同期する、完全なネットワークやノードを作成、設定、稼働させることができます。 

なぜこのツール?

このツールはシンボルの NEM2 Improvement Proposal ( NIP11）に対処するために作られました。理想は以下を置き換えることです。

主な利点:

  • インストール可能なコマンドラインインターフェイスツールです。クローンしたりコンパイルする必要のあるリポジトリではありません。
  • 設定ファイルを変更する代わりに、設定はコマンドラインインターフェイスのコマンドやプリセットでパラメタイズされます。
  • ツールのコードはネットワーク上の、ネットワークタイプ、新しいネットワーク、ノード毎にユニークです。異なるプロジェクトやアッセンブリーにコピーアンドペーストする必要はありません。
  • 設定コマンドはホストマシーンで動きます。docker経由ではなく、デバグやチューンしやすくなります。
  • catqapult-tools （ nemgen はまだネメシスブロックを生成するのに使われています ）ではなく。 鍵生成、vrf トランザクション、アドレス生成に、TS SDK を使います。
  • 設定ファイルは全てのノード、アッセンブリーやネットワークタイプに対し再利用でき、メンテナンスしやすくなります。
  • ネットワークセットアップ（データベース、ノード、restゲートウェイをいくつ稼働させるか）はプリセットで定義されています。ユーザーは自身のセットアップを提供できます。
  • Docker-compose.yaml ファイルは手動で 生成・アップグレードする代わりに、ネットワークセットアップ・プリセットに基づき生成されます。
  • 生成されたネットワーク ( config, nemesis と docker-compose ) は 別のホストマシーンで動くzipにして配布できます。
  • 使用されたdockerイメージバージョンは configuratin/preset 経由で変更できます。
  • oclif フレームを利用しています。新しいコマンドやドキュメントは簡単に追加。
  • クライアントの e2e テストのために npm 依存として含めることができます。

コンセプト

プリセット：

Yaml ファイルは設定やネットワークやノードのレイアウトを定義。ノード、データベース、rest ゲートウェイ、modes、keys などをいくつにするか決めます。

プリセットは生成からspecificの4レベルで定義されます。

  • Shared：全ネットワークのデフォルト設定。
  • Network：ネットワークのメインプリセットを定義します。例： bootstrap や testnet
  • Assembly：ネットワークの変更を定義します。例：testnet peer, testnet dual testnet api。Assembly はいくつかのネットワーク（testnet のような）には必要です。
  • Custom：ユーザーが作ったymlファイル（ --customPrest param ）はアウトオブボックスプリセットのいくつかもしくは全てを上書きできます。

それぞれのファイルの設定値は以前の値を上書きします( オブジェクトディープマージによって)。

Out-of-the-box presets:

  • -p bootstrap：デフォルトプリセット。mongoDB 1つ、peer 1つ、api 1つと rest geteway1つのフルネットワーク。Nemesisiブロック生成済み。
  • -p light；ライトネットワーク。mongoDB 1つ、dual peer 1つ、rest geteway1つのブートストラップのバージョンのひとつ。早く軽量なe2e自動テストに適しています。Nemesisブロック生成済み。
  • -p testnet -a peer：現在のパブリックテストネットに接続する一つのハーベスティングピアノード。Nemesisブロックは上書きコピー。
  • -p testnet -a api：現在のパブリックテストネットに接続する一つのapiピアノード。mongoDBとrest gatewayは独自で稼働。Nemesisブロックは上書きコピー。
  • -p testnet -a dual：現在のパブリックテストネットに接続する一つのdualハーベスティングピアノード。mongoDBとrest gatewayは独自で稼働。Nemesisブロックは上書きコピー。

カスタムプリセット：

コードを修正することなく、ネットワークを調整出来る方法です。  yml ファイル ( --customPrest param ) で、out-of-the-box プリセットのいくつかもしくは全ての設定値を上書きできます。

大部分の人は out-of-box プリセットを使うか、少しの属性を調整するでしょう。

ファイルは階層的yamlオブジェクトです。もし、ある値がルートレベルで定義されていると、全ての影響する設定に対するデフォルト値を上書きします。属性は一つのコンポーネント（node, gateway, nemesis など）だけに影響する下層レベルオブジェクトでも定義できます。

あなたの設定が有効かどうか判断する最良の方法は、ターゲットフォルダに生成された設定とprest.ymlファイルを検査することです。

例:

イメージとストットリングをカスタム：

symbolRestImage: symbolplatform/symbol-rest:1.3.1-alpha
throttlingBurst: 35
throttlingRate: 1000

アカウントの数をカスタム：

nemesis:
  mosaics:
    - accounts: 20

ゼロ手数料ノード：

minFeeMultiplier: 0

rest gatewayを公開しない：

gateways:
    - openPort: false

ジェネレーションハッシュシード、バランス、ブロック１トランザクションをカスタム：

nemesisGenerationHashSeed: 7391E2EF993C70D2F52691A54411DA3BD1F77CF6D47B8C8D8832C890069AAAAA
nemesis:
    balances:
        TDN2CNADENSTASFK6SCB7MFQLAYNZB3JBZCBLLA: 898300000
        TBK7C5SI3NR3ZEZTMNXRISY6FENDK3YDE63HK7Q: 98800000
        TA45K3WZYQQKSFHJ3DSEQTOO6N7RMBQUVE7H6MA: 984750000
transactions:
        '16963_581474': A1000000000000...(serialized hex transaction)
        '16963_580690': A1000000000000...
        'MyTransaction': 01000000000000...

ターゲット：

生成された設定、dockerファイルやデータが保存されるフォルダの場所。フォルダ構成は以下：

  • ./config：dockerサービスが稼働するときにマウントされるノード設定。
  • ./config/generate-addresses：ランダムに生成されたデータ。プリセットでは提供されません。例：SSL キー, nodes キー, nemesis アカウント、ジェネレーションハッシュシードなど。
  • ./config/nemesis：nemgen toolを稼働させるときに使われる設定。
  • ./mongo：mongo データベースのデータ。
  • ./data
  • ./data/nemesis-data：ノードが読み込む nemesis データ。nemesis は ( bootstrapのような新規ネットワークの為に )生成されるか、既存のネットワーク( testnet ) からコピーされます。
  • ./docker：ネットワーク稼働時に使われる、生成された docker-compose.ymlとDockerFiles ファイル。
  • ./state：サービス実行同期に使われるフォルダ。

要求条件

  • NPM 10+
  • Docker
  • Docker Compose

以下のコマンドで環境を検証：

node -v
docker -v
docker-compose -v

あなたの user が sudo なしで docker を動かせるか確認

docker run hello-world

以下のようなエラーが出たら

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

この ガイド にしたがってください。

使い方

空のワーキングディレクトリでコマンドを使うことを推奨します。

デフォルトではネットワーク設定、データ、dockerファイルはターゲットフォルダ( ./target ) 内に生成されます。

mkdir my-networks
cd my-networks

ワーキングディレクトリで一回：

$ npm install -g symbol-bootstrap
$ symbol-bootstrap COMMAND
running command...
$ symbol-bootstrap (-v|--version|version)
symbol-bootstrap/0.1.0 linux-x64 node-v12.18.4
$ symbol-bootstrap --help [COMMAND]
USAGE
  $ symbol-bootstrap COMMAND
...

一般的な使い方は以下のようにになります：

symbol-bootstrap config -p bootstrap
symbol-bootstrap compose
symbol-bootstrap run

これらのコマンドをワンライナーでまとめることもできます：

symbol-bootstrap start -p bootstrap

新たに作り直す必要があるときは、ターゲットフォルダを suro で削除する必要があるでしょう。( docker ボリュームディレクトリは sudo で作られるため )

sudo rm -rf ./target

E2Eテスティングサポート

このコマンドラインインターフェイスの一つの使用例はE2Eテスティングサポートです。もしあなたがシンボルクライアントをコーディングしているなら、あなた( Travis か Jenkins ) は以下のようにe2eテストを走らせることができます。

symbol-bootstrap start -p bootstrap --detached
YOUR TEST (e.g: npm run test, gradle test, selenium etc.)
symbol-bootstrap stop

--detached はサーバーが起動すまで（ ネットワーク http://localhost:3000/node/health ポーリング ）待ちます。コンポーネントが30秒で立ち上がらない場合、コマンドは失敗します。  

もし、あなたのe2eテストを特別な状態 ( 特別なバランス、アドレス、モザイクネームスペース、ジェネレーションハッシュシードなど ) でハジメたい場合、あなた独自のカスタムプリセット( -c )を提供できます。

CLI経由でノードクライアントE2E:

コマンドラインインターフェイスは npm プロジェクト( dev )依存としても利用できます ( npm install --save-dev symbol-bootstrap ) 。そしてネットワークをあなたのnpmテストサイクルに統合できます。あなたのpackage.jsonは以下のようになります：

"devDependencies": {
    ....
    "symbol-bootstrap": "0.0.x",
    ....
}

scripts": {
...
    "clean-network": "symbol-bootstrap clean",
    "run-network": "symbol-bootstrap start -c ./output/my_custom_preset.yml --detached",
    "run-stop": "symbol-bootstrap stop",
    "integration-test": "....some mocha/jest/etc tests running against localhost:3000 network....",
    "e2e": "npm run clean-network && npm run run-network && npm run integration-test && npm run stop-network",
...
}

そして、あなた、Jenkins、Travis や あなたの CI tool は稼働できます;

npm run e2e

API経由でノードクライアントE2E:

他の方法として、サーバーをプログラム的に起動、停止するために BootstrapService ファサードを使うことができます。　

例：

it('Bootstrap e2e test', async () => {
    const service = new BootstrapService();
    const config: StartParams = {
        preset: Preset.bootstrap,
        reset: true,
        timeout: 60000 * 5,
        target: 'target/bootstrap-test',
        detached: true,
        user: 'current',
    };
    try {
        await service.stop(config);
        const configResult = await service.start(config);
        expect(configResult.presetData).not.null;
        expect(configResult.addresses).not.null;
        // Here you can write unit tests against a http://localhost:3000 network
    } finally {
        await service.stop(config);
    }
});

beforeAll, afterAll ステートメントを利用し複数テストのため、同じサーバーを再利用することを推奨します。

開発

このツールに貢献したい場合は、このリポジトリをクローンし、実行してください：

npm install -g

すると、symbol-bootstrap はソースコードから実行します。コードを変更した後、あなたのフューチャーを試すことができます。

プルリクエストを歓迎します！コントリビュートガイドラインに従ってください。

注：このリポジトリのクローンはツールで設定できない方法でツールを調整したい人のみ。この場合フューチャーリクエストを送ってください。一般的なユーザーはこのt−るを他のノードモジュールと同じようにインストールすべきです。

コマンド

コマンドトピックス

  • symbol-bootstrap clean - ターゲットフォルダを削除 ( root権限が必要な場合動かないでしょう！ ) 
  • symbol-bootstrap compose - 設定したネットワークから docker-compose.yml ファイルを生成
  • symbol-bootstrap config - 現在のネットワークの為に設定ファイルとnemesisブロックをセットアップするために使われるコマンド
  • symbol-bootstrap help - symbol-bootstrap のヘルプを表示
  • symbol-bootstrap run - 生成された docker-compose.yml ファイルと設定を使い、docker経由でネットワークを起動。 このコマンドの前に The config and compose methods/commands を呼ぶ必要があります。 これはdocker-compose up bash call の為のただのラッパーです。
  • symbol-bootstrap start - config,composeをまとめて一行で実行する簡単なコマンド！
  • symbol-bootstrap stop - (symbol-bootstrap started with --detached)で動いていれば、docker-compose ネットワークを停止する。 docker-compose down bash コールのただのラッパーです。

 

You may also like

Comments