kora-project-setup-kotlin

Kora Project Setup — Kotlin

Kora sub-skill — obey the kora-v1 meta rules on every task: R0 ensure .kora-agent/ docs+examples are cloned · R1 read this sub-skill before writing code · R2 Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Scaffold a runnable Kotlin Kora service: Gradle Kotlin DSL build, KSP symbol processors, the kora-parent BOM, and a @KoraApp interface that plugs in Kora capabilities by extending *Module interfaces.

Pinned versions (match .kora-agent/kora-examples): Kora BOM 1.2.19, Kotlin 1.9.25, KSP 1.9.25-1.0.20, Gradle 9.5.1, JVM toolchain 21. Never version individual ru.tinkoff.kora:* artifacts — the BOM aligns them all.

---

Core principle

Kora generates code at compile time. For Kotlin this runs through KSP (the com.google.devtools.ksp plugin + the ru.tinkoff.kora:symbol-processors artifact), not Java's annotationProcessor. Without KSP, nothing is generated and the build produces no ApplicationGraph. KSP writes generated sources to build/generated/ksp/main/kotlin — register that directory as a source dir so IDEs and compilation see it.

---

Project structure

my-app/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── gradle/wrapper/gradle-wrapper.properties
├── src/main/
│   ├── kotlin/com/example/Application.kt
│   └── resources/application.conf        # HOCON config
│   └── resources/logback.xml             # logging config
└── src/test/kotlin/com/example/

---

Quick Start

1. settings.gradle.kts

The foojay-resolver-convention plugin lets the Java toolchain auto-download the requested JDK instead of relying only on locally installed ones.

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

rootProject.name = "kora-example"

2. build.gradle.kts

import org.gradle.jvm.toolchain.JavaLanguageVersion
import org.gradle.jvm.toolchain.JvmVendorSpec

plugins {
    id("application")
    kotlin("jvm") version "1.9.25"
    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
}

repositories {
    mavenCentral()
}

// The koraBom configuration carries the BOM and feeds aligned versions into the
// real configurations. ksp needs it separately because it has its own classpath.
val koraBom: Configuration by configurations.creating
configurations {
    ksp.get().extendsFrom(koraBom)
    compileOnly.get().extendsFrom(koraBom)
    implementation.get().extendsFrom(koraBom)
    testImplementation.get().extendsFrom(koraBom)
    kspTest.get().extendsFrom(koraBom)
}

dependencies {
    koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.19"))

    // Mandatory: the Kora symbol processors. Without them nothing is generated.
    ksp("ru.tinkoff.kora:symbol-processors")

    implementation("ru.tinkoff.kora:http-server-undertow")
    implementation("ru.tinkoff.kora:config-hocon")
    implementation("ru.tinkoff.kora:json-module")
    implementation("ru.tinkoff.kora:logging-logback")

    kspTest("ru.tinkoff.kora:symbol-processors")
    testImplementation("ru.tinkoff.kora:test-junit5")
}

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
        vendor.set(JvmVendorSpec.ADOPTIUM)
    }
    sourceSets.main { kotlin.srcDir("build/generated/ksp/main/kotlin") }
    sourceSets.test { kotlin.srcDir("build/generated/ksp/test/kotlin") }
}

application {
    applicationName = "application"
    mainClass.set("com.example.ApplicationKt")
    applicationDefaultJvmArgs = listOf("-Dfile.encoding=UTF-8")
}

tasks.distTar {
    archiveFileName.set("application.tar")
}

tasks.test {
    useJUnitPlatform()
}