WAR

You can run a Ktor application inside a servlet container, such as Tomcat or Jetty. To do this, you need to package your application as a WAR archive and deploy it to a server or a cloud service that supports WAR deployment.

In this topic, you'll learn how to:

Configure Ktor for use in a servlet application.
Apply the Gretty and War plugins to run and package WAR applications.
Run a Ktor application in a servlet container.
Generate and deploy a WAR archive.

Configure Ktor in a servlet application

Ktor allows you to create and start a server using a specific engine (such as Netty, Jetty, or Tomcat) directly in your application. In this setup, your application controls engine configuration, connections, and SSL settings.

When deploying to a servlet container, the container controls the application lifecycle and connection configuration. For this, Ktor provides the ServletApplicationEngine engine, which delegates control of your application to the servlet container.

Add dependencies

To use Ktor in a servlet application, add the ktor-server-servlet-jakarta artifact to your build script:

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

implementation "io.ktor:ktor-server-servlet-jakarta:$ktor_version"

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

You do not need to add separate Jetty or Tomcat engine dependencies when deploying to a servlet container.

Configure a servlet

To register a Ktor servlet in your application, open the WEB-INF/web.xml file and assign ServletApplicationEngine to the servlet-class attribute:

    <servlet>
        <display-name>KtorServlet</display-name>
        <servlet-name>KtorServlet</servlet-name>
        <servlet-class>io.ktor.server.servlet.jakarta.ServletApplicationEngine</servlet-class>
        <init-param>
            <param-name>io.ktor.ktor.config</param-name>
            <param-value>application.conf</param-value>
        </init-param>
        <async-supported>true</async-supported>
    </servlet>

<servlet>
    <display-name>KtorServlet</display-name>
    <servlet-name>KtorServlet</servlet-name>
    <servlet-class>io.ktor.server.servlet.ServletApplicationEngine</servlet-class>
    <init-param>
        <param-name>io.ktor.ktor.config</param-name>
        <param-value>application.conf</param-value>
    </init-param>
    <async-supported>true</async-supported>
</servlet>

Then, configure the URL pattern for this servlet:

    <servlet-mapping>
        <servlet-name>KtorServlet</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

Configure the Gretty plugin

The Gretty plugin allows you to run a servlet application on Jetty and Tomcat.

To apply the plugin, open your build.gradle.kts file and add the following entry to the plugins block:

plugins {
    id("org.gretty") version "5.0.1"
}

Then, you can configure it in the gretty block as follows:

gretty {
    servletContainer = "jetty12"
    contextPath = "/"
}

gretty {
    servletContainer = "tomcat10"
    contextPath = "/"
}

Finally, configure the run task:

afterEvaluate {
    tasks.getByName("run") {
        dependsOn("appRun")
    }
}

Configure the War plugin

The War plugin allows you to generate a WAR archive for deployment to a servlet container.

To apply the plugin, open your build.gradle.kts file and add the following entry to the plugins block :

plugins {
    id("war")
}

Run the application

You can run a servlet application with the configured Gretty plugin by using the run task. For example, to run the jetty-war sample project, run the following command:

./gradlew :jetty-war:run

Generate and deploy a WAR archive

To generate a WAR archive using the War plugin, run the war task. For the jetty-war sample project, the command looks as follows:

./gradlew :jetty-war:war

After the task completes, the jetty-war.war is available in the build/libs directory of the corresponding module.

To deploy the generated archive, copy the file to the jetty/webapps directory in your servlet container.

The following Dockerfile example shows how to run the generated WAR file inside a Jetty or Tomcat servlet container:

FROM jetty:12.0.29
EXPOSE 8080:8080
COPY ./build/libs/jetty-war.war/ /var/lib/jetty/webapps
WORKDIR /var/lib/jetty
CMD ["java","-jar","/usr/local/jetty/start.jar"]

FROM tomcat:10.1.50
EXPOSE 8080:8080
COPY ./build/libs/tomcat-war.war/ /usr/local/tomcat/webapps
WORKDIR /usr/local/tomcat
CMD ["catalina.sh", "run"]

For the complete examples, see jetty-war and tomcat-war.

25 February 2026