ファイルでの設定

ファイルでの設定

Ktorでは、ホストアドレスやポート、ロードする

モジュール

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

など、さまざまなサーバーパラメータを設定できます。 設定方法は、サーバーの作成に使用した方法（

embeddedServerまたはEngineMain

アプリケーションのデプロイニーズに応じたサーバーの作成方法について説明します。

）によって異なります。

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

概要

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

• HOCON (application.conf)

• YAML (application.yaml)

  NOTE

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

  依存関係

  既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法について説明します。

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

  現在、MavenベースのKtorプロジェクトではYAML構成はサポートされていません。

構成ファイルには、少なくとも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ポートでリッスンできるようにし、別のsecurityブロックで必要な

SSL設定

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

を指定しています。

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。 このオプションは

Shutdown 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秘密鍵のパスワード。

環境変数

構成ファイルでは、パラメータを環境変数に置き換えることができます。

• HOCON (application.conf) では、${ENV}構文のみがサポートされています。
• YAML (application.yaml) では、${ENV}と$ENVの両方の構文がサポートされています。

例えば、PORT環境変数をktor.deployment.portプロパティに次のように割り当てることができます。

application.confapplication.yaml

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

application.confapplication.yaml

コード内での構成の読み取り

Ktorを使用すると、構成ファイルで指定されたプロパティ値にアプリケーションコードからアクセスできます。 以下の例では、ktor.deployment.portプロパティを指定しています。

application.confapplication.yaml

ApplicationEnvironment.config() 関数を使用してアプリケーションの構成にアクセスし、プロパティ値を取得できます。必要な値にアクセスするには.property()関数を使用し、オプションの値には.propertyOrNull()を使用します。

構成をデータクラスにデシリアライズする

構成値を型安全に利用するために、構成をKotlinクラスにデシリアライズ (deserialize) できます。

以下の例では、appとsecurityの構成セクションを定義し、それらをシリアライズ可能なKotlinデータクラスにマッピングしています。

application.confapplication.yaml

特定の構成セクションをデシリアライズするには、Application.property()またはApplication.propertyOrNull()関数を使用します。

ApplicationConfig全体をデシリアライズする必要がある場合は、ApplicationConfig.getAs()関数を使用します。

コマンドライン

サーバーの作成にEngineMainを使用する場合、

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

Ktor Gradleプラグインを使用して、実行可能なfat JARを作成して実行する方法について説明します。

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

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

-jar

JARファイルへのパス。

-config

resources内の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プロパティに割り当てられています。その後、KTOR_ENVの値をローカル環境と本番環境で異なる値に設定できます。

application.confapplication.yaml

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

完全なコード例については、engine-main-custom-environmentを参照してください。