Ktor 1.5.3 Help

Configuration

Ktor allows you to configure various server parameters, such as a host address and port, modules to load, enable the development mode, and so on. The configuration depends on the way you used to create a server - embeddedServer or EngineMain:

  • For embeddedServer, you can configure server parameters in code by passing the required parameters to the embeddedServer constructor.

  • For EngineMain, Ktor loads its configuration from an external file that uses the HOCON format. This way provides more flexibility to configure a server and allows you to change a configuration without recompiling your application. Moreover, you can run your application from a command line and override the required server parameters by passing corresponding command-line arguments.

embeddedServer

The embeddedServer function accepts different parameters for configuring a server, including a server engine, a host and port to listen, and so on. In this section, we'll take a look at several examples of running embeddedServer with different setting.

  • The code snippet below shows the basic server setup with the Netty engine and 8000 port.

    fun main() { embeddedServer(Netty, port = 8000) { // ... }.start(wait = true) }
  • In the example below, we've added the configure parameter for configuring setting specific for a selected engine. You can learn more about configuring engines from Configure an engine.

    fun main() { embeddedServer(Netty, port = 8000, configure = { connectionGroupSize = 2 workerGroupSize = 5 callGroupSize = 10 }) { // ... }.start(wait = true) }
  • The example below shows how to run a server with a custom environment represented by the ApplicationEngineEnvironment class.

    fun main() { embeddedServer(Netty, environment = applicationEngineEnvironment { log = LoggerFactory.getLogger("ktor.application") config = HoconApplicationConfig(ConfigFactory.load()) module { main() } connector { port = 8080 host = "127.0.0.1" } }).start(true) }

HOCON file

Overview

If you use EngineMain to start a server, Ktor loads configurations settings from the application.conf HOCON file placed in application resources. This file should contain at least modules to load specified using the ktor.application.modules property, for example:

ktor { application { modules = [ com.example.ApplicationKt.module ] } }

In this case, Ktor will call the Application.module function for the Application.kt file below:

package com.example import io.ktor.application.* import io.ktor.response.* import io.ktor.routing.* fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args) fun Application.module(testing: Boolean = false) { routing { get("/") { call.respondText("Hello, world!") } } }

Besides modules to load, you can configure various server settings, including predefined (such as a port or host, SSL settings, etc.) and custom ones. Let's take a look at several examples.

  • In the example below, a server listening port is set to 8000 using the ktor.deployment.port property.

    ktor { deployment { port = 8080 } application { modules = [ com.example.ApplicationKt.module ] } }
  • The example below enables Ktor to listen on the 8443 SSL port and specifies the required SSL settings in a separate security block.

    ktor { deployment { port = 8080 sslPort = 8443 watch = [ http2 ] } application { modules = [ io.ktor.samples.http2.Http2ApplicationKt.main ] } security { ssl { keyStore = build/temporary.jks keyAlias = mykey keyStorePassword = changeit privateKeyPassword = changeit } } }
  • The application.conf file below contains a custom jwt group to store JWT settings.

    jwt { domain = "https://jwt-provider-domain/" audience = "jwt-audience" realm = "ktor sample app" }

    You can read and handle such settings in code.

Predefined properties

Below is a list of predefined settings that you can use inside a configuration file.

  • ktor.deployment.host: A host address.
    Example: 0.0.0.0

  • ktor.deployment.port/ ktor.deployment.sslPort: A listening port/SSL port. Note that SSL requires additional options listed below.
    Example: 80/ 443

  • ktor.deployment.watch: Watch paths used for auto-reloading.

  • ktor.deployment.rootPath: A servlet context path.
    Example: /

  • ktor.deployment.shutdown.url: A shutdown URL. Note that this option uses the Shutdown URL feature.

  • Properties specific for engines. Learn more from EngineMain.

If you've set ktor.deployment.sslPort, you need to specify the following SSL-specific properties:

  • ktor.security.ssl.keyStore: An SSL key store.

  • ktor.security.ssl.keyAlias: An alias for the SSL key store.

  • ktor.security.ssl.keyStorePassword: A password for the SSL key store.

  • ktor.security.ssl.privateKeyPassword: A password for the SSL private key.

Command line

If you use EngineMain to create a server, you can run your application from a command line and override the required server parameters by passing corresponding command-line arguments. For example, you can override a port specified in the application.conf file in the following way:

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

The available command-line options are listed below:

  • jar: A path to JAR file.

  • config: A path to a custom configuration file used instead of application.conf from resources.

    java -jar sample-app.jar -config=anotherfile.conf
  • host: A host address.

  • port: A listening port.

  • watch: Watch paths used for auto-reloading.

SSL-specific options:

  • sslPort: A listening SSL port.

  • sslKeyStore: An SSL key store.

If you need to override a predefined property that doesn't have a corresponding command-line option, use the -P flag, for example:

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

Environment variables

In HOCON, you can substitute parameters with environment variables by using the ${ENV} syntax. For example, you can assign the PORT environment variable to the ktor.deployment.port property in the following way:

ktor { deployment { port = ${PORT} } }

In this case, an environment variable value will be used to specify a listening port. If the PORT environment variable variable doesn't exist at runtime, you can provide a default port value before assigning ${?PORT} as follows:

ktor { deployment { port = 8080 port = ${?PORT} } }

Read configuration in code

Ktor allows you to access property values specified in application.conf in code. For example, if you've specified the ktor.deployment.port property,...

ktor { deployment { port = 8000 } }

... you can access the application's configuration using ApplicationEnvironment.config and get the required property value in the following way:

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

This is especially useful when you keep custom settings in a configuration file and need to access its values.

Example: How to specify an environment using a custom property

You might want to do different things depending on whether a server is running locally or on a production machine. To achieve this, you can add a custom property in application.conf and initialize it with a dedicated environment variable whose value depends on whether a server is running locally or on production. In the example below, the KTOR_ENV environment variable is assigned to a custom ktor.environment property.

ktor { environment = ${?KTOR_ENV} }

You can access the ktor.environment value at runtime by reading configuration in code and perform the required actions:

fun Application.module(testing: Boolean = false) { val env = environment.config.propertyOrNull("ktor.environment")?.getString() routing { get { call.respondText(when (env) { "dev" -> "Development" "prod" -> "Production" else -> "..." }) } } }
Last modified: 19 April 2021