ファイルでの設定

Ktorを使用すると、ホストアドレスやポート、

読み込むモジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

など、さまざまなサーバーパラメーターを構成できます。 設定は、サーバーを作成した方法、つまり

embeddedServerまたはEngineMain

アプリケーションのデプロイ要件に応じてサーバーを作成する方法を学びます。

によって異なります。

EngineMainの場合、Ktorは HOCON またはYAML形式を使用する設定ファイルから構成を読み込みます。この方法により、サーバーを構成する際の柔軟性が高まり、アプリケーションを再コンパイルすることなく設定を変更できます。さらに、コマンドラインからアプリケーションを実行し、対応する コマンドライン 引数を渡すことで、必要なサーバーパラメーターを上書きできます。

概要

EngineMain を使用してサーバーを起動する場合、Ktorは resources ディレクトリにある application.* というファイルから設定を自動的に読み込みます。以下の2つの設定形式がサポートされています。

• HOCON ( application.conf )

• YAML ( application.yaml )

  NOTE

  YAML設定ファイルを使用するには、ktor-server-config-yaml

  依存関係

  既存のGradle/MavenプロジェクトにKtor Serverの依存関係を追加する方法を学びます。

  を追加する必要があります。

設定ファイルには、少なくともktor.application.modulesプロパティを使用して指定された

読み込むモジュール

モジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。

が含まれている必要があります。例:

application.confapplication.yaml

この場合、Ktorは以下の Application.kt ファイル内のApplication.module関数を呼び出します。

読み込むモジュール以外にも、 事前定義された （ポートやホスト、SSL設定など）およびカスタムのさまざまなサーバー設定を構成できます。 いくつかの例を見てみましょう。

基本的な構成

以下の例では、サーバーのリスニングポートがktor.deployment.portプロパティを使用して8080に設定されています。

application.confapplication.yaml

エンジン構成

EngineMainを使用する場合、ktor.deploymentグループ内で、すべてのエンジンに共通のオプションを指定できます。

application.confapplication.yaml

Netty

構成ファイル内で、ktor.deploymentグループにNetty固有のオプションを設定することもできます。

application.confapplication.yaml

SSL構成

以下の例では、Ktorが8443番のSSLポートでリッスンすることを有効にし、必要な

SSL設定

必要な依存関係: io.ktor:ktor-network-tls-certificates コード例: ssl-engine-main, ssl-embedded-server

を個別のsecurityブロックで指定しています。

application.confapplication.yaml

カスタム構成

事前定義されたプロパティを指定する以外に、Ktorはカスタム設定を構成ファイルに保持することを許可します。 以下の構成ファイルには、JWT設定を保持するために使用されるカスタムjwtグループが含まれています。

application.confapplication.yaml

これらの設定はコードで読み込んで処理できます。

事前定義されたプロパティ

以下は、構成ファイル内で使用できる事前定義された設定のリストです。

ktor.deployment.host

ホストアドレス。

例 : 0.0.0.0

ktor.deployment.port

リスニングポート。このプロパティを0に設定すると、サーバーがランダムなポートで実行されます。

例 : 8080, 0

ktor.deployment.sslPort

リスニングSSLポート。このプロパティを0に設定すると、サーバーがランダムなポートで実行されます。

例 : 8443, 0

NOTE

SSLには、以下にリストされている追加オプションが必要であることに注意してください。

ktor.deployment.watch

自動リロードに使用される監視パス。

ktor.deployment.rootPath

サーブレット

WARアーカイブを使用してサーブレットコンテナ内でKtorアプリケーションを実行およびデプロイする方法を学びます。

コンテキストパス。

例 : /

ktor.deployment.shutdown.url

シャットダウンURL。 このオプションは、

シャットダウンURL

コード例: %example_name%

プラグインを使用することに注意してください。

ktor.deployment.shutdownGracePeriod

サーバーが新しいリクエストの受け入れを停止するまでの最大時間（ミリ秒単位）。

ktor.deployment.shutdownTimeout

サーバーが完全に停止するまで待機する最大時間（ミリ秒単位）。

ktor.deployment.callGroupSize

アプリケーション呼び出しを処理するために使用されるスレッドプールの最小サイズ。

ktor.deployment.connectionGroupSize

新しい接続を受け入れ、呼び出し処理を開始するために使用されるスレッドの数。

ktor.deployment.workerGroupSize

接続の処理、メッセージの解析、およびエンジンの内部作業を行うためのイベントグループのサイズ。

ktor.deployment.sslPortを設定した場合、以下の

SSL固有

必要な依存関係: io.ktor:ktor-network-tls-certificates コード例: ssl-engine-main, ssl-embedded-server

のプロパティを指定する必要があります。

ktor.security.ssl.keyStore

SSLキーストア。

ktor.security.ssl.keyAlias

SSLキーストアのエイリアス。

ktor.security.ssl.keyStorePassword

SSLキーストアのパスワード。

ktor.security.ssl.privateKeyPassword

SSL秘密鍵のパスワード。

環境変数

設定ファイルでは、${ENV} / $ENV構文を使用してパラメーターを環境変数に置き換えることができます。 例えば、PORT環境変数をktor.deployment.portプロパティに次のように割り当てることができます。

application.confapplication.yaml

この場合、環境変数の値がリスニングポートの指定に使用されます。 実行時にPORT環境変数が存在しない場合は、次のようにデフォルトのポート値を指定できます。

application.confapplication.yaml

コードでの設定の読み込み

Ktorでは、設定ファイル内で指定されたプロパティの値にコードからアクセスできます。 例えば、ktor.deployment.portプロパティを指定した場合、...

application.confapplication.yaml

...アプリケーションの設定には ApplicationEnvironment.config を使用してアクセスし、必要なプロパティ値は次のように取得できます。

これは、カスタム設定を設定ファイルに保持し、その値にアクセスする必要がある場合に特に役立ちます。

コマンドライン

EngineMainを使用してサーバーを作成する場合、コマンドラインから

パッケージ化されたアプリケーション

Ktor Gradleプラグインを使用して実行可能なfat JARを作成および実行する方法を学びます。

を実行し、対応するコマンドライン引数を渡すことで必要なサーバーパラメーターを上書きできます。例えば、設定ファイルで指定されたポートを次のように上書きできます。

利用可能なコマンドラインオプションは以下の通りです。

-jar

JARファイルへのパス。

-config

リソースからの application.conf / application.yaml の代わりに使用されるカスタム設定ファイルへのパス。

例 : java -jar sample-app.jar -config=anotherfile.conf

注 : 複数の値を渡すことができます。java -jar sample-app.jar -config=config-base.conf -config=config-dev.conf。この場合、すべての設定がマージされ、右側の設定の値が優先されます。

-host

ホストアドレス。

-port

リスニングポート。

-watch

自動リロードに使用される監視パス。

SSL固有

必要な依存関係: io.ktor:ktor-network-tls-certificates コード例: ssl-engine-main, ssl-embedded-server

のオプション:

-sslPort

リスニングSSLポート。

-sslKeyStore

SSLキーストア。

対応するコマンドラインオプションがない事前定義されたプロパティを上書きする必要がある場合は、-Pフラグを使用します。例:

-Pフラグを使用して、カスタムプロパティを上書きすることもできます。

例: カスタムプロパティを使用した環境の指定方法

サーバーがローカルで実行されているか、本番環境で実行されているかに応じて、異なる処理を行いたい場合があります。これを実現するには、 application.conf / application.yaml にカスタムプロパティを追加し、サーバーがローカルで実行されているか本番環境で実行されているかに応じて値が異なる専用の環境変数で初期化します。以下の例では、KTOR_ENV環境変数がカスタムのktor.environmentプロパティに割り当てられています。

application.confapplication.yaml

実行時にktor.environmentの値にアクセスするには、 コードで設定を読み込み 、必要なアクションを実行します。

完全な例はこちらで確認できます。 engine-main-custom-environment 。