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.

Basic configuration

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

fun main() {
    embeddedServer(Netty, port = 8080) {
        // ...
    }.start(wait = true)
}

Engine configuration

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 = 8080, configure = {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
    }) {
        // ...
    }.start(wait = true)
}

Custom environment

The example below shows how to run a server with a custom environment represented by the ApplicationEngineEnvironment interface.

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)
}

You can also use a custom environment to serve HTTPS. The ssl-embedded-server example shows how to do this.

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 8080 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 } application { modules = [ com.example.ApplicationKt.module ] } security { ssl { keyStore = keystore.jks keyAlias = sampleAlias keyStorePassword = foobar privateKeyPassword = foobar } } }
The application.conf file below contains a custom jwt group to store JWT settings.
jwt { secret = "secret" issuer = "http://0.0.0.0:8080/" audience = "http://0.0.0.0:8080/hello" realm = "Access to 'hello'" }
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 plugin.
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 = 8080
                    }
                }
            

... 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: 11 May 2022