Ktor 2.1.3 Help


In this tutorial, we'll show you how to prepare and deploy a Ktor application to Heroku. This tutorial uses a Ktor application from the Creating a new Ktor project topic.


Before starting this tutorial, make sure that the following prerequisites are met:

  • You have a Heroku account.

  • Heroku CLI is installed on your machine.

Clone a sample application

Clone the ktor-get-started-sample project.

Prepare an application

Step 1: Configure a port

First, you need to specify a port used to listen for incoming requests. Since Heroku uses the PORT environment variable, you need to configure the application to use a value of this variable. Depending on the way used to configure a Ktor server, do one of the following:

  • For the ktor-get-started-sample project with server configuration specified in code, you can obtain the environment variable value using System.getenv. Open the Application.kt file placed in the src/main/kotlin/com/example folder and change the port parameter value of the embeddedServer function as shown below:

    fun main() { embeddedServer(Netty, port = System.getenv("PORT").toInt()) { // ... }.start(wait = true) }
  • If your server configuration is specified in the application.conf file, you can assign the environment variable to the port parameter by using the ${ENV} syntax. Open the application.conf file placed in src/main/resources and update it as shown below:

    ktor { deployment { port = 8080 port = ${?PORT} } }

Step 2: Add a stage task

Open the build.gradle.kts file and add a custom stage task used by Heroku to make an executable that gets run on Heroku's platform:

tasks { create("stage").dependsOn("installDist") }

Note that the installDist task comes with the Gradle application plugin, which is already added to the sample project.

Step 3: Create a Procfile

Create a Procfile in a project root and add the following content:

web: ./build/install/ktor-get-started-sample/bin/ktor-get-started-sample

This file specifies a path to the application's executable generated by the stage task and allows Heroku to start the application.

Deploy an application

To deploy the application to Heroku using Git, open the terminal and follow the steps below:

  1. Commit changes made in the previous section locally:

    git add . git commit -m "Prepare app for deploying"
  2. Login to Heroku CLI:

    heroku login
  3. Create a Heroku application using the heroku create command. You need to replace ktor-sample-heroku with a name of your application:

    heroku create ktor-sample-heroku

    This command does two things:

    • Creates a new Heroku application, which is available on the web dashboard.

    • Adds a new Git remote called heroku to a local repository.

  4. To deploy the application, push changes to heroku main...

    git push heroku main

    ... and wait until Heroku builds and publishes the application:

    ... remote: https://ktor-sample-heroku.herokuapp.com/ deployed to Heroku remote: remote: Verifying deploy... done.
Last modified: 20 July 2022