Skip to content

ファイルでの設定

Ktorでは、ホストアドレスやポート、ロードするモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。など、さまざまなサーバーパラメータを設定できます。 設定方法は、サーバーの作成に使用した方法(embeddedServerまたはEngineMainアプリケーションのデプロイのニーズに応じてサーバーを作成する方法を学びます。)によって異なります。

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

概要

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

  • HOCON (application.conf)

  • YAML (application.yaml)

    YAML構成ファイルを使用するには、ktor-server-config-yaml依存関係既存のGradle/MavenプロジェクトにKtorサーバーの依存関係を追加する方法を学びます。を追加する必要があります。

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

構成ファイルには、少なくともktor.application.modulesプロパティを使用して指定された、ロードするモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。が含まれている必要があります。例:

shell
ktor {
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    application:
        modules:
            - com.example.ApplicationKt.module

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

kotlin
package com.example

import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        get("/") {
            call.respondText("Hello, world!")
        }
    }
}

ロードするモジュールの他に、定義済みのプロパティ(ポート、ホスト、SSL設定など)やカスタム設定など、さまざまなサーバー設定を構成できます。いくつかの例を見てみましょう。

基本設定

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

shell
ktor {
    deployment {
        port = 8080
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.module

エンジン設定

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

shell
ktor {
    deployment {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }
}
yaml
ktor:
    deployment:
        connectionGroupSize: 2
        workerGroupSize: 5
        callGroupSize: 10
        shutdownGracePeriod: 2000
        shutdownTimeout: 3000

Netty

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

shell
ktor {
    deployment {
        maxInitialLineLength = 2048
        maxHeaderSize = 1024
        maxChunkSize = 42
    }
}
yaml
ktor:
    deployment:
        maxInitialLineLength: 2048
        maxHeaderSize: 1024
        maxChunkSize: 42

SSL設定

以下の例では、Ktorが8443番のSSLポートでリッスンできるようにし、別のsecurityブロックで必要なSSL設定必要な依存関係: io.ktor:ktor-network-tls-certificatesを指定しています。

shell
ktor {
    deployment {
        port = 8080
        sslPort = 8443
    }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }

    security {
        ssl {
            keyStore = keystore.jks
            keyAlias = sampleAlias
            keyStorePassword = foobar
            privateKeyPassword = foobar
            trustStore = truststore.jks
            trustStorePassword = foobar
            enabledProtocols = ["TLSv1.2", "TLSv1.3"]
        }
    }
}
yaml
ktor:
    deployment:
        port: 8080
        sslPort: 8443
    application:
        modules:
            - com.example.ApplicationKt.module

    security:
        ssl:
            keyStore: keystore.jks
            keyAlias: sampleAlias
            keyStorePassword: foobar
            privateKeyPassword: foobar
            trustStore: truststore.jks
            trustStorePassword: foobar
            enabledProtocols: ["TLSv1.2", "TLSv1.3"]

カスタム設定

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

shell
ktor {
    deployment {
        port = 8080
    }

    application {
        modules = [ com.example.ApplicationKt.main ]
    }
}

jwt {
    secret = "secret"
    issuer = "http://0.0.0.0:8080/"
    audience = "http://0.0.0.0:8080/hello"
    realm = "Access to 'hello'"
}
yaml
ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.main

jwt:
    secret: "secret"
    issuer: "http://0.0.0.0:8080/"
    audience: "http://0.0.0.0:8080/hello"
    realm: "Access to 'hello'"

これらの設定はコード内で読み取って処理できます。

秘密鍵やデータベースの接続設定などの機密データは、構成ファイルにプレーンテキストで保存しないでください。そのようなパラメータを指定するには、環境変数の使用を検討してください。

定義済みプロパティ

以下は、構成ファイル内で使用できる定義済み設定の一覧です。

ktor.deployment.host

ホストアドレス。

例 : 0.0.0.0

ktor.deployment.port

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

例 : 8080, 0

ktor.deployment.sslPort

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

例 : 8443, 0

SSLには、以下にリストされている追加のオプションが必要です。

ktor.deployment.watch

オートリロードに使用される監視パス。

ktor.deployment.rootPath

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

例 : /

ktor.deployment.shutdown.url

シャットダウンURL。 このオプションはShutdown URLコード例: shutdown-urlプラグインを使用することに注意してください。

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のプロパティを指定する必要があります。

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プロパティに次のように割り当てることができます。

shell
ktor {
    deployment {
        port = ${PORT}
    }
}
yaml
ktor:
    deployment:
        port: ${PORT} # または $PORT

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

shell
ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
}
yaml
ktor:
    deployment:
        port: ${PORT:8080} # または "$PORT:8080"

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

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

shell
ktor {
    deployment {
        port = 8080
    }
}
yaml
ktor:
    deployment:
        port: 8080

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

kotlin
fun Application.module() {
    val port = environment.config.propertyOrNull("ktor.deployment.port")?.getString() ?: "8080"
    routing {
        get {
            call.respondText("Listening on port $port")
        }
    }
}

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

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

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

shell
app {
    port = 8080
    host = "0.0.0.0"
}

security {
    clientId = ${?CLIENT_ID}
    clientSecret = ${?CLIENT_SECRET}
}
yaml
app:
    port: 8080
    host: "0.0.0.0"
security:
    clientId: $CLIENT_ID
    clientSecret: $CLIENT_SECRET

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

kotlin
@Serializable
data class Security(val clientId: String, val clientSecret: String)

fun Application.module() {
    val securityConfig: Security = property("security")

    println("Authorization header: ${securityConfig.clientId}:${securityConfig.clientSecret}")
}

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

kotlin
@Serializable
data class App(val port: Int, val host: String)
@Serializable
data class Security(val clientId: String, val clientSecret: String)
@Serializable
data class Config(val app: App, val security: Security)

fun Application.module() {
    val config = environment.config.getAs<Config>()

    val clientId = config.security.clientId
    val clientSecret = config.security.clientSecret

    println("Authorization header: $clientId:$clientSecret")
}

コマンドライン

サーバーの作成にEngineMainを使用する場合、パッケージ化されたアプリケーションKtor Gradleプラグインを使用して実行可能なfat JARを作成および実行する方法を学びます。をコマンドラインから実行し、対応するコマンドライン引数を渡すことで、必要なサーバーパラメータをオーバーライドできます。例えば、構成ファイルで指定されたポートを次のようにオーバーライドできます。

shell
java -jar sample-app.jar -port=8080

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

-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のオプション:

-sslPort

リスニングSSLポート。

-sslKeyStore

SSLキーストア。

対応するコマンドラインオプションがない定義済みプロパティをオーバーライドする必要がある場合は、-Pフラグを使用します。例:

java -jar sample-app.jar -P:ktor.deployment.callGroupSize=7

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

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

カスタム構成プロパティを使用して、ローカル開発環境や本番環境など、サーバーが実行されている環境に応じてアプリケーションの動作を変更できます。

これを行うには、application.confまたはapplication.yamlでカスタムプロパティを定義し、環境変数からその値を割り当てます。以下の例では、KTOR_ENV環境変数がカスタムのktor.environmentプロパティに割り当てられています。その後、KTOR_ENVの値をローカル環境と本番環境で異なる値に設定できます。

ktor {
    environment = ${?KTOR_ENV}
}
yaml
ktor:
    environment: $?KTOR_ENV

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

kotlin
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Application.module() {
    val env = environment.config.propertyOrNull("ktor.environment")?.getString()
    routing {
        get {
            call.respondText(when (env) {
                "dev" -> "Development"
                "prod" -> "Production"
                else -> "..."
            })
        }
    }
}

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