Engines

To run a Ktor server application, you need to create and configure a server first. Server configuration can include different settings: a server engine, various engine-specific options, host and port values, and so on. The following engines are supported:

Netty
Jetty
Tomcat
CIO (Coroutine-based I/O)

In addition to the engines mentioned above, Ktor provides a special engine type TestEngine for testing application logic. You can learn more about it from Testing.

Add dependencies

Before using the desired engine, you need to add the corresponding dependency to your build.gradle or pom.xml file:

ktor-server-netty
ktor-server-jetty
ktor-server-tomcat
ktor-server-cio

Below are examples of adding a dependency for Netty:

implementation "io.ktor:ktor-server-netty:$ktor_version"

implementation("io.ktor:ktor-server-netty:$ktor_version")

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-server-netty</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Choose how to create a server

A Ktor server application can be created and run in two ways: using the embeddedServer to quickly pass server parameters in code, or using EngineMain to load the configuration from the external application.conf file.

embeddedServer

The embeddedServer function accepts an engine factory used to create an engine of a specific type. In the example below, we pass the Netty factory to run a server with the Netty engine and listen on the 8080 port:

package com.example

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

fun main() {
    embeddedServer(Netty, port = 8080) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

EngineMain

EngineMain represents an engine for running a server. You can use the following engines:

io.ktor.server.netty.EngineMain
io.ktor.server.jetty.EngineMain
io.ktor.server.tomcat.EngineMain
io.ktor.server.cio.EngineMain

The EngineMain.main function is used to start a server with the selected engine and loads the application module specified in the external application.conf file. In the example below, we start a server from the application's main function:

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

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

If you need to start a server using a build system task, you need to configure the required EngineMain as the main class:

mainClassName = "io.ktor.server.netty.EngineMain"

application {
mainClassName = "io.ktor.server.netty.EngineMain"
}

<properties>
<main.class>io.ktor.server.netty.EngineMain</main.class>
</properties>

Configure an engine

In this section, we'll take a look how to specify various engine-specific options.

embeddedServer

The embeddedServer function allows you to pass engine-specific options using the configure optional parameter. This parameter includes options common for all engines and exposed by the ApplicationEngine.Configuration class.

fun main() {
    embeddedServer(Netty, port = 8080, configure = {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
    }) {
        // ...
    }.start(wait = true)
}

In addition to these options, you can configure additional engine-specific properties.

Netty

Netty-specific options are exposed by the NettyApplicationEngine.Configuration class.

embeddedServer(Netty, configure = {
    requestQueueLimit = 16
    shareWorkGroup = false
    configureBootstrap = {
        // ...
    }
    responseWriteTimeoutSeconds = 10 
}) {
    // ...
}.start(true)

Jetty

If you use Jetty as the engine, you can configure the Jetty server inside the configureServer block, which provides access to a Server instance.

embeddedServer(Jetty, configure = {
    configureServer = { // this: Server ->
        // ...
    } 
}) {
    // ...
}.start(true)

CIO

CIO-specific options are exposed by the CIOApplicationEngine.Configuration class.

embeddedServer(CIO, configure = {
    connectionIdleTimeoutSeconds = 45
}) {
    // ...
}.start(true)

Tomcat

If you use Tomcat as the engine, you can configure it using the configureTomcat property, which provides access to a Tomcat instance.

embeddedServer(Tomcat, configure = {
    configureTomcat = { // this: Tomcat ->
        // ...
    }
}) {
    // ...
}.start(true)

EngineMain

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

ktor {
    deployment {
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
    }
}

Last modified: 06 September 2021