Create, open and run a new Ktor project

1. Navigate to the Ktor Project Generator.

2. In the Project artifact field, enter com.example.ktor-sample-app as the name of your project artifact.

   

3. Click Configure to open the settings dropdown menu:

   

   The following settings are available:

   • Build System: Choose the desired build system. This can be Gradle with Kotlin or Groovy DSL, or Maven.

   • Ktor version: Choose the required Ktor version.

   • Engine: Select an engine used to run a server.

   • Configuration: Choose whether to specify server parameters in a YAML or HOCON file, or in code.

   • Include samples: Leave this option enabled to add sample code for plugins.

   For this tutorial you can leave the default values for these settings.

4. Click Done to save the configuration and close the menu.

5. Below you will find a set of plugins that you can add to your project. Plugins are building blocks that provide common functionality in a Ktor application, such as authentication, serialization and content encoding, compression, cookie support, and more.

   For the sake of this tutorial, no plugins need to be added to the project at this stage.

6. Click the Download button to generate and download your Ktor project.

   

Your download should start automatically.

To run the project from within IntelliJ IDEA:

1. Open the Gradle tool window by clicking the Gradle icon () on the right sidebar.

   

2. Within this tool window navigate to Tasks | application and double-click on the run task.

   

3. Your Ktor application will start in the Run tool window at the bottom of the IDE:

   

   The same messages that were previously displayed on the command line will now be visible in the Run tool window.

4. To confirm the project is running, open your browser at the specified URL (http://0.0.0.0:8080).

   You should once again see the message "Hello World!" displayed on the screen:

   

1. Open the Application.kt file. You should find code similar to the following:

   fun main() { embeddedServer( Netty, port = 8080, // This is the port on which Ktor is listening host = "0.0.0.0", module = Application::module ).start(wait = true) } fun Application.module() { configureRouting() }

2. In the embeddedServer() function, change the port parameter to another number of your choosing, such as "9292".

   fun main() { embeddedServer( Netty, port = 9292, host = "0.0.0.0", module = Application::module ).start(wait = true) }

3. Click on the rerun button () to restart the application.

4. To verify that your application is running under the new port number, you can open your browser at the new URL (http://0.0.0.0:9292), or create a new HTTP Request file in IntelliJ IDEA:

   

1. Open the Application.kt file and find the configureRouting() function.

2. In intelliJ IDEA, navigate to the configureRouting() function by placing the caret over the function name and pressing ⌘Cmd+C.

   Alternatively, you can navigate to the function by opening the Routing.kt file.

   This is the code you should see:

   fun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } } }

3. To create a new endpoint, insert the additional five lines of code shown below:

   fun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } get("/test1") { val text = "<h1>Hello From Ktor</h1>" val type = ContentType.parse("text/html") call.respondText(text, type) } } }

   Note that you can change the /test1 URL to be whatever you like.

4. In order to make use of ContentType, add the following import:

   import io.ktor.http.*

5. Click on the rerun button () to restart the application.

6. Request the new URL in the browser (http://0.0.0.0:9292/test1). The port number you should use will depend on whether you have attempted the first task (Changing the default port). You should see the output displayed below:

   

   If you have created an HTTP Request File you can also verify the new endpoint there:

   

   Note that a line containing three hashes (###) is needed to separate different requests.

1. Open the Routing.kt file.

   Once again this should be the default content:

   fun Application.configureRouting() { routing { get("/") { call.respondText("Hello World!") } }

   For this task it does not matter whether you have inserted the content for the extra endpoint specified in Adding a new HTTP endpoint.

2. Add the following line to the routing section:

   fun Application.configureRouting() { routing { // Add the line below staticResources("/content", "mycontent") get("/") { call.respondText("Hello World!") } }

   The meaning of this line is as follows:

   • Invoking staticResources() tells Ktor that we want our application to be able to provide standard website content, such as HTML and JavaScript files. Although this content may be executed within the browser, it is considered static from the server's point of view.

   • The URL /content specifies the path that should be used to fetch this content.

   • The path mycontent is the name of the folder within which the static content will live. Ktor will look for this folder within the resources directory.

3. Add the following import:

   import io.ktor.server.http.content.*

4. In the Project tool window, right-click the src/main/resources folder and select New | Directory.

   Alternatively, select the src/main/resources folder, press ⌘Сmd+N, and click Directory.

5. Name the new directory mycontent and press ↩Enter.

6. Right-click on the newly created folder and click New | File.

7. Name the new file "sample.html" and press ↩Enter.

8. Populate the newly created file page with valid HTML, for example:

   <html lang="en"> <head> <meta charset="UTF-8" /> <title>My sample</title> </head> <body> <h1>This page is built with:</h1> <ol> <li>Ktor</li> <li>Kotlin</li> <li>HTML</li> </ol> </body> </html>

9. Click on the rerun button () to restart the application.

10. When you open your browser at http://0.0.0.0:9292/content/sample.html the content of your sample page should be displayed:

    

1. Create a new directory under src called "test" and a subdirectory called "kotlin".

2. Create a new package inside src/test/kotlin called "com.example".

3. Within src/test/kotlin/com.example create a new file called "ApplicationTest.kt".

4. Open the ApplicationTest.kt file and add the code below:

   class ApplicationTest { @Test fun testRoot() = testApplication { application { module() } val response = client.get("/") assertEquals(HttpStatusCode.OK, response.status) assertEquals("Hello World!", response.bodyAsText()) } }

   The testApplication() method creates a new instance of Ktor. This instance is running inside a test environment, as opposed to a server such as Netty.

   You can then use the application() method to invoke the same setup that is called from embeddedServer().

   Finally, you can use the built-in client object and JUnit assertions to send a sample request and check the response.

5. Add the following required imports:

   import io.ktor.client.request.* import io.ktor.client.statement.* import io.ktor.http.* import io.ktor.server.testing.* import org.junit.Assert.assertEquals import org.junit.Test

Add a new dependency

In the Project tool window, navigate to the src/test/kotlin folder and follow the steps:

1. Open the build.gradle.kts file.

2. In the dependencies section add the extra dependency as shown below:

   dependencies { // The new dependency to be added implementation("io.ktor:ktor-server-status-pages:$ktor_version") // The existing dependencies implementation("io.ktor:ktor-server-core-jvm:$ktor_version") implementation("io.ktor:ktor-server-netty-jvm:$ktor_version") implementation("ch.qos.logback:logback-classic:$logback_version") testImplementation("io.ktor:ktor-server-tests-jvm:$ktor_version") testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version") }

   When you have done this you will need to reload the project to pick up this new dependency.

3. Reload the project by pressing Shift+⌘Cmd+I on macOS or Ctrl+Shift+O on Windows.

Install the plugin and specify an exception handler

1. Navigate to the configureRouting() method in Routing.kt and add the following lines of code:

   fun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { get("/") { call.respondText("Hello World!") } } }

   These lines install the StatusPages plugin and specify what actions to take when an exception of type IllegalStateException is thrown.

2. Add the following import:

   import io.ktor.server.plugins.statuspages.*

Write sample code to trigger the handler

• Staying within the configureRouting() method, add the additional lines as shown below:

  fun Application.configureRouting() { install(StatusPages) { exception<IllegalStateException> { call, cause -> call.respondText("App in illegal state as ${cause.message}") } } routing { get("/") { call.respondText("Hello World!") } get("/error-test") { throw IllegalStateException("Too Busy") } } }

  You have now added an endpoint with the URL /error-test. When this endpoint is triggered, an exception will be thrown with the type used in the handler.

Restart and invoke the sample code

1. Click on the rerun button () to restart the application.

2. In your browser, navigate to the URL http://0.0.0.0:9292/error-test. You should see the error message displayed as shown below: