# keel

> 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.

Page: https://kotlin.website/keel

## Why it exists

Every Kotlin service starts with the same day of work before it does anything. [keel](https://github.com/youndie/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](https://kotlin.website/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](https://kotlin.website/kore) owns the lifecycle, [sborka](https://kotlin.website/sborka) owns the build, and keel only shows them wired. The
test for every file in it: *did konekt or [katcher](https://kotlin.website/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](https://kotlin.website/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](https://kotlin.website/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

```bash
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.
