Deploying a Ktor Fat Jar to Heroku with Shadow Library and Gradle

Chris Basinger
Apr 24 · 3 min read

Hello. I just finished deploying a Ktor REST API & web app to Heroku for a company. There were a few gotchas that I ran into along the way especially with other information I found online. So, I would like to assist you in your deployment process.

  1. Put this in your buildscript under dependencies in your project’s build.gradle file.
classpath 'com.github.jengelman.gradle.plugins:shadow:6.1.0'

2. Add this to your plugins inside your build.gradle file.

apply plugin: 'com.github.johnrengelman.shadow'

3. Add shadow jar config to build.gradle anywhere outside the buildScript. The mainClassName is a variable that is set in your build.gradle file. It should be below the group and version properties. Take note of this version as it will be appended to your jar file.

shadowJar {
manifest {
attributes 'Main-Class': mainClassName

4. I’m using Netty and they have a class that calls the main method from within the Application class. This should be auto generated whenever you generate a new Ktor project. (2021 for me)

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

5. Create file named Procfile at the top level of your project folder and add the following. The name of the jar file needs to match the root.project property found inside your settings.gradle file. You also need to append the version to match the one set in your build.gradle which is right below the group property. Shadow will append a ‘-all’ to the end of the generated jar file. Make sure to add this. 0.0.1 is the default version created in Ktor gradle project.

web: java -jar build/libs/appname-0.0.1-all.jar

6. Create a file at the top level of your project named and set it to your version of Java. As of this writing the most recent version of Kotlin uses java version 1.8


7. Create a file at the top level of your project named app.json. If you’re using post-gresql or anything like that which Heroku would need to know about you need to list it here. See the second example for this.

"name": "My Telematics Ktor Server",
"description": "My telematics app.",
"image": "heroku/java"
//do this one if you need to use an addon{
"name": "My Telematics Ktor Server",
"description": "My telematics app.",
"image": "heroku/java"
"addons": [ "heroku-postgresql" ]

8. Create a file at the top level of the project named .env and make sure you set the PORT property to the same value you set in your application.config file. 8080 is the default for Ktor applications.


9. Install the Heroku command line application. There’s a link below for Windows and Mac users as well as the Debian/Ubuntu commands.

//Windows & Mac
sudo apt-get update && sudo apt-get install heroku
sudo snap install --classic heroku

10. Create a git repository and commit your project files by navigating to your project folder in the terminal and then typing

git init
git add .
git commit -m "init commit"

11. Navigate to your project folder in the terminal and enter this command to create your project

heroku create

12. Navigate to your project folder in the terminal and tell Heroku to use the shadowjar gradle task that Shadow library generated for you.

heroku config:set GRADLE_TASK="shadowJar"

13. Now within your project folder from the terminal you need to push app to the server with git

git push heroku master

14. Now open your app in the terminal with this command. It should be live. Congratulatons!

heroku open