Symbol REST 2.5.1をNode.js 22でビルドする手順のメモです。

対象のDockerfileでは、Node.jsのデフォルトが20になっています。Node.js 20はすでにEOL（サポート終了）のため、Node.js 22でイメージを作り直す応急処置として試します。

Dockerfileの依存パッケージをインストールする処理を変更し、zeromq が依存する nan を 2.22.2 に固定します。作成したイメージは、Shoestringの設定に指定して利用します。

ここで紹介する確認は、Node.jsのバージョンとZeroMQモジュールの読み込みまでです。REST APIやWebSocket通知が正常に動作するか、継続して運用できるかは未確認です。

着手前に依存パッケージの動作を軽く確認する

Node.jsのメジャーバージョンを変更するため、先に主要な依存パッケージがNode.js 22で動作するか、検証用の環境で軽く確認しておく必要があります。対象のpackage.jsonで依存関係と各パッケージの対応Node.jsバージョンを確認し、インストールや読み込み、代表的な処理を試しておきます。特に zeromq のようなネイティブモジュールは、ビルドと読み込みの両方を確認します。

後述の require('zeromq') は、作成したイメージでの最低限の確認です。これだけですべての依存パッケージの互換性を確認できるわけではないため、ノードへ適用する前にはRESTの起動やAPI応答、WebSocket通知も検証環境で確認してください。

ソースコードを取得する

GitとDockerが利用できる環境で、対象のタグを指定して取得します。

git clone https://github.com/symbol/symbol.git -b rest/v2.5.1 --depth 1
cd symbol/client/rest/

以降の編集とビルドは、symbol/client/rest/ で行います。

なぜnanを2.22.2に固定するのか

zeromq@5.3.1 が依存する nan@2.17.0 のままでは、Node.js 22でのビルドに失敗します。そのため、今回は nan を 2.22.2 に固定します。

Dockerfileを変更する

vi Dockerfile

元のDockerfileにある、次の行を変更します。

RUN npm uninstall . && rm -rf node_modules && npm install --omit=dev

変更後は次のとおりです。

RUN npm pkg set "overrides.zeromq.nan=2.22.2" \
    && npm install --package-lock-only --ignore-scripts \
    && npm ci --omit=dev

npm pkg set で、zeromq 配下の nan に適用するバージョン指定を package.json に追加します。npmのoverridesは、このように依存先のパッケージのバージョンも指定できます。

続いてlockfileに変更を反映し、npm ci --omit=dev で開発用の依存パッケージを除いてインストールします。--ignore-scripts を付けるのはlockfile更新の段階だけです。最後の npm ci では、ネイティブモジュールのビルドに必要なインストールスクリプトを実行できるようにします。

なお、npm ciは既存の node_modules を削除してからインストールするため、変更後の処理では rm -rf node_modules を別に実行していません。

イメージをビルドする

ビルド引数でNode.js 22を指定します。

docker build \
  --build-arg NODE_MAJOR=22 \
  -t symbol-rest:2.5.1-node22 \
  .

作成するイメージ名は symbol-rest:2.5.1-node22 です。Node.jsのメジャーバージョンを指定しているため、パッチバージョンはビルド時に取得されるものによって変わります。

Node.jsのバージョンを確認する

docker run --rm \
  --entrypoint node \
  symbol-rest:2.5.1-node22 \
  --version

表示されたバージョンが v22. で始まることを確認します。

ZeroMQの読み込みを確認する

docker run --rm \
  --entrypoint node \
  symbol-rest:2.5.1-node22 \
  -e "require('zeromq'); console.log('ZeroMQ OK')"

読み込みに成功すると、次の文字列が表示されます。

ZeroMQ OK

ZeroMQ OK と表示されれば、少なくともモジュールの読み込みは成功しています。ただし、このコマンドではSymbolノードへの接続やメッセージの送受信は行っていません。実際にちゃんと動くかどうかは、別途確認が必要です。

Shoestringに作成したイメージを指定する

ここからは、既存のShoestringのノード配置先で作業します。ビルドしたイメージが、そのノードを動かすDocker環境に存在していることが前提です。別のマシンでビルドした場合は、先にイメージを転送して読み込んでおきます。

使用中の shoestring.ini を開き、[images] セクションの rest を変更します。以下は該当箇所の抜粋です。

[images]
rest = symbol-rest:2.5.1-node22

同じセクションの client や mongo など、ほかの設定は残します。[images] の rest がREST用イメージの指定に使われることは、Shoestringの設定読み込み処理で確認できます。

設定後、Shoestringの upgrade コマンドを実行してCompose定義などを再生成します。ウィザードからアップグレードするとDockerイメージの指定が元に戻るため、今回は必ずコマンドで実行します。

コマンドのオプション指定を間違えると、既存の環境が壊れる可能性があります。実行前にノードを停止し、必ず keys/ と shoestring/ ディレクトリをバックアップしてください。

バックアップ先はノードの配置先とは別の場所とし、秘密鍵を含む keys/ は第三者がアクセスできない場所で保管します。

また、既存のCompose定義や userconfig/ を削除して作り直す処理なので、これらも復旧用に保存しておきます。upgradeの実装も参照してください。

たとえば、Mainnetで、設定が shoestring/shoestring.ini、独自設定が shoestring/overrides.ini、配置先がカレントディレクトリの場合は次の形です。ShoestringをインストールしたPython環境で実行します。

python3 -m shoestring upgrade \
  --config shoestring/shoestring.ini \
  --overrides shoestring/overrides.ini \
  --directory . \
  --package mainnet

ネットワーク、設定ファイル、独自設定ファイル、配置先は使用中の環境に合わせます。--rest-overrides も使用している場合は、更新時にも同じ指定を引き継いでください。

更新後は docker compose config でRESTサービスのイメージが symbol-rest:2.5.1-node22 になっていることを確認してから、ノードを起動します。

起動後はログ、REST APIの応答、WebSocketでのブロック通知を確認します。モジュールの読み込み確認だけで、ノードとしての動作確認を済ませたことにはしないようにします。