Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Project Setup with Gradle

Set up a Ktor 3 project with Gradle Kotlin DSL: the Ktor plugin, engine and feature dependencies, source layout, and how install { } configuration blocks work.

A Ktor project is a normal Kotlin/JVM Gradle project with a handful of Ktor dependencies. You can generate one at the Ktor project generator website or from IntelliJ IDEA's New Project wizard, but it pays to understand what those tools produce, because you will add and remove dependencies all the time.

This lesson walks through the build files, the folder layout, and the Kotlin idiom (lambdas with receivers) that makes Ktor's install { } configuration blocks work. All Gradle and Ktor code here is read-only; the runnable stand-in reproduces the configuration idiom in plain Kotlin.

The build file

A minimal build.gradle.kts for a Ktor 3 server:

Kotlin
plugins {
    kotlin("jvm") version "2.2.0"
    kotlin("plugin.serialization") version "2.2.0"
    id("io.ktor.plugin") version "3.2.0"
}

group = "com.example"
version = "0.0.1"

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

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.ktor:ktor-server-core")
    implementation("io.ktor:ktor-server-netty")
    implementation("io.ktor:ktor-server-content-negotiation")
    implementation("io.ktor:ktor-serialization-kotlinx-json")
    implementation("ch.qos.logback:logback-classic:1.5.18")

    testImplementation("io.ktor:ktor-server-test-host")
    testImplementation(kotlin("test"))
}

The pieces:

  • io.ktor.plugin is the Ktor Gradle plugin. It manages the Ktor version for you (so the io.ktor: dependencies above have no version number), and adds tasks such as buildFatJar and buildImage that you will use in the deployment chapter.
  • kotlin("plugin.serialization") enables kotlinx.serialization, needed for JSON. See kotlinx.serialization basics.
  • mainClass: io.ktor.server.netty.EngineMain reads application.conf and starts the server. The alternative is your own main() with embeddedServer; the next lessons show both.
  • Dependencies are one artifact per feature. ktor-server-core is the core, ktor-server-netty is the engine. Nothing else comes in by default.
  • Logback is the logging backend. Without a logging dependency Ktor prints a warning and logs nothing useful.

Choosing an engine

Engine Artifact Notes
Netty ktor-server-netty Most popular, high performance, the default choice
CIO ktor-server-cio Pure-Kotlin coroutine engine, light, no native dependencies
Jetty ktor-server-jetty-jakarta Use when you need Jetty features
Tomcat ktor-server-tomcat-jakarta Also for deploying as a WAR to an existing Tomcat

Switching is a one-line dependency change plus the import in main(). Application code (routing, plugins) does not change.

Project layout

TEXT
my-ktor-app/
โ”œโ”€โ”€ build.gradle.kts
โ”œโ”€โ”€ settings.gradle.kts
โ”œโ”€โ”€ gradle.properties
โ””โ”€โ”€ src/
    โ”œโ”€โ”€ main/
    โ”‚   โ”œโ”€โ”€ kotlin/
    โ”‚   โ”‚   โ”œโ”€โ”€ Application.kt        # main + module()
    โ”‚   โ”‚   โ”œโ”€โ”€ Routing.kt            # Application.configureRouting()
    โ”‚   โ”‚   โ””โ”€โ”€ Serialization.kt      # Application.configureSerialization()
    โ”‚   โ””โ”€โ”€ resources/
    โ”‚       โ”œโ”€โ”€ application.conf      # or application.yaml
    โ”‚       โ””โ”€โ”€ logback.xml
    โ””โ”€โ”€ test/
        โ””โ”€โ”€ kotlin/
            โ””โ”€โ”€ ApplicationTest.kt

The convention is one file per concern, each exposing an extension function on Application:

Kotlin
// Application.kt
fun Application.module() {
    configureSerialization()
    configureRouting()
}

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

Because they are extension functions, configureRouting() can use this (the Application) to install plugins and routes, and module() just calls them in order. This keeps Application.kt short even in large apps.

How install { } works: lambdas with receivers

Ktor plugins are configured like this:

Kotlin
install(ContentNegotiation) {
    json()
}
install(CallLogging) {
    level = Level.INFO
}

The block is a lambda with receiver: inside it, this is the plugin's configuration object. level = Level.INFO assigns a property on that object; json() calls a method on it. The stand-in below builds the same idiom from scratch so you can see there is no magic.

Kotlin Stand-in: install(Plugin) { configuration }

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Two Kotlin features carry all of this: the C.() -> Unit parameter type (lambda with receiver) and extension functions (Application.module()).

Running the project

Gradle tasks you will use most:

Command What it does
./gradlew run Compile and start the server
./gradlew test Run the tests
./gradlew buildFatJar Build one runnable JAR with all dependencies
./gradlew buildImage Build a Docker image (Ktor plugin)

With EngineMain, the server reads its port from application.conf. For development, auto-reload watches the compiled classes and reloads the application when they change. You turn it on with ktor.development = true (or the -Dio.ktor.development=true JVM flag).

Add dependencies by Ktor's artifact names (ktor-server-<feature>), and let the Gradle plugin or the version catalog supply the version. Mixing Ktor artifacts of different versions causes confusing NoSuchMethodError crashes at start-up.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the io.ktor.plugin Gradle plugin provide?

    It aligns Ktor dependency versions and adds packaging tasks.
  2. 2. Which dependency is required to actually listen for HTTP connections?

    The core has no network code; the engine (Netty, CIO, Jetty, Tomcat) accepts connections.
  3. 3. In install(CallLogging) { level = Level.INFO }, what is this inside the braces?

    The block is a lambda with receiver whose receiver is the configuration.
  4. 4. Why are functions like configureRouting() declared as extensions on Application?

    It is a convention that splits configuration across files while giving each function access to the Application.

Summary

  • A Ktor project is a Kotlin/JVM Gradle build with the io.ktor.plugin plugin and one artifact per feature.
  • Pick one engine (Netty is the usual default); the rest of your code is engine independent.
  • Organise configuration as extension functions on Application, called from module().
  • install(Plugin) { ... } blocks are lambdas with receivers over the plugin's configuration.
  • ./gradlew run, test and buildFatJar are the daily commands.

Next: Your First Ktor Server