heroku.md

Initial project: ktor-get-started-sample

Learn how to prepare and deploy a Ktor application to Heroku.

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 topic.

Prerequisites {id="prerequisites"}

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 {id="clone"}

Clone the ktor-get-started-sample project.

Note that Ktor provides two approaches to create and configure a server: in code or by using the application.conf configuration file. The only difference in deploying is how to specify a port used to listen for incoming requests.

Prepare an application {id="prepare-app"}

Step 1: Configure a port {id="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}
      }
  }
  

  {style="block"}

Step 2: Add a stage task {id="stage"}

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 {id="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

{style="block"}

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 {id="deploy-app"}

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:

   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.
   

   {style="block"}