WHEELの起動方法
事前準備
WHEELの起動にはDockerを使用します。最新の Docker をインストールしてください。 なお、代表的な構成パターンを以下に示します。利用ユーザー数や使用可能なマシンなどの環境に従い、最適な構成をご検討ください。
構成パターン1：ユーザごとにWHEEL環境を構築
本パターンでは、ユーザの作業用PCそれぞれにDockerをインストールします。その上で、WHEELのコンテナイメージを展開し起動します。
構成パターン2：サーバにWHEEL環境を集約し構築
本パターンでは、1台のサーバにDockerをインストールします。その上で、WHEELを使用するユーザ数分のWHEELコンテナイメージを展開し、サーバ上で起動します。ユーザごとに使用するWHEELを分けるため、port番号での制御が必要となります。
起動方法
WHEELの起動方法は以下の通りです。 なお、ここでは 構成パターン1：ユーザごとにWHEEL環境を構築 にて構築することを前提として説明します。
- 任意の場所にディレクトリを作成します。(以降では、このディレクトリを
CONFIG_DIRとします。) -
HTTPS通信用のサーバ証明書および鍵ファイルを、それぞれ
server.crt,server.keyという名前でCONFIG_DIRに格納します。 自己証明書を使用する際は次のURLのドキュメントを参考にしてください。https://letsencrypt.org/docs/certificates-for-localhost/
なお、HTTP通信にてWHEELを使用する場合は、
CONFIG_DIRにサーバ証明書と鍵ファイルを格納する必要はありません。 本手順をスキップしてください。 -
ターミナルを起動し、以下のコマンドを入力します。
> docker run -d -v ${HOME}:/root -v CONFIG_DIR:/usr/src/server/app/config -e TZ=$(readlink /etc/localtime | sed 's#.*/zoneinfo/##') -p 8089:8089 tmkawanabe/wheel:latestこのとき、
CONFIG_DIRは、ホストマシン上での絶対パスである必要があります。上記コマンドでは、
- コンテナ内でのプロジェクトの作成先（/root）を、ホストの${HOME}にマッピングしています。 WHEEL上で作成されたプロジェクトは${HOME}に格納されます。 したがって、${HOME}にはWHEELからファイルの書き出しが行われるので、書き込み権限が必要です。
- コンテナ内での設定ファイルの置き場所（/usr/src/server/app/config）を、ホストの
CONFIG_DIRにマッピングしています。CONFIG_DIRにはWHEELからも書き込みが行われるので、書き込み権限が必要です。 また、以下のファイルは必要に応じて参照・編集してください。- wheel.log : WHEELのログファイル。
- jobScheduler.json : バッチシステムの設定。詳細は バッチシステムの設定を参照。
- server.crt/server.key : サーバ証明書/鍵ファイル
- WHHELのポート番号を8089に指定しています。
-e TZ=...の部分は、ホストマシンに設定されているタイムゾーンを読み取ってコンテナに渡すので、コンテナの時計がUTCではなくホストのローカル時刻と一致するようになります。ホストに合わせる代わりに特定のタイムゾーンを強制したい場合は、例えば-e TZ=Asia/Tokyoのように置き換えてください。
- WHEELサーバが起動したら、ホストマシン上でwebブラウザを開いて、
http(s)://localhost:8089にアクセスします。
HTTP通信を使用する方法
HTTPS通信の代わりにHTTP通信を使う場合は、 手順3. にてdocker runを実行する際に以下のオプションを追加します。
-e WHEEL_USE_HTTP=1
なお、HTTP通信はローカルネットワーク内での試用など、セキュリティ上の問題が無い環境でのみお使いください。
認証機構の有効化
起動時に、環境変数 WHEEL_ENABLE_AUTHを設定することで認証機構が有効化されます。
環境変数の値は何を設定しても有効になります。
認証機構が有効な場合、未ログイン状態のブラウザからのアクセスは全てログインページへリダイレクト され、ログイン処理を行なうまではWHEELの各画面にアクセスすることはできません。
ユーザ登録/削除は次のコマンドを介して行ないます。
node bin/passwordDBTool.js
オプション無しで起動した場合は、DB内に登録されているユーザ名の一覧を表示します。 それ以外の利用方法は次のとおりです。
ユーザの追加
次のコマンドで、ユーザ (foo)、 パスワード (bar) をDBに登録します
node bin/passwordDBTool.js -u foo -p bar
ユーザの削除
次のコマンドで既存のユーザ(foo)をDBから削除します
node bin/passwordDBTool.js -d -u foo
アノニマスユーザの作成
次のコマンドでアノニマスユーザを作成します。 既にDB内に存在する場合は、新規パスワードを発行します。
node bin/passwordDBTool.js -A
正常にアノニマスユーザが作成されると、画面に次のようにパスワードが出力されます。
Anonymous user created with password = XXXXXXXXXXXX
ログイン時には、ユーザ名として anonymous パスワードとして上記出力中の “XXXXXXXXXXXX” を入力してください。
DBの全削除
次のコマンドを実行するとDBのファイルが削除されます。
node bin/passwordDBTool.js -c
-c オプションは -A や -u, -p オプションと組み合わせて使うこともできます。
この場合、DBに存在する全ユーザが削除された上で、オプションで指定されたユーザが作成されます。
docker版起動時のAnonymousユーザ作成
docker版の起動時に、環境変数 WHEEL_ANONYMOUS_LOGIN が YES に設定されていると、
認証機構を有効にした上で、起動時に新規アノニマスユーザが作成されます。
アノニマスユーザのパスワードは、標準出力に表示されますが、
環境変数 WHEEL_ANONYMOUS_PASSWORD に値が設定されていると、その値の名前でパスワードを記載したファイルが生成されます。
リモートホスト設定
WHEELは、sshでログインした先の計算サーバ上でタスクを実行することが可能です。 ここでは、WHEELから計算サーバに接続するためのリモートホスト設定を行います。
リモートホスト設定には、以下の2パターンが存在します。使用する計算サーバに応じて設定を行ってください。
- バッチシステムがない場合 計算サーバにバッチシステムがない場合、もしくは計算サーバにバッチシステムがあっても使用しない場合は、本手順を実施します。
- バッチシステムがある場合の追加設定 計算サーバのバッチシステムを使用する場合は、バッチシステムがない場合の手順に加えて、本手順を追加実施します。
バッチシステムがない場合
まず、WHEELにアクセスし、画面右上のハンバーガーメニューをクリックします。
表示されたメニュー内の Remotehost editor をクリックします。リモートホスト設定ダイアログが表示されます。
画面上部の NEW REMOTE HOST SETTING ボタンをクリックします。新規ホスト設定ダイアログが表示されます。
フォームのうち次の項目に、値を入力してください。
- label
- 任意の文字列
- Hostname
- 接続先のホスト名またはIPアドレス
- Port number
- 接続先のポート番号
- User ID
- 接続先ホストでのユーザID
- Host work dir
- リモートホスト内で使用するディレクトリのパス
例えば、 foo.example.com ホストに対して、ユーザー bar で接続しタスクの実行を /home/users/bar/baz ディレクトリ以下で行なう設定をexample という名前で作成する場合、入力内容は次のようになります。
| 入力フィールド | 入力値 |
|---|---|
| 1 | example |
| 2 | foo.example.com |
| 3 | bar |
| 4 | /home/users/bar/baz |
labelはWHEELが接続先ホストを区別するための文字列で、大文字小文字が区別されます。
Hostname, User IDは接続先のホスト名(IPアドレスでも可)とユーザIDです。
これらのフィールドには、 ~/.ssh/config で設定した値を指定することもできます。
Host work dirには接続先ホストでの作業ディレクトリを絶対パスで指定します。 WHEELがリモートホストでプログラムを実行する時には、ここで指定したディレクトリの下にファイルを転送してから実行します。
通常は接続先ホストのホームディレクトリを指定しますが、システムによっては容量制限やI/O性能の都合で他の領域を使う方が良い場合もあります。 接続先システムの利用ガイド等を参照して適切なディレクトリを選択してください。
リモートホストへの接続に公開鍵認証を使用する場合 リモートホストへの接続に公開鍵認証を使用する際は、 use public key authentication のスイッチを有効にします。 下側に、秘密鍵を指定する欄が表示されるので、秘密鍵のパスを入力するか、 BROWSE ボタンをクリックしてファイルを選択します。
その他の詳細な設定内容は リファレンスマニュアル をご参照ください。
SSH認証方式（公開鍵認証・ssh-agent・~/.ssh/config の活用方法など）については SSH認証の設定 をご参照ください。
バッチシステムがある場合の追加設定
ここでは、計算サーバにバッチシステムがある場合に必要な追加のリモートホスト設定について説明します。 本手順を実施する際は、事前にバッチシステムがない場合の手順を実施してください。
リモートホストエディタを起動します。 バッチシステムがない場合で登録したリモートホストが表示されるので、右端の鉛筆アイコンをクリックしてホスト情報編集ダイアログを表示します。
リモートホストで使われているバッチシステムの種類を、 job scheduler の欄①から選びます。 現在設定可能な値は次の6種類です。
- PBSPro
- SLURM
- Fugaku
Fugakuについて 富岳では、Technical Computing Suite (TCS) 上でジョブ管理が行われています。同じジョブスケジューラを導入している他システムでは 動作確認を行なっていないため、富岳専用の設定(Fugaku)として用意しています
バッチシステムの設定について バッチシステムの種類を追加・削除したり、設定を変更する際はバッチシステムの設定をご参照ください。
続いて、使用可能なキュー名を available queues の欄(2)にカンマ区切りで入力します。 デフォルトキューが設定されているシステムで、デフォルトキューのみを使う場合は空欄のままでも構いません。
最後に、ジョブの同時投入本数に制限を行ないたい場合は、 max number of jobs の欄(3)を入力します。
例えば、同時投入本数が10本に制限されているシステムでは11本目のジョブを投入しようとするとエラーになりジョブ投入が受け付けられません。 そこでWHEEL側で制限を行なうことでこのようなエラーの発生を抑制できます。 ただし、WHEELを使わずに投入されたジョブ数は数えられません。そのため、グループ単位での同時投入ジョブ数が制限されているような場合は、制限に抵触する可能性もありますのでご留意ください。
サーバー設定のカスタマイズ
WHEELはすべての設定ファイル（server.json、jobScheduler.json）を以下の優先順位で読み込みます（上位が優先）。
- 環境変数（例:
WHEEL_PORT） — すべての設定ファイルより優先されます WHEEL_CONFIG_DIR/{ファイル名}—WHEEL_CONFIG_DIR環境変数でディレクトリを指定します~/.wheel/{ファイル名}— 簡単な方法: ホームディレクトリにファイルを置くだけで、環境変数は不要です- パッケージ組み込みのデフォルト値
~/.wheel/ を使う（推奨）
~/.wheel/ 以下にファイルを作成し、変更したい設定項目のみ記述してください。WHEELがデフォルト値と自動的にディープマージします。
例えばポート番号を変更する場合は ~/.wheel/server.json を作成します。
{ "port": 9000 }
バッチスケジューラーの設定を一部だけ変更する場合は ~/.wheel/jobScheduler.json を作成します。
{ "PBSPro": { "submit": "my-qsub" } }
Dockerをご利用の方
標準の docker run コマンドでWHEELを起動する場合、ホスト側の ${HOME} はコンテナ内の /root にマウントされています。
docker run -d -v ${HOME}:/root ...
そのため、コンテナ内の ~/.wheel/ はホスト側の ${HOME}/.wheel/ と同じディレクトリです。追加のボリュームマウントは不要で、ホスト側にファイルを作成するだけで自動的に読み込まれます。
server.json の設定項目
| キー | デフォルト値 | 対応する環境変数 | 説明 |
|---|---|---|---|
port |
8089 |
WHEEL_PORT |
WHEELが待ち受けるポート番号 |
numLogFiles |
5 |
— | 保持するログファイルの数 |
withLogin |
false |
— | ログイン必須にする（代わりに WHEEL_ENABLE_AUTH 環境変数を使用してください） |
numLocalJob |
1 |
WHEEL_NUM_LOCAL_JOB |
localhostで実行するtaskの同時実行本数 |
baseURL |
"" |
WHEEL_BASE_URL |
WHEELのベースURL（リバースプロキシ配下で使用） |
useHttp |
false |
WHEEL_USE_HTTP |
TLSを無効にしてHTTPで起動する |
acceptAddress |
null |
WHEEL_ACCEPT_ADDRESS |
接続を許可するクライアントのIPアドレス（nullは全て許可） |
logLevel |
"debug" |
WHEEL_LOG_LEVEL |
ログレベル（trace/debug/info/warn/error/fatal） |
verboseSsh |
false |
WHEEL_VERBOSE_SSH |
SSH接続時に詳細ログを出力する（-vvvオプション） |
enableWebApi |
false |
WHEEL_ENABLE_WEB_API |
Web APIエンドポイントを有効にする |
enableAuth |
false |
WHEEL_ENABLE_AUTH |
認証機構を有効にする |
注意:
WHEEL_LOGLEVELはWHEEL_LOG_LEVELに名称変更されました。既存の設定をお使いの場合は更新が必要です。
設定の移行（マイグレーション）
WHEELは起動時に、ユーザーの設定ファイル（~/.wheel/server.json、$WHEEL_CONFIG_DIR/server.json）を自動的に確認し、古いプロパティ名を新しい名前に書き換えます。書き換えが発生した場合は、起動時に console.warn メッセージが表示されます。
自動変換されるプロパティ名
| 旧プロパティ名 | 新プロパティ名 |
|---|---|
numJobOnLocal |
numLocalJob |
廃止された環境変数
| 廃止された環境変数 | 代替の環境変数 |
|---|---|
WHEEL_LOGLEVEL |
WHEEL_LOG_LEVEL |
廃止された環境変数が設定されている場合、WHEELは起動時に警告を表示します。廃止された環境変数は設定値として認識されないため、意図した設定が有効にならない場合があります。古い名前から新しい名前への更新をお願いします。