Ktor 3.0.0-rc-1 Help

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.application.* import io.ktor.server.response.* import io.ktor.server.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) }

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