youndie@kotlin.website:~/src$ cat keel/README.md

keel

kmp: jvm + native · ktor · template · kore
A template repository for a Kotlin server that ships twice: clone, rename, and there is a service with one route, one table, three probes and /version, built for the JVM and as a native Linux binary from one source, in a 14 MB image. Every number in it was measured.

Why it exists

Every Kotlin service starts with the same day of work before it does anything. keel is that day, done once: clone, rename, ./gradlew run, and there is a service — one route, one table, three probes, a /version, two targets both runnable, one image, every check green on day one.

It is konekt with the domain removed: the wiring a new service needs, and nothing the last one happened to have. It is not a library and publishes nothing, and it is not a framework — kore owns the lifecycle, sborka owns the build, and keel only shows them wired. The test for every file in it: did konekt or katcher need this? If not, it is not in keel.

What is in it

:server one KMP module, jvm() + linuxX64 (+ linuxArm64 behind a property)
one route GET/POST /items, JSON via kotlinx.serialization
one store ItemStore over sqlx4k-sqlite — the Rust driver on native, sqlite-jdbc on the JVM, one implementation
kore probes, /version, and runUntilSignal with announce → drain → release
sborka allocator settings, ktlint, a size budget, the staged binary path
zavarnik a Leyden AOT cache for the JVM distribution, verified on check
the image distroless/cc-debian13 by digest, the binary and nothing beside it, built with no Docker daemon
docs/ a docs-bootstrap tree, passing make check on day one

23 tests run on each of jvm and linuxX64 from one source, both halves pass kore's shutdown oracle, and the two binaries produce no diff after a normaliser written before the first run.

The numbers

Each began as a threshold declared before the first commit.

target measured
clone → /health/ready on both targets, cold machine, toolchain fetch included under 1 h 3 min 48 s, image build not included
image, distroless/cc under 25 MB 13 972 497 bytes
Kotlin, main sources under 500 lines 214
Gradle build logic under 100 lines 87 code lines
the linuxX64 release binary — 9 228 056 bytes, declaring 7 shared libraries

docker images reports 55.4 MB for the same image, counting every platform of the base manifest; a budget checked with the wrong command fails at random, so the method is named next to the number. Going over a budget is the signal that something belongs in sborka or kore instead, and it is filed there rather than fixed here.

Starting a service from it

scripts/rename.sh relay                    # or: scripts/rename.sh webhook-relay com.example.relay

It rewrites every spelling of the name in the code — package, configuration prefix, types, binary, Docker paths, the workflow — and replaces the documentation rather than rewriting it, since keel's describes keel. Then it fails if git grep -il keel still finds anything.

Limitations

  • kore, sborka and razves are not on Maven Central yet, so a clone needs the portfolio's Reposilite in settings.gradle.kts, filtered to io.github.youndie.
  • A static image is not shipped, and not planned: about 4.5 MB of saving on an image already 44 % under budget, against a recipe that pins compiler properties a Kotlin bump can change.