Running

When running a Ktor server application, take into account the following specifics:

The way used to create a server affects whether you can override server parameters by passing command-line arguments when running a packaged Ktor application.
Gradle/Maven build scripts should specify the main class name when starting a server using EngineMain.
Running your application inside a servlet container requires a specific servlet configuration.

In this topic, we'll take a look at these configuration specifics and show you how to run a Ktor application in IntelliJ IDEA and as a packaged application.

Configuration specifics

Configuration: code vs configuration file

Running a Ktor application depends on the way you used to create a server - embeddedServer or EngineMain:

For embeddedServer, server parameters (such as a host address and port) are configured in code, so you cannot change these parameters when running an application.
For EngineMain, Ktor loads its configuration from an external file that uses the HOCON or YAML format. Using this approach, you can run a packaged application from a command line and override the required server parameters by passing corresponding command-line arguments.

Starting EngineMain: Gradle and Maven specifics

If you use EngineMain to create a server, you need to specify the main function for starting a server with the desired engine. The example below demonstrates the main function used to run a server with the Netty engine:

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

To run a Ktor server using Gradle/Maven without configuring the engine inside the main function, you need to specify the main class name in the build script as follows:

application {
    mainClass.set("io.ktor.server.netty.EngineMain")
}

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

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

WAR specifics

Ktor allows you to create and start a server with the desired engine (such as Netty, Jetty, or Tomcat) right in the application. In this case, your application has control over engine settings, connection, and SSL options.

In contrast to this approach, a servlet container should control the application lifecycle and connection settings. Ktor provides a special ServletApplicationEngine engine that delegates control over your application to a servlet container. You can learn how to configure your application from Configure War.

Run an application

Run an application using Gradle/Maven

To run a Ktor application using Gradle or Maven, use the corresponding plugins:

Application plugin for Gradle. For the Native server, use the Kotlin Multiplatform plugin.
Exec plugin for Maven.

Run a packaged application

Before deploying your application, you need to package it in one of the ways described in the Packaging section. Running a Ktor application from the resulting package depends on the package type and might look as follows:

To run a Ktor server packaged in a fat JAR with and override the configured port, execute the following command:
java -jar sample-app.jar -port=8080
To run an application packaged using the Gradle Application plugin, run a corresponding executable:
./ktor-sample
ktor-sample.bat
To run a servlet Ktor application, use the run task of the Gretty plugin.

Last modified: 02 April 2024