Kora Project Setup Java

Kora Project Setup — Java

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 minimal, compilable Kora service in Java. Kora is a compile-time framework: its annotation processor generates ApplicationGraph, controllers, JSON readers/writers and aspects during compileJava. If the processor is not wired into the Gradle build, nothing is generated and nothing works. This skill gets that wiring right the first time.

BOM version: ru.tinkoff.kora:kora-parent:1.2.19 (declared once; every ru.tinkoff.kora:* artifact inherits it — never version them individually). JDK: 17 minimum, 25 recommended. Gradle: 9+ (wrapper pins 9.5.1).

Quick Start

Smallest build that compiles and runs an HTTP endpoint. Mirrors .kora-agent/kora-examples/guides/java/kora-java-guide-getting-started-app.

build.gradle:

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

plugins {
    id "java"
    id "application"
}

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

repositories {
    mavenCentral()
}

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

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

    // Mandatory: without this nothing is generated.
    annotationProcessor "ru.tinkoff.kora:annotation-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"

    testAnnotationProcessor "ru.tinkoff.kora:annotation-processors"
    testImplementation "ru.tinkoff.kora:test-junit5"
}

application {
    mainClass = "com.example.Application"
}

settings.gradle:

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

rootProject.name = "kora-example"

src/main/java/com/example/Application.java:

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
public interface Application extends
        HoconConfigModule,
        JsonModule,
        LogbackModule,
        UndertowHttpServerModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

ApplicationGraph is generated by the annotation processor from the @KoraApp interface; it appears in build/generated/sources/annotationProcessor/ after the first compile. ApplicationGraph::graph is the entry point passed to KoraApplication.run.

src/main/java/com/example/HelloController.java:

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
public final class HelloController {

    @HttpRoute(method = HttpMethod.GET, path = "/hello")
    public HttpServerResponse hello() {
        return HttpServerResponse.of(200, HttpBody.plaintext("Hello, Kora!"));
    }
}

src/main/resources/application.conf:

httpServer {
  publicApiHttpPort = 8080
  privateApiHttpPort = 8085
}

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

Build and run:

./gradlew clean build   # runs the annotation processor, builds the graph
./gradlew run           # GET http://localhost:8080/hello -> "Hello, Kora!"

Project structure

my-app/
├── build.gradle
├── settings.gradle
├── gradle.properties
├── gradle/wrapper/gradle-wrapper.properties
├── src/main/java/com/example/Application.java
├── src/main/resources/application.conf
├── src/main/resources/logback.xml
└── src/test/java/com/example/

What's in references/ and assets/

When to use vs NOT

Use this skill when:

• Creating a Java Kora service from scratch (build files + @KoraApp root).
• A build fails with "annotation processor did not run", a missing ApplicationGraph, or "Required dependency was not found".
• Choosing the JDK toolchain, the kora-parent BOM version, or the Gradle wrapper for a Kora project.

Do NOT use this skill for:

• Kotlin projects → kora-project-setup-kotlin (uses ksp + symbol-processors, not annotationProcessor).
• Adding HTTP / Database / Kafka / gRPC modules to an existing build → kora-project-dependencies.
• Writing @ConfigSource typed config → kora-config-hocon.
• DI patterns (@Component, @Module, factories) → kora-di-compile.

The four things that must be right

1. koraBom configuration wiring. A custom koraBom configuration holds the platform("ru.tinkoff.kora:kora-parent:1.2.19") and is extended by annotationProcessor, implementation, compileOnly, and the test* configurations. The annotation-processor classpath is separate from the application classpath, so it needs the BOM explicitly — otherwise the processor resolves without a version and fails.

2. annotationProcessor "ru.tinkoff.kora:annotation-processors". This is the single processor that generates the graph, controllers, JSON readers/writers, and aspects. Add testAnnotationProcessor too so @KoraAppTest works.

3. @KoraApp graph root. An interface annotated with @KoraApp that extends the framework *Module interfaces it needs. main calls KoraApplication.run(ApplicationGraph::graph) — the generated ApplicationGraph lives in the same package.

4. Correct imports. @KoraApp is ru.tinkoff.kora.common.KoraApp; KoraApplication is ru.tinkoff.kora.application.graph.KoraApplication; @Component is ru.tinkoff.kora.common.Component.

Core patterns

Modules are interfaces the @KoraApp extends

Framework capabilities ship as *Module interfaces. The graph root pulls them in via extends; each module contributes component factories to the graph.

@KoraApp
public interface Application extends
        HoconConfigModule,        // config-hocon
        JsonModule,               // json-module
        LogbackModule,            // logging-logback
        UndertowHttpServerModule  // http-server-undertow
{ ... }

Each extends must be backed by an implementation "ru.tinkoff.kora:<artifact>" in build.gradle. If a module is on the build path but not extended, its factories are not added to the graph.

Your code joins the graph via @Component

A class annotated with @Component becomes a managed node. Dependencies are declared as constructor parameters — Kora resolves them at compile time.

@Component
@HttpController
public final class HelloController {
    private final GreetingService service;        // resolved from the graph

    public HelloController(GreetingService service) {
        this.service = service;
    }
}

Do not use field injection. Kora wires components only through constructors.

A minimal @KoraAppTest

test-junit5 provides @KoraAppTest, which builds the real graph and injects components into the test via @TestComponent.

import static org.junit.jupiter.api.Assertions.assertNotNull;

import org.junit.jupiter.api.Test;
import ru.tinkoff.kora.test.extension.junit5.KoraAppTest;
import ru.tinkoff.kora.test.extension.junit5.TestComponent;

@KoraAppTest(Application.class)
class ApplicationTest {

    @TestComponent
    private HelloController controller;

    @Test
    void controllerIsWired() {
        assertNotNull(controller);
    }
}

Requires testAnnotationProcessor "ru.tinkoff.kora:annotation-processors" so the test graph is generated. Deeper testing → kora-testing-junit-java.

Common pitfalls

Full diagnosis table: references/troubleshooting-reference.md.

Next steps

• kora-project-dependencies — add HTTP, Database, Kafka, gRPC, S3 modules.
• kora-config-hocon — typed @ConfigSource configuration.
• kora-di-compile — compile-time DI patterns.
• kora-testing-junit-java — @KoraAppTest testing.