Configuration in a file

Overview

A configuration 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 calls the Application.module function in the Application.kt file below:

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

Basic configuration

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

Engine configuration

If you use EngineMain, you can specify options common for all engines within the ktor.deployment group.

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

Netty

You can also configure Netty-specific options in a configuration file within the ktor.deployment group:

ktor {
    deployment {
        maxInitialLineLength = 2048
        maxHeaderSize = 1024
        maxChunkSize = 42
    }
}

SSL configuration

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

Custom configuration

Apart from specifying the predefined properties, Ktor allows you to keep custom settings in the configuration file. The configuration files below contain a custom jwt group used to keep JWT settings.

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'"
}

Predefined properties

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

Environment variables

In a configuration file, you can substitute parameters with environment variables by using the ${ENV}/$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 as follows:

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

Read configuration in code

Ktor allows you to access property values specified inside a configuration file in code. For example, if you've specified the ktor.deployment.port property,...

ktor {
    deployment {
        port = 8080
    }
}

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

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

Command line

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

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

You can also use the -P flag to override a custom property.

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/application.yaml 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:

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

Configuration in a file﻿

Overview﻿

note

Basic configuration﻿

Engine configuration﻿

Netty﻿

SSL configuration﻿

Custom configuration﻿

warning

Predefined properties﻿