Creating a server

Before creating a Ktor application, you need to take into account how your application will be deployed:

As a self-contained package
In this case, an application engine used to process network requests should be a part of your application. Your application has control over engine settings, connection, and SSL options.
As a servlet
In this case, a Ktor application can be deployed inside a servlet container (such as Tomcat or Jetty), which controls the application lifecycle and connection settings.

Self-contained package

To deliver a Ktor server application as a self-contained package, you need to create a server first. Server configuration can include different settings: a server engine (such as Netty, Jetty, etc.), various engine-specific options, host and port values, and so on. There are two main approaches in Ktor for creating and running a server:

The embeddedServer function is a simple way to configure server parameters in code and quickly run an application.
EngineMain provides more flexibility to configure a server. You can specify server parameters in a file and 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.

Configuration in code

The embeddedServer function is a simple way to configure server parameters in code and quickly run an application. In the code snippet below, it accepts an engine and port as parameters to start a server. In the example below, we run a server with the Netty engine and listen on the 8080 port:

package com.example

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

/*
   Important: The contents of this file are referenced by line number in `server-configuration-code.topic`,
   `server-engines.md` and `migrating-3.md`. If you add, remove, or modify any lines, ensure you update the corresponding
    line numbers in the `code-block` element of the referenced file.
*/
fun main(args: Array<String>) {
    if (args.isEmpty()) {
        println("Running basic server...")
        println("Provide the 'configured' argument to run a configured server.")
        runBasicServer()
    }

    when (args[0]) {
        "basic" -> runBasicServer()
        "configured" -> runConfiguredServer()
        else -> runServerWithCommandLineConfig(args)
    }
}

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

fun runConfiguredServer() {
    embeddedServer(Netty, configure = {
        connectors.add(EngineConnectorBuilder().apply {
            host = "127.0.0.1"
            port = 8080
        })
        connectionGroupSize = 2
        workerGroupSize = 5
        callGroupSize = 10
        shutdownGracePeriod = 2000
        shutdownTimeout = 3000
    }) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

fun runServerWithCommandLineConfig(args: Array<String>) {
    embeddedServer(
        factory = Netty,
        configure = {
            val cliConfig = CommandLineConfig(args)
            takeFrom(cliConfig.engineConfig)
            loadCommonConfiguration(cliConfig.rootConfig.environment.config)
        }
    ) {
        routing {
            get("/") {
                call.respondText("Hello, world!")
            }
        }
    }.start(wait = true)
}

You can find the full example here: embedded-server.

Configuration in a file

EngineMain starts a server with the selected engine and loads the application modules specified in the external configuration file placed in the resources directory: application.conf or application.yaml. Besides modules to load, a configuration file can include various server parameters (the 8080 port in the example 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!")
        }
    }
}

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

ktor:
    deployment:
        port: 8080
    application:
        modules:
            - com.example.ApplicationKt.module

You can find the full examples here: engine-main and engine-main-yaml.

Servlet

A Ktor application can be run and deployed inside servlet containers that include Tomcat and Jetty. To deploy inside a servlet container, you need to generate a WAR archive and then deploy it to a server or a cloud service that supports WARs.

Last modified: 02 April 2024