Ktor 2.3.12 Help


In this tutorial, we'll show you how to prepare and deploy a Ktor application to Heroku.


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

  • You have a Heroku account.

  • Heroku CLI is installed on your machine.

Create a sample application

Create a sample application as described in Create, open and run a new Ktor 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:

  • If server configuration is 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. You might need to replace ktor-get-started-sample with you project name.

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: 02 April 2024