Libertyの基本的な構成方法

@2022 IBM Corporation
IBM Automation Software
Liberty Dojo 第⼆回
Libertyの基本的な構成
https://openliberty.io
⽇本IBM
⽥中孝清

View Slide

Liberty Dojo
1
開催⽇・時間タイトル担当
6/28(⽕) 17-18時 Cloud Nativeの世界でもJava EEを使える︕
OSSの実⾏環境 Open Liberty
⽥中孝清
7/12(⽕) 17-18時 Libertyの基本的な構成⽅法⽥中孝清
7/20(⽔) 13-14時 tWASからLibertyへのモダナイズカスタマー
サクセスマネージャ有志
8/2(⽕) 17-18時 MicroProfileを触ろう⾺場剛
申込はIBM Tech / Developer Dojoへ
https://ibm-developer.connpass.com/

View Slide

⾃⼰紹介
n
⽥中孝清
n ⽇本アイ・ビー・エム株式会社
オートメーションソフトウェアテクニカルセールス
n WebSphere Application Serverなどの
テクニカルセールスを20年以上担当
n Twitter @TTakakiyo
2

View Slide

本⽇のアジェンダ
n Get started
–JDK，Git，Maven
–EclipseとLiberty Developer Tools
–Liberty starter
n 基本情報
–Libertyのディレクトリ構成
–構成ファイルの種類
n server.xmlの基本
–デフォルトベースの構成
–時間の記述⽅法
–変数の使⽤
–別のファイルの読み込み
n server.xmlの構成例
–Featureの管理
–アプリケーションのデプロイ
–データベース接続の構成
n server.xml以外の構成ファイル
–server.env
–jvm.options
–bootstrap.properties
3

View Slide

Get Started
4

View Slide

Libertyを利⽤する前に⽤意するといいもの（1）
n JDK（Java SE 8 / 11 / 17などのバージョン）
例）
– IBM Semeru Runtimes︓
IBM Developerサイトから⼊⼿
https://developer.ibm.com/languages/java/semeru-runtimes/downloads/
– Eclipse Temurin︓
Adoptiumプロジェクトページから⼊⼿
https://adoptium.net/temurin/releases
n Git
n ビルドツール
– Maven
– Gradle
5

View Slide

Libertyを利⽤する前に⽤意するといいもの（2）
n Eclipse IDE for Enterprise Java and Web Developers
– https://www.eclipse.org/downloads/packages/
n IBM Liberty Developer Tools
– Eclipse IDE上で，メニューから
[Help] → [Eclipse Marketplace...]で
マーケットプレイスを開き，
検索してInstallする
6

View Slide

Open LibertyのGet Startedページ
https://openliberty.io/start/
n Starterによるプロジェクトのダウンロード
n ツールによるダウンロード
– Maven
• 依存関係（）に追加
– Gradle
• 依存関係（dependencies）に追加
– Docker
• docker pull open-liberty
n パッケージのダウンロード
– ZIPファイルを配布
7

View Slide

Starterで作成したプロジェクトをEclipse IDEにインポートする
n Starterで作成したMavenプロジェクトを，
「Import」 → 「Maven/Existing Maven projects」で取り込む
8

View Slide

早速エラーが報告されています
n SSLが必須なのにKeystoreが指定されていない
（デフォルトのまま）なので
エラーが報告されている
– コメントアウトされている
をpassword付きで設定すると
エラーが消えます
9

View Slide

EclipseのServersにLibertyを登録
n プロジェクトの「Maven」のメニューから
「Create WebSphere Liberty runtime
and server」選ぶと登録される
10
サーバー名の右クリックメニューから
様々な操作ができるようになる。

View Slide

今回のセッションの⽬的
n src/main/liberty/configの下に格納される
サーバーの構成情報を
どのように作っていけばいいのか
11

View Slide

基本情報
12

View Slide

Libertyのディレクトリ構成
• wlp ︓製品ルート
• bin ︓Libertyプロファイル管理スクリプト
• clients ︓Libertyプロファイルクライアント、シン・クライアント
• dev ︓ユーザー・コードから参照可能なライブラリ
• lib ︓プラットフォームのランタイム
• templates ︓構成のテンプレート、サンプル
• etc ︓全サーバーに適⽤される（デフォルトでは存在しない）
server.env, jvm.optionsファイルを配置
• usr ︓ サーバーの構成情報
• servers/ ︓ サーバー定義ディレクトリ
• apps ︓ アプリケーション・構成導⼊⽤ディレクトリ
• dropins ︓アプリケーション・ドロップイン導⼊⽤ディレクトリ
• logs ︓ サーバー・ログ・ディレクトリ（ffdc含む）
• workarea ︓サーバー・ワークエリア
• shared ︓共有ファイル・ディレクトリ
• apps ︓共有アプリケーション
• config ︓共有構成ファイル
• resource ︓共有リソース
13
ユーザーがファイルを置いてもいい場所（これ以外はファイルの追加・編集はできない）

View Slide

⼆つのディレクトリの使い分け
• etc ︓全サーバーに適⽤される（デフォルトでは存在しない）
server.env, jvm.optionsファイルを配置
• usr ︓ サーバーで使⽤される構成情報など
• servers/ ︓ サーバー定義ディレクトリ
• apps ︓ アプリケーション・構成導⼊⽤ディレクトリ
• dropins ︓アプリケーション・ドロップイン導⼊⽤ディレクトリ
• logs ︓ サーバー・ログ・ディレクトリ（ffdc含む）
• workarea ︓サーバー・ワークエリア
• shared ︓共有ファイル・ディレクトリ
• apps ︓共有アプリケーション
• config ︓共有構成ファイル
• resource ︓共有リソース
14
可搬性のある，どの環境でも動くの（ZIPにパッケージされる）
可搬性のない，その環境固有のもの（ZIPにパッケージされない）

View Slide

変数でのディレクトリの参照
n server.xml内では
${変数名}で値を参照できる
n 環境変数などで，
場所をデフォルトと変えた場合も，
変数で参照すれば，追随できる
n ${server.config.dir}
– ${server.config.dir}/server.xml や
${server.config.dir}/jvm.options などが
構成ファイルとして使われる
n ${server.output.dir}
– ${server.output.dir}/logs や
${server.output.dir}/workarea などに
ファイルが出⼒される
– 実⾏されているサーバーの
（デフォルトの）カレントディレクトリ
15
n ${wlp.install.dir}
– wlp
n ${wlp.user.dir}
– wlp/usr
n ${server.config.dir}
– wlp/usr/servers/サーバー名
n ${server.output.dir}
– wlp/usr/servers/サーバー名
n ${shared.app.dir}
– wlp/usr/shared/apps
n ${shared.config.dir}
– wlp/usr/shared/config
n ${shared.resource.dir}
– wlp/usr/shared/resouces

View Slide

サーバー定義ディレクトリ（usr/servers/サーバー名）の構成ファイル
n server.xml（必須）
– Libertyの⼤部分の設定をおこなう構成ファイル
– XML形式で記述される
n server.env
– サーバプロセスの環境変数を定義するファイル
– 名前=値を各⾏に記述する
n jvm.options
– サーバープロセスを実⾏するJVMに与えるオプション（引数）を定義する
– 各⾏にオプションを⼀つずつ記述する
n bootstrap.properties
– Libertyプロセスの起動時に読み込まれる
– server.xmlが読み込まれる前に設定する必要がある値（トレースなど）を設定する
16

View Slide

server.xmlの基本
17

View Slide

Eclipse上のLiberty Developer Toolによるserver.xmlの編集
n LDTを使うと，server.xmlをGUIを使って編集することができる
– 「Source」のタブで，XML形式のファイルを直接編集
– 「Design」のタブで，GUIでファイルを編集
n 構⽂チェックにも対応
– エラーがあると，サーバーを動かす前に，問題として報告される
18

View Slide

デフォルトベースの構成
n server.xmlで設定する全ての項⽬には「デフォルト値」が決まっている
– デフォルト値は，バージョンが上がっても変更されない
– バージョンが上がっても，構成ファイルが変更されなければ，同じ値が使われ続ける
n デフォルト値から変更する項⽬だけをファイルに記述する
– ⾮常に簡潔な構成ファイルで稼働する
– 別途，パラメーターシートなどで「デフォルトのまま」「変更したもの」を管理する必要はない
– 記述してあるものだけが「デフォルトから変更したもの」
n デフォルトの値は，Documentを参照することでもわかるが，
Eclipse上のLiberty Developer Toolで参照するのが便利
19

View Slide

Eclipse上のLiberty Developer Toolによるデフォルト値の確認
20
autoExpand="true" />
GUIで
開くと
明⽰的に記載された「アプリケーションの⾃動展開」以外の
4つの設定項⽬や，そのデフォルト値もわかる
GUIでデフォルト値から変更すると・・・
autoExpand="true"
startTimeout="15s"/>
隠れていた設定項⽬が
記載される

View Slide

server.xmlでの時間の設定項⽬
n 時間を設定する項⽬には，単位をつける
– d ⽇
– h 時間
– m 分
– s 秒
– ms ミリ秒
n 複数の単位を併⽤することもできる
– 「1m30s」→ 1分30秒（90秒）
21

View Slide

server.xmlでの変数の使⽤
n server.xmlの設定値には，以下の値が「${変数名}」で参照できる（下のものほど優先）
– server.xmlに記述された，要素のdefaultValue属性で指定された値
– 環境変数
– bootstrap.propertiesで指定された値
– Javaのシステムプロパティ
• Libertyの各種ディレクトリの位置を表す${wlp.install.dir}や${server.config.dir}なども
システムプロパティとして登録されている
– ${server.config.dir}/variablesディレクトリに置かれたファイルで指定された値
– server.xmlに記述された，要素のvalue属性で指定された値
– Libertyを起動したserverコマンドで「--」の後に指定された値
• 例） server run myserver -- --keyName=value
n 環境変数は，形式を変換されたものも検索される
たとえば${my.env.var}という変数が参照された場合，以下の環境変数が順に検索される
– my.env.var そのまま
– my_env_var 英数字以外を下線（_）に変換したもの
– MY_ENV_VAR 英字を⼤⽂字に変換したもの
22

View Slide

変数の使⽤例
n デフォルトの値をdefaultValueに構成しておいて，実⾏時に環境変数などでカスタマイズできる
– 例）デフォルトではhttpPortとして9080番，httpsPortとして9443番ポートが使⽤されるが，
「HTTP_PORT」などの環境変数で設定を上書きできる
n 数値の変数には，+や*などの数値演算が使⽤できる
– 例）httpPortとして，9000+80で9080番ポートが使⽤される
23

httpsPort="${https.port}" host="*"
id="defaultHttpEndpoint" />

httpsPort="${port.offset+443}" host="*"

View Slide

idによる参照
n 設定する要素の中には，他の要素の設定を参照しなければいけないものがある
– 例）DataSourceはJDBCドライバーが必要，JDBCドラーバーはライブラリ，ファイルセットが必要
n 他の要素の参照は，ネストするか，idを使⽤して参照する
24

dir="${shared.resource.dir}/derby"
includes="derby.jar" />

jdbcDriverRef="derbyDriver" />
libraryRef="derbyLib" />
filesetRef="derbyFile" />
dir="${shared.resource.dir}/derby"
includes="derby.jar" />
ネストした設定の例 idで参照した設定の例

View Slide

server.xmlから他のファイルの読み込み
n 要素で，他のファイルを読み込むことができる
– 相対パスで記述すると，元のファイルからの相対パス，${server.config.dir}からの相対パスが検索される
– 変数などを使⽤した絶対パスでの記述がおすすめ
– 読み込むファイルが存在しないとエラーとなる。存在するときにだけ読み込む場合にはoptionalを設定する
– location属性には，ネット上のURLも指定できる
25

View Slide

⾃動でincludeされるファイル
n 以下のファイルが存在していれば，⾃動的にserver.xmlファイルにincludeされる
– ${server.config.dir}/configDropins/defaults/ にあるXMLファイル
• server.xmlより先に読み込まれる
• 同じ設定項⽬がある場合には，server.xmlが優先される
– ${server.config.dir}/configDropins/overrides/ にあるXMLファイル
• server.xmlより後に読み込まれる
• 同じ設定項⽬がある場合には，構成は上書きされる
26

View Slide

パスワードの難読化
n パスワードを設定する属性には
XORやAESで難読化することができる
– Liberty Developer Toolsで「Set...」をおす
– ダイアログボックスでパスワードを⼊⼒し
難読化のEncodingを指定する
27

View Slide

server.xmlの動的更新
n Libertyのプロセス起動中にserver.xmlの内容を更新して保存した場合，
変更結果は即座に反映される
n したファイル，configDropinsのファイルが更新された場合も，即座に反映される
n 動的更新を無効にするには要素のupdateTrigger属性にmbeanを設定する
– MBean経由でトリガーされたときにのみ，再読み込みするようになる
28

View Slide

server.xmlの構成例
29

View Slide

Featureの構成
n アプリケーションやサーバーで使⽤するFeatureを
の⼦要素として設定する
– デフォルトは「なし」なので，構成しないとLibertyは何もできない
– 構成ファイル中に複数の要素がある場合，
定義された全てのが読み込まれる
n 依存関係も⾃動的に解決される
例）
– jaxrs-2.1を有効にすると
jaxrsClient-2.1, jsonp-1.1, servlet-4.0も有効になる
– jakartaee-8.0, もしくはjavaee-8.0, microProfile-2.0等を有効にすると
jaxrs-2.1が有効になる
n これを利⽤して，仕様群をまとめて有効にするFeatureも定義されている
– 上記のjavaee-8.0, microProfile-2.0など
n jakartaee-8.0などの統合Featureより，
個別のAPIのFeature単位で有効にした⽅が，
サーバーのランタイムを軽量に保てる
30

View Slide

Featureの構成（続き）
n 共存できないFeatureを同時に設定すると，
エラーとして報告される
– 異なるバージョンの仕様（Java EE 7とEE 8など）を混在させる
などするとエラーになる
n ⾜りないFeatureは，
featureUtilityコマンドで追加導⼊できる
– 例） % ./featureUtility if jsp-2.2
n サーバー名を指定して，server.xmlなどで
定義されたFeatureを追加導⼊できる
– 例） % ./featureUtility isf defaultServer
31
% ./featureUtility if jsp-2.2
初期化中...
リモート・フィーチャーを解決中です。このプロセスは、完了するまでに数分間かかる場合があ
ります。
資産をインストールする準備をしています。このプロセスは、完了するまでに数分間かかる場合
があります。
構成された Maven リポジトリーへの接続を確立中...
このプロセスは、完了するまでに数分間かかる場合があります。
構成されたリポジトリーへの接続が成功しました。
必要なフィーチャーをダウンロード中...
インストールを開始中...
フィーチャー jsp-2.2 を正常にインストールしました。
すべてのフィーチャーが正常にインストールされました。
製品妥当性検査を開始します...
製品妥当性検査が正常に完了しました。

View Slide

HTTPエンドポイントの構成
n LibertyがHTTPリクエストを処理するためにLISTENするエンドポイントの構成
n host属性（LISTENするさいにBINDするIPアドレス）のデフォルトは「localhost」
– デフォルトのままでは，ローカルからの接続しかできない
– 明⽰的に「host="*"」を指定し，全てのIPアドレスにBINDしないと，リモートからの接続ができない
n ⼦要素として構成できるものの例
– ︓HTTPレベルの各種設定
• ヘッダの数やサイズの制限，各種タイムアウトや，HTTP/2の設定など
– ︓TCPレベルの各種設定
• ソケットオプションや接続制限など
– ︓アクセスログを取得する構成
– ︓レスポンスを⾃動的に圧縮するための構成
32
httpPort="${http.port}" httpsPort="${https.port}"

View Slide

Java EE/Jakarta EEアプリケーションのデプロイ
n アプリケーションの配置場所は⼆種類
– ${server.config.dir}/dropins
• server.xmlなどに定義しなくても，アプリケーションとして実⾏される
• クラスローダーやセキュリティなど，追加の構成はできない
– ${server.config.dir}/apps
• server.xmlなどに定義すると，アプリケーションとして実⾏される
• クラスローダーやセキュリティなど，追加の構成ができる
n アプリケーションは，
war/earファイルを直接おいてもいいし，
同名のディレクトリを作成し，
その中に展開して配置してもいい
33
アーカイブを直接おいた例
展開して配置した例

View Slide

server.xmlへのアプリケーションの登録
n EARファイル
– 要素で登録する
– location要素でEARファイル/ディレクトリの場所を指定する
• 相対パスで記述したときは，${server.config.dir}/appsディレクトリからのパスとして扱われる
n WARファイル
– 要素で登録する
– location要素でWARファイル/ディレクトリの場所を指定する
• 相対パスで記述したときは，${server.config.dir}/appsディレクトリからのパスとして扱われる
– コンテキストルートは，以下の順で値が検索されて使⽤される（上のものほど優先）
• server.xmlファイルの要素のcontextRoot属性
• アプリのibm-web-ext.xmlファイルで設定されたcontext-root / server.xmlファイルの要素のcontext-root属性
• server.xmlファイルの要素のname属性
• WARファイルの（.war拡張⼦を除いた）ファイル名（dropinsにWARをおいた場合は，多くはこれになる）
34

View Slide

の⼦要素に設定できるものの例
n ︓アプリケーション・スコープ・プロパティ
– アプリケーションから参照される初期化パラメーターを設定する
n ︓クラス・ローダー
– アプリケーションが参照する外部ライブラリを設定する
n ︓アプリケーション・バインディング
– アプリケーション内で定義されているリソース参照やセキュリティ・ロールなどに
サーバーで構成されたリソースやロールをマップする
n ︓Webアプリケーション拡張
– IBMの独⾃拡張機能の構成をおこなう
35

View Slide

データベース・アクセスの構成
n Libertyで定義したDataSourceリソースを，アプリケーションから取得して利⽤する
n DataSourceの定義をおこなうために必要な要素
• ︓DataSourceの定義
• ︓使⽤するJDBCドライバーの定義
• ︓クラスを提供するライブラリ
•
︓JARのファイルの指定
• など︓DMBSごとの接続構成
• ︓コネクションプールの構成（オプション）
•
など︓接続のための認証情報（オプション）
n 対応しているDBごとに，
接続のためのプロパティ構成が⽤意されている
– 対応していないDBに接続する場合には，「⼀般JDBCドライバー・プロパティ」を使⽤する
– 「属性=値」の組み合わせが，そのまま接続時にPropertiesとしてわたされる
36

View Slide

データベース・アクセスの構成例
n 「jdbc/myDS」というJDNI名でアプリケーションから利⽤
n wlp/usr/shared/resources/derbyディレクトリに置いたderby.jarでJDBC接続
n サーバーの出⼒ディレクトリのresources/myDSディレクトリ以下にDBを作成
n コネクションプールの最⼤数は30
37

createDatabase="create"
databaseName="${server.output.dir}/resources/myDS"/>

View Slide

その他にどんな設定項⽬があるか，Liberty Developer Toolsで調べる⽅法
n server.xmlのGUIで適当な要素をえらんで
「Add」ボタンを押す
– その要素の⼦要素として設定可能な⼀覧が出てくる
n 適当な設定項⽬を選ぶと，簡単な説明が出る
n 実際にserver.xmlに追加してみて，
どんな設定項⽬があるが⾒てみる
– 要素を追加しただけだと，
「全部デフォルト」のままなのでサーバーの構成は壊れない
– 属性を編集してデフォルトから変更してはじめて
サーバーの構成に影響が出る
– 設定項⽬にマウスカーソルを合わせると，
簡単なヘルプがチップで出る
38

View Slide

server.xml以外の
構成ファイル
39

View Slide

server.env
n LibertyのJavaプロセスで使⽤される環境変数を定義する
– 各⾏に「環境変数名=値」を記述する（イコールの両側に空⽩を置いてはいけない）
– 「#」で始まる⾏はコメントとして無視される
n 以下の場所から検索され，全ての設定がマージされる
同じ値が設定されている場合は，下のものほど優先される
– ${wlp.install.dir}/etc/server.env
• デフォルト︓wlp/etc/server.env
– ${wlp.user.dir}/shared/server.env
• デフォルト︓wlp/usr/shared/server.env
– ${server.config.dir}/server.env
• デフォルト︓wlp/usr/servers/サーバー名/server.env
n ファイル内での環境変数の展開はできない
– 「LIBPATH=${WLP_USER_DIR}/shared/lib:${LIBPATH}」のような設定はできない
– 「# enable_variable_expansion」というコメント⾏をつけると展開されるようになるが，
プラットフォーム依存になる（Windowsとその他で挙動が異なる）ので，極⼒使わないほうがよい
40

View Slide

Libertyで使われる主な環境変数
n JAVA_HOME
– Libertyを起動するために使⽤するJava実⾏環境の場所を設定する
n WLP_USER_DIR
– ユーザー構成のディレクトリ${wlp.user.dir}をデフォルトの場所から変更する
n WLP_OUTPUT_DIR
– サーバーの出⼒先${server.output.dir}をデフォルトの場所から変えたい場合に設定する
– 新しいサーバーの出⼒先は「${WLP_OUTPUT_DIR}/サーバー名」になる
n LOG_DIR
– ログの出⼒先を，デフォルトの${server.output.dir}/logsから変更したいときに設定する
n SERVER_WORKING_DIR
– 実⾏中のサーバーのカレントディレクトリを，デフォルトの${server.output.dir}から変更したいときに設定する
41

View Slide

jvm.options
n サーバープロセスを実⾏するJVMに与えるオプション（引数）を定義する
– ⼀⾏にオプションを⼀つずつ記述する
n 以下の場所から検索され，全ての設定がマージされる
– ${wlp.user.dir}/shared/jvm.options
– ${server.config.dir}/configDropins/defaults/jvm.options
– ${server.config.dir}/jvm.options
– ${server.config.dir}/configDropins/overrides/jvm.options
n 四つのファイルがいずれも⾒つからなかった場合には，以下のファイルが使われる
– ${wlp.user.dir}/etc/jvm.options
n Javaヒープサイズの設定や，Verbose GCの設定などをおこなう
– 変数の展開はできないので，ログやダンプの出⼒先は，カレントディレクトリからの相対パスで記述
42

View Slide

参考︓Libertyでガーベッジ・コレクションの詳細情報を取得する
n https://qiita.com/TTakakiyo/items/ac92330fd862c9fe245c
43

View Slide

bootstrap.properties
n server.xmlで使⽤する変数を定義する
– 現在は環境変数で定義できるようになっため，この⽤途の重要性は少なくなっている
n server.xmlを読み込むよりも前，Libertyの起動シーケンスの最初期で読み込まれる
– server.xmlが読み込まれる前に有効にしたい⼀部の設定（問題判別のためのトレース出⼒など）を設定する
例）
• com.ibm.ws.logging.trace.file.name ︓トレースを出⼒するファイル名
• com.ibm.ws.logging.trace.specification ︓トレースを出⼒するコンポーネントや出⼒レベルの構成
n server.xmlと同じディレクトリ，${server.config.dir}に配置される
– 形式はJavaの通常のプロパティファイル（名前=値が各⾏に書かれている）
44

View Slide

Liberty Dojo
45
開催⽇・時間タイトル担当
6/28(⽕) 17-18時 Cloud Nativeの世界でもJava EEを使える︕
OSSの実⾏環境 Open Liberty
⽥中孝清
7/12(⽕) 17-18時 Libertyの基本的な構成⽅法⽥中孝清
7/20(⽔) 13-14時 tWASからLibertyへのモダナイズカスタマー
サクセスマネージャ有志
8/2(⽕) 17-18時 MicroProfileを触ろう⾺場剛
申込はIBM Tech / Developer Dojoへ
https://ibm-developer.connpass.com/

View Slide

Libertyの基本的な構成方法

Libertyの基本的な構成方法

Takakiyo Tanaka

More Decks by Takakiyo Tanaka

Other Decks in Technology

Featured

Transcript