Docker

In this section we'll see how to deploy a Ktor application to a Docker container which can then be run either locally or on your cloud provider of choice.

Docker is a container system that allows for packaging software in a format that can then be run on any platform that supports Docker, such as Linux, macOS, and Windows. Conceptually Docker is an operating system with layers providing multiple services. While the basics of Docker will be covered, if you're not familiar with it, check out some of the Getting Started documentation.

Getting the application ready

In order to run on Docker, the application needs to have all the required files deployed to the container. As a first step, you need to create a zip file containing the application and its dependencies. Depending on the build system you're using, there are different ways to accomplish this.

The example below will be using Gradle and the application plugin to accomplish this. If using Maven, the same thing can be accomplished using the assembly functionality.

Configure the Gradle file

plugins {
    id 'application'
    id 'org.jetbrains.kotlin.jvm'
}

mainClassName = "io.ktor.server.netty.EngineMain"

repositories {
    mavenCentral()
    maven { url "https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven" }
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    implementation "io.ktor:ktor-server-netty:$ktor_version"
    implementation "io.ktor:ktor-html-builder:$ktor_version"
    implementation "ch.qos.logback:logback-classic:$logback_version"

    testImplementation 'junit:junit:4.13'
    testImplementation 'org.hamcrest:hamcrest:2.2'
    testImplementation project(':e2e')

    testImplementation "io.ktor:ktor-client-core:$ktor_version"
    testImplementation "io.ktor:ktor-client-cio:$ktor_version"
}

ktor {
    deployment {
        port = 8080
    }

    application {
        modules = [ com.example.ApplicationKt.main ]
    }
}

package com.example

import io.ktor.application.*
import io.ktor.features.*
import io.ktor.html.*
import io.ktor.routing.*
import kotlinx.html.*

fun Application.main() {
    install(DefaultHeaders)
    install(CallLogging)
    routing {
        get("/") {
            call.respondHtml {
                head {
                    title { +"Ktor: Docker" }
                }
                body {
                    val runtime = Runtime.getRuntime()
                    p { +"Hello from Ktor Netty engine running in Docker sample application" }
                    p { +"Runtime.getRuntime().availableProcessors(): ${runtime.availableProcessors()}" }
                    p { +"Runtime.getRuntime().freeMemory(): ${runtime.freeMemory()}" }
                    p { +"Runtime.getRuntime().totalMemory(): ${runtime.totalMemory()}" }
                    p { +"Runtime.getRuntime().maxMemory(): ${runtime.maxMemory()}" }
                    p { +"System.getProperty(\"user.name\"): ${System.getProperty("user.name")}" }
                }
            }
        }
    }
}

Prepare Docker image

In the root folder of the project create a file named Dockerfile with the following contents:

FROM openjdk:8-jdk
EXPOSE 8080:8080
RUN mkdir /app
COPY ./build/install/docker/ /app/
WORKDIR /app/bin
CMD ["./docker"]

The Dockerfile indicates a few things:

What image is going to be used (JDK 8 in this case).
The exposed port (this does not automatically expose the port which is done when running the container)
How to run the application (cmd file)

The other steps merely create a folder, copy the contents from the build output to the folder and change to it in preparation to run the image.

Building and running the Docker image

First step is to create the distribution of the application (in this case using Gradle):

./gradlew installDist

Next step is to build and tag the Docker image:

docker build -t my-application .

Finally, start the image:

docker run -p 8080:8080 my-application

For more information about running a docker image please consult docker run documentation.

If using IntelliJ IDEA, you can simply click Run in the Dockerfile to perform these steps.

Last modified: 27 May 2021