WAR

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.

In this topic, we'll show you how to:

configure Ktor to use it in a servlet application;
apply Gretty and War plugins for running and packaging WAR applications;
run a Ktor servlet application;
generate and deploy a WAR archive.

Configure Ktor in a servlet application

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 the approach above, 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.

Add dependencies

To use Ktor in a servlet application, you need to include the ktor-server-servlet-jakarta artifact in the 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>
                    
        

If you use the 9.x or earlier version of Tomcat/Jetty, add the ktor-server-servlet artifact instead.

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 Gretty

The Gretty plugin allows you to run a servlet application on Jetty and Tomcat. To install this plugin, open the build.gradle.kts file and add the following code to the plugins block:

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

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

gretty {
    servletContainer = "jetty11"
    contextPath = "/"
    logbackConfigFile = "src/main/resources/logback.xml"
}

gretty {
    servletContainer = "tomcat10"
    contextPath = "/"
    logbackConfigFile = "src/main/resources/logback.xml"
}

Finally, configure the run task:

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

Configure War

The War plugin allows you to generate WAR archives. You can install it by adding the following line to the plugins block in your build.gradle.kts file:

plugins {
    id("war")
}

Run an application

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

./gradlew :jetty-war:run

Generate and deploy a WAR archive

To generate a WAR file with your application using the War plugin, execute the war task. For the jetty-war example, a command looks as follows:

./gradlew :jetty-war:war

The jetty-war.war is created in the build/libs directory. You can deploy the generated archive inside a servlet container by copying it to the jetty/webapps directory. For instance, a Dockerfile below shows how to run the created WAR inside a Jetty or Tomcat servlet container:

FROM jetty:11.0.22
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.20
EXPOSE 8080:8080
COPY ./build/libs/tomcat-war.war/ /usr/local/tomcat/webapps
WORKDIR /usr/local/tomcat
CMD ["catalina.sh", "run"]

You can find the complete examples here: jetty-war and tomcat-war.

Last modified: 02 April 2024