Ktor using Kotlin/Native

Overview

This serves as a straightforward example illustrating how Kotlin/Native, Ktor, Docker, Docker Hub and GitHub Actions can work seamlessly together. The ultimate goal is to achieve fully automated creation of a compact Docker image and its versioned transfer to Docker Hub.

‼️Choosing the right runtime:

• Kotlin/Native, with static compilation and limited Java library support, shines for IoT, iOS/mobile, embedded targets, and small tools.
• For larger cloud-native apps, microservices, and serverless, prefer GraalVM Native Image.
• When startup time is less critical, the JVM's JIT and runtime optimizations make it ideal for enterprise systems, monoliths, and other long-running services.

Technologies used

• Kotlin/Native
• Ktor server framework
• Gradle as build tool
• Docker as application container
• Docker Hub as container registry
• GitHub Actions to automate CI/CD workflows (build the Docker application, push to the registry,...)
• Renovate for automatic dependency updates

Requirements

• Local JDK 24 installation to build and run the application without Docker for local debugging
• Local Docker installation to build Docker images from your machine
• Docker Hub account for automatic image upload to the registry
• Installed Renovate GitHub App to support automatic dependency updates
• Platform prerequisites for local native builds (only needed if you build/run outside Docker):
  • macOS: Install Xcode Command Line Tools (xcode-select --install). Apple Silicon and Intel are supported host platforms. See target support below.
  • Linux: Ensure a basic native toolchain is available (clang/llvm, make, and zlib headers). Example (Debian/Ubuntu): sudo apt-get install -y build-essential clang zlib1g-dev. Example (Fedora/RHEL): sudo dnf install -y make clang zlib-devel.
  • Windows: Install MSYS2 and the MinGW-w64 toolchain. Follow https://www.msys2.org/, then install packages: pacman -S --needed mingw-w64-x86_64-clang mingw-w64-x86_64-zlib make. Use the "MSYS2 MinGW x64" shell or ensure the MinGW bin directory is on PATH.
• Cross-compilation note: Building Linux binaries from non-Linux hosts locally can be tricky. Prefer the provided Dockerfile and Buildx targets to produce Linux images (see Makefile and Dockerfile notes below).

Further reading (official docs):

• Kotlin/Native overview: https://kotlinlang.org/docs/native-overview.html
• Supported targets and host platforms: https://kotlinlang.org/docs/native-target-support.html
• Set up and build with Gradle: https://kotlinlang.org/docs/native-using-gradle.html

Restrictions

• No Java 25 support yet because Kotlin Multiplatform is not yet available for Gradle 9.0, and lower Gradle versions do not support Java 25
• Dockerfile is using --platform=linux/amd64 as build host, because build host aarch64 is not supported by Kotlin/Native
• Kotlin/Native does not include a JVM. Therefore, many Java libraries will not work. Only libraries that are explicitly Kotlin Multiplatform or those that can be integrated via C Interop are usable.

Build on your current machine

• Debug: ./gradlew linkDebugExecutableApp
• Release: ./gradlew linkReleaseExecutableApp
• Artifacts: build/bin/app/(debugExecutable|releaseExecutable)/app.kexe (Unix) or app.exe (Windows)

Makefile (build shortcuts)

This project ships with a Makefile to simplify common tasks. Run make to see available targets.

Dockerfile notes

• Multi-stage build: Uses a JVM-based build stage to compile the Kotlin/Native binary and a minimal Alpine runtime stage.
• Security: The runtime now uses a non-root user and only installs minimal runtime libraries (gcompat, libgcc, libstdc++).
• Metadata: Adds OCI image labels (title, description, source, license) for better registry visibility.
• Healthcheck: Uses the app's /health endpoint.
• Best practice: .dockerignore is included to reduce build context size and speed up builds.

In-depth explanation

How to use this example

1. Fork this project to your own GitHub space
2. Add your personal Docker Hub credentials to your repository
3. Change IMAGE_NAME in GitHub Actions to your specific name
4. Activate Renovate in your GitHub repository to support automatically dependency updates. You may have to adapt the file renovate.json to your own needs

Where are the unit tests?

This is a simple illustration that shows the interaction between Kotlin/Native, Ktor, Docker, Docker Hub and GitHub Actions. Although the Dockerfile contains a phase that executes the (non-existent) tests, tests were omitted for the demo due to time constraints.