Dokku

Dokku is a self-hosted Platform-as-a-Service (PaaS) that runs on your own Linux server and provides a deployment workflow similar to Heroku. While you can deploy a Ktor application by copying a fat JAR to a server manually, Dokku automates the surrounding infrastructure:

Git-based deployments — push your code with git push and Dokku builds and restarts the application automatically, without SSH file copying or manual restarts.
Process management — Dokku starts, stops, and restarts your application automatically, including after server reboots.
Multiple apps on one server — each application runs in an isolated container, preventing port conflicts and interference between apps.
HTTPS — a single command provisions a Let's Encrypt certificate for your app.
Zero-downtime deployments — Dokku waits for the new container to pass a health check before switching traffic away from the old one.

Dokku requires a Linux server to run on. Several hosting providers offer pre-installed Dokku images, so you don't need to set it up manually: DigitalOcean, Hostinger, and HOSTKEY.

Prerequisites

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

You have a Linux server with Dokku installed. You can install it manually or use a hosting provider that offers a pre-installed Dokku image.
Git is installed on your machine.

Prepare an application

Step 1: Configure a port

First, you need to specify a port used to listen for incoming requests. Dokku dynamically assigns a port to each application and passes it using the PORT environment variable. Your application must read this variable at startup, otherwise it may listen on the wrong port and Dokku won't be able to route traffic to it. Depending on how you configure a Ktor server, do one of the following:

If your server configuration is specified in code, read the environment variable using the System.getenv() function and pass it to the port parameter of the embeddedServer() function:
fun main() { embeddedServer(Netty, port = System.getenv("PORT")?.toIntOrNull() ?: 8080) { // ... }.start(wait = true) }
If your server configuration is specified in a configuration file, open your application.conf or application.yaml file placed in src/main/resources and update the port property as shown below:
ktor { deployment { port = 8080 port = ${?PORT} } }
ktor: deployment: port: ${PORT:8080}

Step 2: Add a stage task

Open the build.gradle.kts file and add a custom stage task that Dokku uses to build the application:

tasks {
    register("stage").configure {
        dependsOn("installDist")
    }
}

Step 3: Specify the Java version

Create a system.properties file in the project root to specify the Java version:

java.runtime.version=21

The version must match the JVM toolchain version specified in your build.gradle.kts file. Without this file, Dokku will use the latest available JDK version, which may change over time and cause unexpected build failures.

Step 4: Create a Procfile

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

web: ./build/install/<project-name>/bin/<project-name>

This file tells Dokku how to start the application after it is built by the stage task. Replace <project-name> with your project name. To find your project name, run the following command:

./gradlew properties -q | grep "^name:" | sed 's/name: //'

Deploy an application

To deploy the application to Dokku using Git, open a new terminal window and follow the steps below:

Commit changes made in the previous section locally:
git add . git commit -m "Prepare app for deploying"
Connect to your server and create a Dokku application. Replace <app-name> with a name for your application:
ssh <user>@<your-server> dokku apps:create <app-name>
Add the Dokku server as a Git remote. Replace <your-server> with your server's hostname or IP address, and <app-name> with the name used in the previous step:
git remote add dokku dokku@<your-server>:<app-name>
Push the code to Dokku to trigger a build and deployment:
git push dokku main
Replace main with your branch name if it differs.
If your Ktor application is located in a subdirectory, use git subtree push instead:
git subtree push --prefix=<subdir> dokku main
Wait until Dokku builds and starts the application:
... =====> Application deployed: http://<app-name>.<your-server>
Set a domain or IP address to make the application accessible:
ssh <user>@<your-server> dokku domains:set <app-name> <domain-or-ip>
The application will be available at http://<domain-or-ip>.

18 March 2026