QuickStart

Estimated reading time: 5 minutes

Ktor logo

Ktor is a framework to easily build connected applications – web applications, HTTP services, mobile and browser applications. Modern connected applications need to be asynchronous to provide the best experience to users, and Kotlin coroutines provide awesome facilities to do it in an easy and straightforward way.

While not yet entirely there, the goal of Ktor is to provide an end-to-end multiplatform application framework for connected applications. Currently, JVM client and server scenarios are supported, and we are working on bringing server facilities to native environments, and client facilities to native and JavaScript.

Table of contents:

Gradle Setup

This section assumes you have some basic knowledge of Gradle. If you have never used Gradle, gradle.org provides several guides to help you get started.

You can set-up a simple Ktor application using Gradle like this:

Ktor Build with Gradle

Text version:

// build.gradle

group 'Example'
version '1.0-SNAPSHOT'

buildscript {
    ext.kotlin_version = '1.3.0'
    ext.ktor_version = '1.0.0-beta-3'

    repositories {
        mavenCentral()
        maven { url "https://dl.bintray.com/kotlin/kotlin-eap" }
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin: 'java'
apply plugin: 'kotlin'
apply plugin: 'application'

mainClassName = 'MainKt'

sourceCompatibility = 1.8
compileKotlin { kotlinOptions.jvmTarget = "1.8" }
compileTestKotlin { kotlinOptions.jvmTarget = "1.8" }

kotlin { experimental { coroutines "enable" } }

repositories {
    mavenCentral()
    jcenter()
    maven { url "https://dl.bintray.com/kotlin/ktor" }
    maven { url "https://dl.bintray.com/kotlin/kotlin-eap" }
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    compile "io.ktor:ktor-server-netty:$ktor_version"
    compile "ch.qos.logback:logback-classic:1.2.3"
    testCompile group: 'junit', name: 'junit', version: '4.12'
}
// build.gradle.kts

import org.jetbrains.kotlin.gradle.dsl.Coroutines
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

group = "Example"
version = "1.0-SNAPSHOT"

val ktor_version = "1.0.0-beta-3"

plugins {
    application
    kotlin("jvm") version "1.3.0"
}

kotlin.experimental.coroutines = Coroutines.ENABLE

repositories {
    mavenCentral()
    jcenter()
    maven { url = uri("https://dl.bintray.com/kotlin/ktor") }
    maven { url = uri("https://dl.bintray.com/kotlin/kotlin-eap") }
}

java {
    sourceCompatibility = JavaVersion.VERSION_1_8
}

tasks.withType<KotlinCompile>().all {
    kotlinOptions.jvmTarget = "1.8"
}

application {
    mainClassName = "MainKt"
}

dependencies {
    compile(kotlin("stdlib-jdk8"))
    compile("io.ktor:ktor-server-netty:$ktor_version")
    compile("ch.qos.logback:logback-classic:1.2.3")
    testCompile(group = "junit", name = "junit", version = "4.12")
}

Since Ktor is not yet 1.0, we have custom Maven repositories for distributing our early preview artifacts. You have to set up a couple of repositories as shown below, so your tools can find Ktor artifacts and dependencies.

Of course, don’t forget to include the actual artifact! For our quickstart, we are using the ktor-server-netty artifact. That includes Ktor’s core, netty, and the ktor-netty connector as transitive dependencies. You can, of course, include any additional dependencies that you need.

Since Ktor is designed to be modular, you will require additional artifacts and potentially other repositories for specific features. You can find the required artifacts (and repositories where required) for each feature in the specific feature documentation.

Hello World

A simple hello world in Ktor looks like this:

Ktor Hello World

  1. Here you define a plain callable main method.
  2. Then you create an embedded server using Netty as the back-end that will listen on port 8080.
  3. Installs the routing feature with a block where you can define routes for specific paths and HTTP methods.
  4. Actual routes: In this case, it will handle a GET request for the path /demo, and will reply with a HELLO WORLD! message.
  5. Actually start the server and wait for connections.

Text version:

import io.ktor.application.*
import io.ktor.http.*
import io.ktor.response.*
import io.ktor.routing.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*

fun main(args: Array<String>) {
    val server = embeddedServer(Netty, port = 8080) {
        routing {
            get("/") {
                call.respondText("Hello World!", ContentType.Text.Plain)
            }
            get("/demo") {
                call.respondText("HELLO WORLD!")
            }
        }
    }
    server.start(wait = true)
}

Accessing your application

Since you have a main method, you can execute it with your IDE. That will open a HTTP server, listening on http://127.0.0.1:8080, You can try opening it with your favorite web browser.

If that doesn’t work, maybe you are using that port already. You can try changing the port 8080 (in line 10) and adjust it as needed.

Ktor Hello World Browser

At this point you should have a very simple Web Back-end running, so you can make changes, and see the results in your browser.

Since you have configured a Gradle project with the application plugin and the mainClassName, you can also run it from a terminal using ./gradlew run on Linux/Mac, or gradlew run on a Windows machine.

Walkthroughs