メインコンテンツまでスキップ
Version: v2.2.0

構築手順

1. 目的

本ドキュメントはFRUCtoS配布パッケージを用いて、FRUCtoSを動作させる環境を構築するための手順を説明した資料です。
本ドキュメントはソフトウェアのインストール、OSの環境設定など基本的なコンピュータ管理の知識とその操作権限をもつ方を対象としています。 また、本書ではDockerを用いた環境構築手順を中心に解説しているため、Dockerの基本的な知識があるとより望ましいです。

2. FRUCtoSの全体像

本パッケージにより構成されるFRUCtoSの概念図と利用するTCPポートアドレス及びURLを下記に示します。

注意

本配布パッケージに予め設定されている各種情報や本書で示される設定情報は動作確認のためのものであり、実運用を考慮したものではありません。

特に、Keycloakを用いたGatewayの構成はあくまで参考実装であり、同梱のKeycloak-Gatewayはその実装サンプルです。 Keycloakを使用してFRUCtoSをご利用の際は、管理者アカウントのパスワード変更や実装先に合わせた構成の見直し等、セキュリティ対策を十分に行ってください。 使用時に発生したトラブルにつきまして、利用者が一切の責任を負うものとします。

全体の概念図

利用するTCPポートアドレスとURL

3. FRUCtoSを動作させるのに必要な環境

3.1. サーバ

3.1.1. OS

FRUCtoSは以下のOSで動作確認済みです。これらのOSを利用することを推奨します。

  • Windows 11 Pro
  • macOS 14.3 Appleシリコン
  • Ubuntu 22.04 LTS

3.1.2. Docker

本パッケージで提供されるFRUCtoSはDockerコンテナ上での動作を前提としています。 Dockerのインストールや設定についてはDocker設定手順を御覧ください。

注意

docker-composeのバージョンがv2.0.0以上の場合、以降のドキュメントサイトに記載されているdocker-composeコマンドをdocker composeコマンドに読み替えて実行してください。
また以下のファイル内のコマンドについてもdocker-composeコマンドをdocker composeコマンドに修正した後ご利用ください。
・ 『dist/keycloak/deploy_all.sh』
・ 『dist/keycloak/deploy_all_win.bat』
・ 『dist/log-tools/startupErrorDetection.bat』
・ 『dist/log-tools/startupErrorDetection.ps1』
・ 『dist/log-tools/startupErrorDetection.sh』

3.2. クライアント

FRUCtoSはHL7FHIR規格のREST APIサーバです。動作確認にはOAuth2認証に対応したREST API Clientが必要です。本書ではPostmanを用いた動作確認を解説しています。

4. FRUCtoSの構築手順

4.1. 構築から動作確認までの流れ

FRUCtoSの構築から動作確認までの手順を以下に図示します。

4.2. Dockerのインストールと設定

Docker設定手順を参照してください。

4.3. FRUCtoSの配置

配布パッケージを解凍するとfructos-x.x.xx.x.xの部分はバージョン番号)というフォルダができます。以下の説明ではこのfructos-x.x.xというフォルダを$WORKで表します。

配布パッケージには以下のものが含まれます。
ファイル名の「?.?.?」にはバージョンが設定されます。例)gateway-0.0.2-SNAPSHOT.jar

資料場所
KeycloakとGatewayのdocker-composeファイル『dist/keycloak/docker-compose.yml』
Gateway用のDockerfile『dist/keycloak/Dockerfile』
『dist/keycloak/Dockerfile.keycloak』
Keycloakの設定ファイル『dist/keycloak/realm-export.json』
gatewayのjarファイル『dist/keycloak/gateway-?.?.?-SNAPSHOT.jar』
postmanの設定ファイル『dist/keycloak/client.postman_collection.json』
Docker起動用スクリプト
(mac)『dist/keycloak/deploy_all.sh』
(windows)『dist/keycloak/deploy_all_win.bat』
FRUCtoS構築用配布物dist/fructos_docker フォルダ内
利用しているOSSのライセンスファイルlicense フォルダ内
Docker コンテナログ確認スクリプトdist/log-tools フォルダ内
管理システム構築用配布物dist/fructos_admin_docker フォルダ内
※構築手順については管理システムの構築手順を御覧ください。
管理システム利用時のオプション資材dist/fructos_admin_docker_attachment フォルダ内
アダプタ開発用配布物dist/repository-adapter-sample フォルダ内
ダンプツール配布物dist/dump-tools フォルダ内
および dist/dump-tools-auditevent フォルダ内

dist/以下にFRUCtoSの実行環境を構築するために必要なファイルが配置されています。

4.4. Dockerコンテナ作成と起動

4.4.1. FRUCtoSサーバ

Dockerイメージ・コンテナの作成と起動

$WORK/dist/fructos_dockerフォルダへ移動し、docker-composeコマンドにより、Dockerイメージ・コンテナを作成します。
FRUCtoSサーバはDB管理システムとしてPostgreSQLを使用します。DBの接続情報は環境変数として .envファイルに記載されていますので、当ファイルを編集することで変更できます。 コンテナのポート番号はdocker-compose.ymlを編集することで変更できます。
管理システムを利用する場合には8. 管理システム利用時の追加作業の手順を先に実施して下さい。
過去にインストールしたFRUCtoSサーバのDocker環境が残っている場合には7.環境削除を参照して下さい。

注意

セキュリティ上の観点から、DBの接続情報やコンテナのポート番号の変更をお勧めします。

  1. .envファイルの初期値
    FRUCTOS_PSQL_USER=fructos                                      ・・・(ユーザ名)
    FRUCTOS_PSQL_PASSWORD=fructos#2020 ・・・(パスワード)
    FRUCTOS_PSQL_DB=fructos ・・・(DB名)
    FRUCTOS_AUDIT_PSQL_USER=fructos_audit ・・・(監査ログのユーザ名)
    FRUCTOS_AUDIT_PSQL_PASSWORD=fructos!audit#2020 ・・・(監査ログのパスワード)
    FRUCTOS_AUDIT_PSQL_DB=fructos_audit ・・・(監査ログのDB名)
    FRUCTOS_CONFIGURATION_PSQL_USER=fructos_configuration ・・・(設定永続化のユーザ名)
    FRUCTOS_CONFIGURATION_PSQL_PASSWORD=fructos!configuration#2020 ・・・(設定永続化のパスワード)
    FRUCTOS_CONFIGURATION_PSQL_DB=fructos_configuration ・・・(設定永続化のDB名)
  2. tomcat/config/environmentファイルの初期値(※管理システム利用時)
    .envファイルと同様
  3. docker-compose.ymlファイルの初期値(抜粋)
    services:
    db:
    # ...
    tomcat:
    # ...
    ports:
    - "8099:8080"
    # ...
  4. docker-composeによる起動
    Shell
    docker-compose up -d --build
Dockerコンテナの起動確認

docker-compose psコマンドでコンテナの起動状態を確認します。なお、本ドキュメントではdocker-compose 1.xでの表示例を掲載しており、docker-composeのバージョンによっては表示形式の異なる場合があります。お使いのバージョンに合わせて適宜読み替えてください。

Shell
docker-compose ps
               Name                             Command               State           Ports
---------------------------------------------------------------------------------------------------------------------------------------
FRUCtoS_postgres docker-entrypoint.sh -c co ... Up 5432/tcp
FRUCtoS_postgres_audit docker-entrypoint.sh -c co ... Up 5432/tcp
FRUCtoS_postgres_configuration docker-entrypoint.sh -c co ... Up 5432/tcp
FRUCtoS_tomcat /bin/sh -C 'java -jar Pack ... Up 139/tcp, 2222/tcp, 0.0.0.0:8099->8080/tcp, :::8099->8080/tcp

Stateが全てUpになっていればコンテナの起動成功です。

note

Portsの->の左側の値は、「4.4.2. FRUCtoSサーバ」の「Dockerイメージ・コンテナの作成と起動」のdocker-compose.ymlで設定したポート番号になります。

FRUCtoSサーバの起動確認

以下のdocker-compose logsコマンドでFRUCtoSサーバの起動状態を確認します。

Shell
docker-compose logs -f
   ....
FRUCtoS_tomcat | 08-Oct-2021 17:36:08.729 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [57307] milliseconds

FRUCtoS_tomcatのServer startupが表示されていれば起動完了です。Ctrl+Cで止めてください。

Dockerコンテナのログ確認

Dockerコンテナのログにエラーが出力されていないか確認します。
$WORK/dist/fructos_dockerフォルダで確認用スクリプトを実行してください。
確認用スクリプトは$WORK/dist/log-toolsに配置されています。パス指定、或いは必要に応じてコピーして使用してください。
以下のDockerコンテナのログ確認の手順は相対パス指定で実行している例です。

Windows

PowerShellスクリプトを実行して確認します。

PowerShell
PowerShell -f ..\log-tools\startupErrorDetection.ps1
tip

環境によりPowerShellスクリプトが実行出来ない場合は、必要に応じてPowerShellスクリプトの実行に先立ち、 以下の「Windowsの実行ポリシーの設定」や「PowerShellスクリプトのプロパティ変更」を行ってください。

  • 実行ポリシーの設定
    PowerShell
    Set-ExecutionPolicy RemoteSigned -Scope Process
    『y』を入力してください。
  • プロパティ変更
    startupErrorDetection.ps1ファイルの『セキュリティ』を次の手順で許可にしてください。
    1. startupErrorDetection.ps1ファイルをエクスプローラーで選択し、マウスボタン右クリックでプロパティを表示します。
    2. 『全般』タブの『セキュリティ:』の『許可する(K)』をチェックします。
info

PowerShellの代わりにバッチファイルによる実行も可能です。
但しバッチファイル中で使用しているfindstrコマンドの制限のためログ出力が多い場合は正常に実行できません。

コマンドプロンプト
..\log-tools\startupErrorDetection.bat
Linux または macOS
Shell
sh ../log-tools/startupErrorDetection.sh
結果確認

以下のメッセージが出力されていればサーバ起動時にエラーメッセージは出力されていません。

docker container: fructos_docker エラーは検出されませんでした

4.4.2. Keycloak Gateway

Keycloak Gatewayの設定はFRUCtoSサーバの起動確認ができてから実施します。

Dockerイメージ・コンテナの作成と起動

Keycloak Gatewayの配置フォルダ$WORK/dist/keycloakへ移動しての作業となります。 Keycloak Gatewayの起動用のスクリプトとしてLinuxおよびMacはdeploy_all.sh、 Windowsはdeploy_all_win.batがありますので、これを使用します。 しかし、FRUCtoSがKeycloak Gatewayとは異なるマシンにある場合や、 ネットワークインタフェースが複数ある場合には利用できませんので、 環境変数DOCKERHOSTを設定し、 FRUCtoSサーバと同様にdocker-composeコマンドでDockerイメージ・コンテナを作成および起動する必要があります。

スクリプトによる起動
  • Windows
    コマンドプロンプト
    deploy_all_win
  • LinuxまたはmacOS
    Shell
    sh ./deploy_all.sh
tip

FRUCtoSがKeycloak Gatewayとは異なるマシンにある場合、ネットワークインタフェースが複数ある場合、あるいはifconfigコマンドが利用できない環境の場合は、 FRUCtoSのあるマシンのIPv4アドレス、あるいは利用したいネットワークアダプタに設定されているIPv4アドレスを環境変数DOCKERHOSTに設定してください。 Keycloak Gatewayの配置フォルダに.envファイルを作成し、そこに下記のように記載します。

  • .envファイル
    DOCKERHOST=<IPv4アドレス>
docker-composeコマンドによるDockerイメージ、コンテナの作成
Shell
docker-compose -p keycloak up -d --build
Dockerコンテナの起動確認

docker-compose psコマンドでコンテナの起動状態を確認します。

Shell
docker-compose -p keycloak ps
      Name                     Command               State                     Ports
--------------------------------------------------------------------------------------------------------------------------
keycloak_gateway /bin/sh -c /wait && java - ... Up 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp
keycloak_keycloak /opt/jboss/tools/docker-en ... Up 8080/tcp, 8443/tcp, 0.0.0.0:8090->8090/tcp, :::8090->8090/tcp
keycloak_postgres docker-entrypoint.sh postgres Up 5432/tcp

Stateが全てUpになっていればコンテナの起動成功です。

Keycloak Gatewayの起動確認

以下のdocker-compose logsコマンドでFRUCtoSサーバの起動状態を確認します。

Shell
docker-compose -p keycloak logs -f
   ....
keycloak_gateway | 2021-10-08 18:31:38.353 INFO 1 --- [main] jp.fructos.gateway.GatewayApplication : Started GatewayApplication in 40.8 seconds

keycloak_gatewayのStarted GatewayApplicationが表示されていれば起動完了です。Ctrl+Cで止めてください。

4.5. 動作確認用クライアントのインストールと設定

動作確認にはREST APIクライアントであるPostmanを使用します。 クライアントはKeycloak GatewayやFRUCtoSとは別のマシンへのインストールも可能ですが、本手順書では同じマシン上にインストールします。
PostmanはWebブラウザ上で動作するWebバージョンとWindows, macOS, Linux用のデスクトップアプリケーションがあります。Webバージョンはユーザ登録が必用ですが、インストール不要です。 デスクトップアプリケーションは、ユーザ登録は不要ですがインストールが必要です。本書ではデスクトップアプリケーションを用います。

デスクトップアプリケーションのインストール

https://www.postman.com/downloads/ よりインストーラを入手して実行して下さい。インストール完了後にPostmanを起動します。

設定
  1. Importボタンを押下するとImportダイアログが開きます。Fileタブを選択し、Upload Filesボタンを押して下さい。
  2. ファイル選択ダイアログが表示されますので、配布物$WORK/dist/keycloak/client.postman_collection.jsonを選択して下さい。
  3. Collectionsメニューで[client]が表示されていることを確認します。

以上でPostmanの設定は完了です。

5. 動作確認

Postmanを用いた動作確認の手順の例を示します。

Keycloak Gatewayを通してのFRUCtoSのAPI実行にはOAuth2のAccessTokenが必要です。

5.1. AccessToken の取得

POST get tokenを開き、[Send]ボタンを押してレスポンスのBodyより"access_token"の値を取り出し、クリップボードなどにコピーします。この値がAccessTokenで、5分間有効です。

5.2. Metaデータの取得

GET metadataを開き、Authorizationタブを選択し、TypeはBearer Tokenを選択し、コピーしたAccessTokenを[Token]の値として貼りつけた後、[Send]ボタンを押下します。 Test Resultsが下図の様に200 OKでBodyが表示されれば成功です。

5.3. 患者リソースの作成

POST createを開き、Authorizationタブを選択し、TypeはBearer Tokenを選択し、コピーしたAccessTokenを[Token]の値として貼りつけた後、[Send]ボタンを押下します。 Test Resultsが下図の様に201 CreatedでBodyに作成した患者情報が表示されれば成功です。

5.4. 作成した患者リソースの読み込み

GET readを開き、Authorizationタブを選択し、TypeはBearer Tokenを選択し、コピーしたAccessTokenを[Token]の値として貼りつけた後、[Send]ボタンを押下します。 Test Resultsが下図の様に200 OKでBodyにPatient=1の患者情報が表示されれば成功です。

6. 停止と起動

構築後のKeycloak Gateway、FRUCtoSの停止・起動はDockerコンテナの停止・起動により行います。停止はKeycloak Gateway → FRUCtoSの順に行ないます。 起動は逆にFRUCtoS → Keycloak Gatewayの順に行います。

6.1. Keycloak Gatewayの停止

Keycloak Gatewayの配置フォルダへ移動してdocker-compose stopにより停止します。その後docker-compose psでコンテナの起動状態を確認します。

Shell
docker-compose -p keycloak stop
Stopping keycloak_gateway  ... done
Stopping keycloak_keycloak ... done
Stopping keycloak_postgres ... done
Shell
docker-compose -p keycloak ps
      Name                     Command               State    Ports
-------------------------------------------------------------------
keycloak_gateway /bin/sh -c /wait && java - ... Exit 143
keycloak_keycloak /opt/jboss/tools/docker-en ... Exit 0
keycloak_postgres docker-entrypoint.sh postgres Exit 0

Stateが全てExitになっていればコンテナの停止成功です。

6.2. FRUCtoSの停止

FRUCtoSの配置フォルダへ移動してdocker-compose stopにより停止します。その後docker-compose psでコンテナの起動状態を確認します。

Shell
docker-compose stop
Stopping FRUCtoS_tomcat                 ... done
Stopping FRUCtoS_postgres_configuration ... done
Stopping FRUCtoS_postgres_audit ... done
Stopping FRUCtoS_postgres ... done
Shell
docker-compose ps
               Name                             Command                State     Ports
--------------------------------------------------------------------------------------
FRUCtoS_postgres docker-entrypoint.sh -c co ... Exit 0
FRUCtoS_postgres_audit docker-entrypoint.sh -c co ... Exit 0
FRUCtoS_postgres_configuration docker-entrypoint.sh -c co ... Exit 0
FRUCtoS_tomcat catalina.sh run Exit 143

Stateが全てExitになっていればコンテナの停止成功です。

6.3. FRUCtoSの起動

FRUCtoSの配置フォルダへ移動してdocker-compose startにより起動します。その後docker-compose psでコンテナの起動状態を確認します。

Shell
docker-compose start
Starting db               ... done
Starting audit-db ... done
Starting configuration-db ... done
Starting tomcat ... done
Shell
docker-compose ps
               Name                             Command               State           Ports
---------------------------------------------------------------------------------------------------------------------------------------
FRUCtoS_postgres docker-entrypoint.sh -c co ... Up 5432/tcp
FRUCtoS_postgres_audit docker-entrypoint.sh -c co ... Up 5432/tcp
FRUCtoS_postgres_configuration docker-entrypoint.sh -c co ... Up 5432/tcp
FRUCtoS_tomcat /bin/sh -C 'java -jar Pack ... Up 139/tcp, 2222/tcp, 0.0.0.0:8099->8080/tcp, :::8099->8080/tcp

Stateが全てUpになっていればコンテナの起動成功です。

note

Portsの->の左側の値は、「4.4.2. FRUCtoSサーバ」の「Dockerイメージ・コンテナの作成と起動」 の docker-compose.ymlで設定したポート番号になります。

6.4. Keycloak Gatewayの起動

Keycloak Gatewayの配置フォルダへ移動してdocker-compose startにより起動します。その後docker-compose psでコンテナの起動状態を確認します。

Shell
docker-compose -p keycloak start
Starting postgres ... done
Starting keycloak ... done
Starting gateway ... done
Shell
docker-compose -p keycloak ps
      Name                     Command               State                     Ports
--------------------------------------------------------------------------------------------------------------------------
keycloak_gateway /bin/sh -c /wait && java - ... Up 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp
keycloak_keycloak /opt/jboss/tools/docker-en ... Up 8080/tcp, 8443/tcp, 0.0.0.0:8090->8090/tcp, :::8090->8090/tcp
keycloak_postgres docker-entrypoint.sh postgres Up 5432/tcp

Stateが全てUpになっていればコンテナの起動成功です。

7. 環境削除

警告

本手順の実施後、DBのデータは削除されます。
データを移行する必要がある場合は、バージョンアップ手順の2.1. 旧環境のデータのエクスポートを本手順の実施前に行ってください。

7.1. Keycloak Gateway の環境削除

Keycloak Gatewayの配置フォルダへ移動してdocker-compose down --rmi allによりDockerコンテナとDockerイメージの削除を行ないます。

Shell
docker-compose -p keycloak down --rmi all
Removing keycloak_gateway   ... done
Removing keycloak_keycloak ... done
Removing keycloak_postgres ... done
Removing network dist_gateway-net
Removing image library/postgres:12
Removing image jboss/keycloak:7.0.1
Removing image dist_gateway

7.2. FRUCtoSの環境削除

FRUCtoSの配置フォルダへ移動してdocker-compose down --rmi allによりDockerコンテナとDockerイメージを削除します。

Shell
docker-compose down --rmi all
Stopping FRUCtoS_tomcat                 ... done
Stopping FRUCtoS_postgres_configuration ... done
Stopping FRUCtoS_postgres_audit ... done
Stopping FRUCtoS_postgres ... done
Removing FRUCtoS_tomcat ... done
Removing FRUCtoS_postgres_configuration ... done
Removing FRUCtoS_postgres_audit ... done
Removing FRUCtoS_postgres ... done
Removing network fructos_docker_of_net
Removing image library/postgres:13
Removing image library/postgres:13
WARNING: Image library/postgres:13 not found.
Removing image library/postgres:13
WARNING: Image library/postgres:13 not found.
Removing image fructos_docker_tomcat

7.3. Databaseイメージの削除

警告

本手順の実施後、DBのデータは削除されます。
データを移行する必要がある場合は、バージョンアップ手順の2.1. 旧環境のデータのエクスポートを本手順の実施前に行ってください。

FRUCtoSおよびKeycloakで使用しているDatabaseイメージはdocker-composeでは削除されません。 docker volume lsで確認後docker volume rmにより、以下のDBを削除します。

  • keycloak_postgres_data (keycloak用のDB)
  • fructos_docker_database (FRUCtoS用のDB)
  • fructos_docker_audit_database (FRUCtoSの監査ログ用のDB)
  • fructos_docker_configuration_database (FRUCtoSの設定永続化用のDB)
Shell
docker volume ls
DRIVER    VOLUME_NAME
local keycloak_postgres_data
local fructos_docker_audit_database
local fructos_docker_configuration_database
local fructos_docker_database
Shell
docker volume rm keycloak_postgres_data fructos_docker_audit_database fructos_docker_configuration_database fructos_docker_database
keycloak_postgres_data
fructos_docker_audit_database
fructos_docker_configuration_database
fructos_docker_database

8. 管理システム利用時の追加作業

管理者システム利用者向けオプション資材の配置作業について説明します。
以下の例では配布パッケージを展開した$WORK/distで作業します。

  1. fructos_admin_docker_attachment/configフォルダを中身ごとfructos_docker/tomcat/にコピーします。
    • Windows
      コマンドプロンプト
      xcopy fructos_admin_docker_attachment\config fructos_docker\tomcat\config /I
    • LinuxまたはmacOS
      Shell
       cp -r fructos_admin_docker_attachment/config/. fructos_docker/tomcat/config
  2. fructos_admin_docker_attachment/packagesフォルダを中身ごとfructos_docker/tomcat/にコピーします。
    • Windows
      コマンドプロンプト
      xcopy fructos_admin_docker_attachment\packages fructos_docker\tomcat\packages /I
    • LinuxまたはmacOS
      Shell
      cp -r fructos_admin_docker_attachment/packages fructos_docker/tomcat/packages
  3. fructos_admin_docker_attachment/docker-compose.ymlfructos_docker/docker-compose.ymlに上書きします。
    • Windows
      コマンドプロンプト
      copy /Y fructos_admin_docker_attachment\docker-compose.yml fructos_docker\docker-compose.yml
    • LinuxまたはmacOS
      Shell
      cp fructos_admin_docker_attachment/docker-compose.yml fructos_docker/docker-compose.yml
  4. fructos_admin_docker_attachment/Dockerfilefructos_docker/tomcat/Dockerfileに上書きします。
    • Windows
      コマンドプロンプト
      copy /Y fructos_admin_docker_attachment\Dockerfile fructos_docker\tomcat\Dockerfile
    • LinuxまたはmacOS
      Shell
      cp fructos_admin_docker_attachment/Dockerfile fructos_docker/tomcat/Dockerfile

※ 管理システム用に、fructos_docker/tomcat/config/environmentファイルにもfructos_docker/.envファイルと同様の設定をして下さい。