Kora Project Dependencies

Kora Project Dependencies — Module Catalog

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.

BOM: ru.tinkoff.kora:kora-parent (pin the version once; every Kora artifact inherits it) Java: 21+ (examples build on JDK 21) | Kotlin: 1.9.25 | KSP: 1.9.25-1.0.20 | Gradle: 9+

Critical: Always import the kora-parent BOM. It aligns every Kora module to one version and pins transitive libraries (Jackson, OkHttp, Undertow, Micrometer, OpenTelemetry, HikariCP, Kafka client, gRPC, Caffeine, Resilience4j). Never put a version on a ru.tinkoff.kora:* artifact — the BOM does it.

Read this first when:

• Selecting which Kora modules to include in a build
• Setting up the BOM and the koraBom configuration in build.gradle / build.gradle.kts
• Configuring annotation processors (Java) or KSP (Kotlin)
• Resolving "Required dependency not found" or transitive version conflicts
• Scaffolding a new project (see Project Generator below)

NOT when: writing DI code (→ kora-di-compile), HTTP controllers (→ kora-http-server), repositories (→ kora-database-jdbc), or Kafka handlers (→ kora-kafka-consumer).

Quick Start — BOM Setup

Pin the BOM version in gradle.properties and reference it via $koraVersion.

gradle.properties

koraVersion=1.2.19

Java (build.gradle)

The koraBom configuration must feed annotationProcessor, compileOnly, implementation (and api/testImplementation/testAnnotationProcessor if used) via extendsFrom, otherwise the BOM does not apply to the processor classpath.

plugins {
    id "java"
    id "application"
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
        vendor = JvmVendorSpec.ADOPTIUM
    }
}

configurations {
    koraBom
    annotationProcessor.extendsFrom(koraBom)
    compileOnly.extendsFrom(koraBom)
    implementation.extendsFrom(koraBom)
    api.extendsFrom(koraBom)
    testImplementation.extendsFrom(koraBom)
    testAnnotationProcessor.extendsFrom(koraBom)
}

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:$koraVersion")
    annotationProcessor "ru.tinkoff.kora:annotation-processors"

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

    testImplementation "ru.tinkoff.kora:test-junit5"
}

Kotlin (build.gradle.kts)

Kotlin uses the KSP plugin and the symbol-processors artifact instead of annotationProcessor.

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

val koraBom: Configuration by configurations.creating
configurations {
    ksp.get().extendsFrom(koraBom)
    compileOnly.get().extendsFrom(koraBom)
    api.get().extendsFrom(koraBom)
    implementation.get().extendsFrom(koraBom)
}

val koraVersion: String by project
dependencies {
    koraBom(platform("ru.tinkoff.kora:kora-parent:$koraVersion"))
    ksp("ru.tinkoff.kora:symbol-processors")

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

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

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
        vendor.set(JvmVendorSpec.ADOPTIUM)
    }
}

Depth: references/bom-usage-reference.md, references/annotation-processors-reference.md

Project Generator

scripts/generate_project.py scaffolds a compile-ready project (build script, @KoraApp, HOCON config, sample controller/repository/Kafka handlers) for a chosen set of modules.

# List available module keys
python scripts/generate_project.py --list-modules

# Java REST API + PostgreSQL
python scripts/generate_project.py \
  --name my-service --package com.example --lang java \
  --modules http-server,jdbc-postgres,metrics

# Kotlin Kafka service
python scripts/generate_project.py \
  --name kafka-service --package com.example --lang kotlin \
  --modules kafka,metrics

The generator emits real Kora APIs only: @KoraApp from ru.tinkoff.kora.common, @HttpController + @HttpRoute, @Repository + extends JdbcRepository, @KafkaListener/@KafkaPublisher, and a httpServer { ... } / db { ... } HOCON config.

Details: scripts/generate_project.py

Core Modules (almost every service)

Depth: references/core-modules-reference.md

Module Catalog

Artifact names below are the real ones verified against the Kora docs and example apps. Note the group is ru.tinkoff.kora except for experimental modules (S3, Camunda), which use ru.tinkoff.kora.experimental.

HTTP

HTTP-server/client auth (BasicAuth, Bearer, API key) ships inside these artifacts as BasicAuthModule, BearerAuthModule, ApiKeyAuthModule. Authorization is configured in code, not via a separate auth artifact.

Skills: kora-http-server, kora-http-client

Database

JDBC drivers are not in the BOM — version them yourself (see Externally Versioned Dependencies).

Skills: kora-database-jdbc, kora-database-cassandra, kora-database-migration

Messaging (Kafka)

There is a single kafka artifact — there are no separate kafka-producer/kafka-consumer artifacts.

Skills: kora-kafka-producer, kora-kafka-consumer

Telemetry

Probes (ProbesModule, readiness/liveness on the private port) and metrics both require an HTTP server module. There is no standalone probes artifact in the BOM; probes come with the HTTP server.

Skills: kora-telemetry-metrics, kora-telemetry-tracing, kora-telemetry-logging

gRPC

Skills: kora-grpc-server, kora-grpc-client

OpenAPI

Skills: kora-openapi-generator-server, kora-openapi-generator-client, kora-openapi-management

AOP

The @Log / @Mdc logging aspect lives in the logging modules (logging-logback/logging-common), not a separate AOP artifact.

Skills: kora-aop-resilient, kora-aop-caching, kora-aop-scheduling-jdk, kora-aop-scheduling-quartz, kora-aop-validation, kora-aop-logging

Other

MapStruct integration (MapStructModule) uses the upstream org.mapstruct:mapstruct + org.mapstruct:mapstruct-processor artifacts plus the Kora annotation processor; there is no ru.tinkoff.kora:mapper-mapstruct artifact. GraalVM native image is a build-plugin concern (org.graalvm.buildtools.native), not a Kora artifact.

Skill: kora-mapstruct

Testing

Black-box / E2E tests use test-junit5 together with Testcontainers — there is no separate test-blackbox artifact.

Skills: kora-testing-junit-java, kora-testing-junit-kotlin, kora-testing-blackbox

Externally Versioned Dependencies (not in the BOM)

These are not Kora artifacts; pin their versions explicitly.

dependencies {
    // JDBC drivers
    implementation "org.postgresql:postgresql:42.7.7"
    runtimeOnly    "com.mysql:mysql-connector-j:8.3.0"

    // Testing
    testImplementation "ru.tinkoff.kora:test-junit5"
    testImplementation "org.testcontainers:junit-jupiter:1.21.4"
    testImplementation "org.mockito:mockito-core:5.14.2"   // Java mocks
    testImplementation "io.mockk:mockk:1.13.13"            // Kotlin mocks
}

Versions the BOM Owns (do not override)

// WRONG — fights the BOM, can break Kora at runtime
implementation "com.fasterxml.jackson.core:jackson-databind:2.16.0"

// RIGHT — let the BOM pin Jackson
implementation "ru.tinkoff.kora:json-module"

If you truly must change a transitive version, use resolutionStrategy { force "..." } rather than declaring a raw version.

Typical Combinations

REST API (HTTP server + JSON + metrics)

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:$koraVersion")
    annotationProcessor "ru.tinkoff.kora:annotation-processors"

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

JDBC service (PostgreSQL + Flyway)

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:$koraVersion")
    annotationProcessor "ru.tinkoff.kora:annotation-processors"

    implementation "ru.tinkoff.kora:database-jdbc"
    implementation "ru.tinkoff.kora:database-flyway"
    implementation "org.postgresql:postgresql:42.7.7"

    implementation "ru.tinkoff.kora:logging-logback"
    implementation "ru.tinkoff.kora:config-hocon"

    testImplementation "ru.tinkoff.kora:test-junit5"
}

Kafka service (JSON)

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:$koraVersion")
    annotationProcessor "ru.tinkoff.kora:annotation-processors"

    implementation "ru.tinkoff.kora:kafka"
    implementation "ru.tinkoff.kora:json-module"

    implementation "ru.tinkoff.kora:logging-logback"
    implementation "ru.tinkoff.kora:config-hocon"
}

Full multi-module example: assets/build.gradle-full.template

Common Pitfalls

References

See Also

• kora-project-setup-java — Java Gradle scaffolding
• kora-project-setup-kotlin — Kotlin Gradle scaffolding
• kora-di-compile — compile-time DI (@KoraApp, @Component, @Module)
• kora-config-hocon — typed @ConfigSource configuration