vbmeg_docker

vbmeg docker構築ガイド

このドキュメントはvbmeg dockerというソフトウェアの使用説明書です。vbmeg dockerは、VBMEGという脳波・脳磁図解析ソフトをdockerを使って簡単に実行できるようにするためのソフトウェアです。このページでは、vbmeg dockerのインストール方法や設定方法、起動方法などについて詳しく説明しています。

dockerとは？

dockerとは、とても簡単にいうと、「OSとソフトがインストールされた環境自体」を、１つのアプリのようなもの（コンテナといいます）に閉じ込めて利用することのできる技術です。この技術を用いると、VBMEGの実行に必要なOS(Linux)とソフト(MATLAB、FreeSurfer、FSL、SPM、MRTrix)をコンテナにまとめてインストールし、その環境を起動して利用することができます。dockerの良い点と悪い点については、こちらにまとめましたのでご覧下さい。 それでは、vbmeg dockerのインストール方法について説明していきます。

目次

• vbmeg docker構築ガイド
  • dockerとは？
• vbmeg dockerのインストール手順
• 1.OS毎のdockerのインストール
  • Linux
  • Windows10
  • Mac
• 2.vbmeg dockerコンテナのインストール
  • 手順1 - vbmeg dockerをダウンロードする
  • 手順2 - コンテナをホストにインストールする
  • 手順3 - コンテナを起動する
• 3.コンテナにMATLABをインストールする
• 4.vbmeg dockerの基本設定を行う
  • 設定1 - FreeSurferのLicenseファイルを準備・格納する
  • 設定2 - MATLABのパスを設定する
  • 設定3 - ホストのディレクトリをコンテナでマウントする(解析用ディレクトリなどをコンテナ内で利用できるようにする)
• 4.コンテナを起動する
  • 手順1 - コンテナを起動する
  • 手順2 - デスクトップを表示する
• 5.VBMEG解析環境を起動する
  • 手順1 - 端末を起動する
  • 手順2 - VBMEGを起動する
  • コンテナ内データの保存について
  • うまくいかない場合は
• 6.コンテナを終了する
  • ctrlL+cで終了する
  • コンテナID（または名前)を指定して終了する
• Reference
  • vbmeg dockerの設定
    • デスクトップ解像度設定
    • MATLABパス設定
    • VBMEGディレクトリ設定
    • ホスト名設定
    • ネットワークドメイン名設定
    • コンテナ内のLinuxユーザーのUID/GID設定
  • コンテナ内のソフトウェアとパスについて
  • コンテナ内データの保存について
• history

vbmeg dockerのインストール手順

まずvbmeg dockerを利用するためには、基本的にはLinuxをインストールしたPCをご用意下さい。以降、vbmeg dockerの起動元のマシンのことをホストと呼び、インストールされるvbmeg dockerコンテナのことをコンテナと呼びます。ホストがWindows10やMacでも動作しますが、dockerはLinuxを利用するソフトウェアであるため、WindowsやMacでも内部ではLinuxが起動しています。そのため、CPUやメモリの観点からは推奨されません。dockerが動作するLinuxディストリビューションについては、dockerのインストール要件のページをご覧下さい。
https://docs.docker.com/engine/install/
執筆時点のdockerの最新バージョンは、v19.03.0です。

ハードウェアの最低スペックとして、

• ディスク容量：40GB以上
• メモリ:16GB以上

を必要とします。

1.OS毎のdockerのインストール

Linux

ここでは、Ubuntu 18.04を例にとり説明します。

1. ホスト(Ubuntu Linux 18.04)にdockerをインストールします。

   How to setup docker on host Ubuntu Linux?
   をご覧ください。

2. vbmeg_dockerのインストールに進みます。

※LinuxはUbuntu18.04で動作確認を行っています

Windows10

1. ホスト(Windows10）にWSL2+Linux(Ubuntu Linux)をインストールします。

   How to install WSL2 and Ubuntu Linux?

2. WSL上で実行されるUbuntu Linuxにdockerをインストールします。

   How to setup docker on host Ubuntu Linux?

3. vbmeg_dockerのインストールに進みます。

Mac

1. ホスト(Mac)にdockerをインストールします。

   How to setup docker on host macOS?

2. vbmeg_dockerのインストールに進みます。

2.vbmeg dockerコンテナのインストール

手順1 - vbmeg dockerをダウンロードする

1. Linuxを起動し、ターミナルを開きます(インストール先がリモートの場合はログインします(例：ssh algol))
2. カレントディレクトリをvbmeg dockerをインストールしたいディレクトリにします(ここではホームディレクトリにしています)。

   cd ~
   

3. vbmeg dockerをダウンロードします。

   wget https://vbmeg.atr.jp/download/v30/vbmeg_docker.zip

4. zipファイルを解凍します。

   unzip vbmeg_docker.zip

手順2 - コンテナをホストにインストールする

1. 解凍したフォルダに移動し、vbmeg_docker_install.shを実行します。

   cd vbmeg_docker
   chmod 755 *.sh
   ./vbmeg_docker_install.sh

   初回は、FSL、FreeSurfer、SPM8、MRtrixをダウンロードしますので、ダウンロードに数時間程度かかります。以降、他のホストにインストールする場合には、ダウンロード時間が発生せず、30分程度でインストールすることができます。ソフトは$vbmeg_docker/environment/docker/V**/software内に保存されます。

手順3 - コンテナを起動する

コンテナを起動するを参照してコンテナのデスクトップ画面を表示して下さい。デスクトップが表示されたらコンテナのインストールは成功しています。

3.コンテナにMATLABをインストールする

コンテナにMATLABをインストールするを参照して、コンテナにLinux版のMATLABをインストールします。

• 過去にインストールしたことがある場合は、$vbmeg_docker/MATLAB内にMATLABがありますので、インストール作業は不要です。
• Linux版のMATLABがインストールされたディレクトリをコンテナにマウントし、vbmeg_docker_settings.sh内のMATLABDIRのパスを設定することで、既存のMATLABを使用することができます(詳しい手順は、こちらを参照して下さい)。

ここで一旦、コンテナを終了させます(コンテナを終了する)。

4.vbmeg dockerの基本設定を行う

VBMEGで解析する前に、vbmeg dockerにいくつか基本設定が必要になります。以下の設定を行って下さい。

設定1 - FreeSurferのLicenseファイルを準備・格納する

1. https://surfer.nmr.mgh.harvard.edu/registration.htmlにアクセスし、手順に従って利用登録をします。
2. メールでlicense.txtというファイルが届くので、$vbmeg_docker/FreeSurferLicense/license.txtとなるようにファイルを置いて下さい。

設定2 - MATLABのパスを設定する

設定ファイルにコンテナ内のMATLABパスを記載します。
$vbmeg_docker/vbmeg_docker_settings.sh

MATLABDIR=/usr/local/MATLAB/Rxxxx (xxxxはバージョン番号)

設定3 - ホストのディレクトリをコンテナでマウントする(解析用ディレクトリなどをコンテナ内で利用できるようにする)

コンテナ内ではコンテナの起動元のディレクトリを参照することができないため、ディレクトリをマウントする必要があります。例外として、コンテナの/usr/local/アカウント以下はホスト側ディレクトリの$vbmeg_docker/userhome以下に保存されます。 dockerコマンドに、-v ホスト側ディレクトリ:コンテナ側ディレクトリという形式で渡すと、コンテナはそのディレクトリをマウントし、コンテナ側ディレクトリを通じてホスト側ディレクトリにデータを読み書きできるようになります(複数行指定可)。

$vbmeg_docker/$vbmeg_docker_desktop.sh

docker run \
...
...
-v /home/cbi-data33:/home/cbi-data33 \
...
...

以上で設定は終了です。次の項目のコンテナを起動する、から作業を行います。 その他の設定については、こちらをご覧下さい。

4.コンテナを起動する

インストールされたvbmeg dockerコンテナを起動します。

手順1 - コンテナを起動する

1. ターミナルを開きます(リモートホストの場合はログインします(例：ssh algol))
2. カレントディレクトリをvbmeg_dockerディレクトリにします。

   cd ~/vbmeg_docker
   

3. vbmeg_docker_desktop.shを実行します。

   ./vbmeg_docker_desktop.sh

   すると、以下のような表示が出ます。
   
   

4. 初回時のみVNC接続に使用するパスワードを聞かれます。VNCパスワードを2回入力して下さい。

   * Initial VNC password creation *
   Password:********

5. ターミナルはメッセージが表示され、入力が停止した状態となります。これでコンテナの起動は完了です。

   
   

手順2 - デスクトップを表示する

1. ブラウザを開き、From Browserの項目にあるURLにアクセスして下さい(例：http://algol.cns.atr.jp:8901)。すると、以下のような画面が表示されますので、「接続」ボタンを押します。

   
   

2. パスワード入力ダイアログが表示されるので、先ほど指定したパスワードを入力し、資格情報送信ボタンを押します。

   
   すると、コンテナ内に起動したデスクトップに接続が完了し、以下のように画面が表示されます。
   

3. 「use default config」ボタンを押して下さい。

   画面中央下部にDockが表示されます。
   
   

デスクトップを表示するにはブラウザ以外に汎用のVNCクライアントソフトからも可能です。

• ブラウザを使用する
  • ブラウザを開くだけで接続できる。複数起動した場合に、ブックマーク等で切り替えられる。
  • URL：http://ホスト名:ポート番号(例：http://algol.cns.atr.jp:5901)
• 汎用のVNCクライアントソフトを使用する
  • クリップボードのコピー＆ペーストが利用できる
  • 接続先＝ホスト名:ポート番号(例：algol.cns.atr.jp:5901)

ポート番号については、コンテナ起動時に表示される以下を参照して下さい(5901、8901の部分は変化します)

From VNC : algol.cns.atr.jp:5901
From Browser : http://algol.cns.atr.jp:8901

5.VBMEG解析環境を起動する

docker内でVBMEGの解析環境を起動します。

手順1 - 端末を起動する

ここからは、コンテナ内のデスクトップ操作になります。画面中央下部のDockの左から２番目の四角い黒アイコンをクリックします。

端末が起動します。


インストールされているアプリケーションのパス等の情報が表示されています。

手順2 - VBMEGを起動する

ホームディレクトリ(/usr/local/アカウント名)にあるvbmeg.shを実行して下さい。

cd ~
vbmeg.sh

MATLABにVBMEGとSPM8のパスが通った状態で起動します。
これでVBMEGでの作業ができる状態になりました。

もし、チュートリアルを試される場合は以下をご参照ください(この例はVBMEG v3のチュートリアルです。その他のバージョンはhttp://vbmeg.atr.jpをお訪ね下さい)。

• GUIを使った基本チュートリアルはこちら
• スクリプトを使ったAdvancedチュートリアルはこちら

コンテナ内データの保存について

コンテナの/usr/local/アカウント以下に保存したデータはホストの$vbmeg_docker/userhome以下に保存されます。 その他のディレクトリを指定したい場合は、以下の方法でご自身でマウントしてください。

• 以下のように$vbmeg_docker/vbmeg_docker_desktop.shを変更し、dockerコマンドに-vオプションで渡して下さい(複数指定可)。

  -v HOST側ディレクトリ名:コンテナディレクトリ名 \
  
  $vbmeg_docker/$vbmeg_docker_desktop.sh

  docker run \
  ...
  ...
  -v /home/cbi-data33:/home/cbi-data33 \
  ...
  ...
  

うまくいかない場合は

コンテナ内のソフトウェアのパスを確認して下さい。

6.コンテナを終了する

vbmeg dockerコンテナを終了します。vbmeg dockerコンテナの起動元で操作を行います。

ctrlL+cで終了する

「コンテナを起動する」で起動した端末を[ctrl]+[c]を押して終了すると、コンテナは終了します。

コンテナID（または名前)を指定して終了する

もし、なんらかの不具合でホストのコンテナ起動端末のみが終了し、コンテナが生き残った状態になってしまった場合は、以下のようにして、コンテナを終了させて下さい。

1. コンテナが実行されているホストにログインします。

   ssh algol

2. vbmeg_dockerディレクトリに移動します。

   cd $vbmeg_docker

3. ホストで起動中のコンテナをリストアップします。

   ./vbmeg_docker_list_container.sh

   以下のように、実行中のコンテナが表示されます。

   ============================
   CONTAINER ID NAMES
   7150e1bdd59f rhayashi-5901
   ============================
   To kill the container,
   docker rm -f CONTAINER ID or NAMES
   

4. コンテナを削除します
   • IDで削除する場合(IDは先頭から一意に特定できる数文字分指定すればよい)

     docker rm -f 715

   • 名前で削除する場合(コンテナの名前は、アカウント名-VNCのポート番号になっています)

     docker rm -f rhayashi-5901

Reference

vbmeg dockerの設定

vbmeg dockerの設定について説明します。 設定は、設定ファイル(vbmeg_docker/vbmeg_docker_settings.sh)を編集することで行います。

#/bin/bash
# This is a setting file for vbmeg_docker.
#
# [History]
# 2021/3/8 rhayashi
#
# [Description]
# You can change the settings to suit your environment.
# DESKTOP_GEOMETRY : Resolution of desktop size.
# MATLAB_DIR : MATLAB path used inside the docker container.
# DOWNLOAD_LINK : VBMEG download link.
# HOSTNAME : HOSTNAME is automatically acquired by hostname command.
# you can manually change this.
# POSTFIX_HOSTNAME : You may need the domain name in addition to the host name
# when accessing the container. This setting expects to specify a domain name.


# vbmeg docker version
export VBMEG_DOCKER_VERSION=V30

# Desktop resolution
export DESKTOP_GEOMETRY=1920x1080

# MATLAB directory of docker
export MATLABDIR=/usr/local/MATLAB/R2019b

# VBMEG download link
export DOWNLOAD_LINK=https://vbmeg.atr.jp/download/v30/vbmeg3_0_0_a_1.zip

# VBMEG directory on launcher linux
# (e.g. $SCRIPTDIR/vbmeg/vbmeg2_2_0_a_2)

# get directory of this script(vbmeg_install.sh)
SCRIPTDIR=$(dirname $(./readlink_cmn.sh $0))
export VBMEGDIR=$SCRIPTDIR/vbmeg/$(basename $DOWNLOAD_LINK .zip)

#
# --- Port settings
#

export VNC_PORT_START=5901 # How to choose VNC PORT:
export MAX_PORT_NUM=20 # Find a free port from VNC_PORT_START to VNC_PORT_START + MAX_PORT_NUM.
export HTTP_PORT_GAP=3000 # How to choose HTTP PORT:
# HTTP_PORT = VNC_PORT + HTTP_PORT_GAP

# HOSTNAME
export HOSTNAME=`hostname`
export POSTFIX_HOSTNAME=""
export HOSTNAME="$HOSTNAME$POSTFIX_HOSTNAME"

# /home directory mount option
# https://unix.stackexchange.com/questions/292999/mounting-a-nfs-directory-into-host-volume-that-is-shared-with-docker
export MOUNT_OPTION=:rslave

# for windows
# (This section overwrites settings : HOSTNAME and MOUNT_OPTION)
if [ -d /mnt/c ]; then
# HOSTNAME
export HOSTNAME=localhost
export MOUNT_OPTION=""
fi

デスクトップ解像度設定

以下の変数を任意の解像度を指定することができます(例:1920x1080)

DESKTOP_GEOMETRY=1280x1024

MATLABパス設定

MATLABディレクトリを指定します。このディレクトリはコンテナ内でのパスを指定します。

MATLABDIR=/usr/local/MATLAB/Rxxxx (xxxxはバージョン番号)

コンテナ内で、

matlab

を実行すると、$MATLABDIR/bin/matlabが呼び出されます。

VBMEGディレクトリ設定

使用するVBMEGディレクトリを指定することができます。このディレクトリは、ホスト側のパスで指定します。VBMEGのインストールは、$vbmeg_docker/vbmegに行われますので、基本は、以下のvbmeg3_0_0_a_0の部分を修正します。

VBMEGDIR=$SCRIPTDIR/vbmeg/vbmeg3_0_0_a_0

ここで指定されたパスがvbmeg dockerコンテナ内では、

/usr/local/vbmeg

となります。

ホスト名設定

vbmeg dockerコンテナ起動時に表示するホスト名を指定します。デフォルトでは自動でhostnmaeコマンドから取得するようになっています。

HOSTNAME=`hostname`

ネットワークドメイン名設定

vbmeg docker起動時に表示される、VNC接続情報およびブラウザURLについてはホスト名が表示されます。 例えば、ホスト名:algolの場合のブラウザURLは、http://algol:8901 のようにURLが表示されます。もし、ホストにアクセスする場合にドメイン名(.cns.atr.jp)が必要な場合は、POSTFIX_HOSTNAMEを指定すると、表示がhttp://algol.cns.atr.jp:8901のようになります。

POSTFIX_HOSTNAME = '.cns.atr.jp'

コンテナ内のLinuxユーザーのUID/GID設定

コンテナ内のLinuxユーザーは、何も設定しない場合、ホスト側のユーザー名、UID、GIDと同一になります。
もし、ファイルの所有者が問題になる場合は、下記のファイル内のLOCAL_UID, LOCAL_GIDに値を指定して下さい。
Linuxの場合、id -u usernameでUID、id -g usernameでGIDを取得できます(usernameはユーザー名)。 $vbmeg_docker/vbmeg_docker_desktop.sh

# Get Username
USER_NAME=`whoami`
LOCAL_UID=$(id -u $USER) # to specify Linux user id, please change here.
LOCAL_GID=$(id -g $USER) # to specify Linux group id, please change here.

コンテナ内のソフトウェアとパスについて

以下のソフトウェアがインストールされています。各ソフトウェアにはパスが通っています。
(VBMEG V3用は以下のようになっています)

ソフト名	バージョン	パス
VBMEG	VBMEGディレクトリ設定に指定したVBMEG	/usr/local/vbmeg
FreeSurfer	v6.0.1	/usr/local/freesurfer
FSL	v6.0.6.4	/usr/local/fsl
MRtrix	v3.0.3	/usr/local/mrtrix3
SPM	v8	/usr/local/spm8
MATLAB	MATLABパス設定に指定したMATLAB	/usr/local/MATLAB/Rxxxx

コンテナ内データの保存について

コンテナの/usr/local/アカウント以下に保存したデータはホストの$vbmeg_docker/userhome以下に保存されます。 その他のディレクトリを指定したい場合は、以下の方法でご自身でマウントしてください。

• 以下のように$vbmeg_docker/vbmeg_docker_desktop.shを変更し、dockerコマンドに-vオプションで渡して下さい(複数指定可)。

  -v HOST側ディレクトリ名:コンテナディレクトリ名 \
  
  $vbmeg_docker/$vbmeg_docker_desktop.sh

  docker run \
  ...
  ...
  -v /home/cbi-data33:/home/cbi-data33 \
  ...
  ...
  

history

• 2023/11/17 Base OS changed(Ubuntu 18.04 LTS to 20.04 LTS)
• 2023/04/18 fix problems
  • Changed FSL version(v6.0.5 to v6.0.6.4) inside container because of the installation cannot be succeeded from FSL site.
• 2022/09/05 fix problems
  • New MATLAB can now be installed (R2022a or later).
  • Fixed a bug that prevented FreeSurfer license files from being loaded.
• 2022/07/28 Released for VBMEG ver 3.0-0-a-0