Heroku

In this tutorial, we'll show you how to prepare and deploy a Ktor application to Heroku. This tutorial uses a Ktor application created in the Adding Ktor to an existing Gradle project topic.

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

To open a sample application, follow the steps below:

Clone the ktor-gradle-sample project.
Switch a branch from main to one of the following:
git checkout embedded-server # a server is configured in code # or git checkout engine-main # a server is configured in 'application.conf'
These branches demonstrate different approaches to creating and configuring a Ktor server: in code or by using the application.conf configuration file. The only difference in deploying these projects is how to specify a port used to listen for incoming requests.

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 you've chosen the embedded-server branch 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 you've chosen the engine-main branch with server configuration 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 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-gradle-sample/bin/ktor-gradle-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:

Commit changes made in the previous section locally:
git add . git commit -m "Prepare app for deploying"
Login to Heroku CLI:
heroku login
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.
To deploy the application, push changes to heroku main...
git push heroku embedded-server:main # or git push heroku engine-main: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: 13 August 2021