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()
}

Full file: assets/build.gradle.kts.template

3. gradle.properties

org.gradle.java.installations.auto-detect=true
org.gradle.java.installations.auto-download=true
# Kotlin 1.9.25 cannot target every recent JDK exactly; warn instead of fail.
kotlin.jvm.target.validation.mode=warning
org.gradle.jvmargs=-Dfile.encoding=UTF-8
org.gradle.parallel=true
org.gradle.caching=true

4. Application.kt

@KoraApp marks the application graph root. Each Kora capability is added by extending its *Module interface. The ApplicationGraph object is generated by KSP at compile time, so it does not resolve in the IDE until the first build.

package com.example

import ru.tinkoff.kora.application.graph.KoraApplication
import ru.tinkoff.kora.common.KoraApp
import ru.tinkoff.kora.config.hocon.HoconConfigModule
import ru.tinkoff.kora.http.server.undertow.UndertowHttpServerModule
import ru.tinkoff.kora.json.module.JsonModule
import ru.tinkoff.kora.logging.logback.LogbackModule

@KoraApp
interface Application :
    HoconConfigModule,
    JsonModule,
    LogbackModule,
    UndertowHttpServerModule

fun main() {
    KoraApplication.run { ApplicationGraph.graph() }
}

Full file: assets/Application.kt.template

5. A first component

Components are registered with @Component; an HTTP controller adds @HttpController and @HttpRoute. Adapted from .kora-agent/kora-examples/guides/kotlin/kora-kotlin-guide-getting-started-app.

package com.example

import ru.tinkoff.kora.common.Component
import ru.tinkoff.kora.http.common.HttpMethod
import ru.tinkoff.kora.http.common.annotation.HttpRoute
import ru.tinkoff.kora.http.common.body.HttpBody
import ru.tinkoff.kora.http.server.common.HttpServerResponse
import ru.tinkoff.kora.http.server.common.annotation.HttpController

@Component
@HttpController
class HelloController {

    @HttpRoute(method = HttpMethod.GET, path = "/hello")
    fun hello(): HttpServerResponse =
        HttpServerResponse.of(200, HttpBody.plaintext("Hello, Kora!"))
}

6. application.conf (HOCON)

Keep public traffic and metrics/probes on separate ports.

httpServer {
  publicApiHttpPort = 8080
  privateApiHttpPort = 8085
  telemetry.logging.enabled = true
}

logging.level {
  "root": "WARN"
  "ru.tinkoff.kora": "INFO"
}

7. Gradle wrapper

gradle/wrapper/gradle-wrapper.properties:

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Commands

./gradlew classes        # runs KSP; first real validation that the graph builds
./gradlew run            # starts the application
./gradlew clean build    # full build + tests
./gradlew test           # tests

classes is a meaningful check in Kora: it runs the symbol processors, so it verifies not only Kotlin syntax but that the application graph can be assembled.

When to use vs NOT

Common pitfalls

Multi-module / @KoraSubmodule

Most services are a single module. To split across Gradle modules with @KoraSubmodule feature modules aggregated by a @KoraApp app module, see references/multi-module-reference.md.

Assets

Next steps

• kora-project-dependencies — add modules (HTTP, Database, Kafka, ...)
• kora-config-hocon — typed @ConfigSource configuration
• kora-di-compile — compile-time DI patterns
• kora-testing-junit-kotlin — @KoraAppTest component tests

References