Installation

This guide gets your build ready to use StoatFlow: wire up the private Maven repository with your credentials, add the dependency, and configure the JVM toolchain. Then configure your license and build your first app.

Prerequisites

• JDK 25 or newer. StoatFlow uses JDK preview features (virtual threads, structured concurrency), so a 25+ toolchain is mandatory — not just for building, but at runtime.
• Apache Kafka 4.x, reachable from where you run the app. For local development the quickest option is a single-node KRaft broker via Docker (localhost:9092).
• Your onboarding email. It contains your read-only Maven token (username customer-<your-slug> + secret) and your license key. Don't have one yet? Get in touch.

1. Register the private Maven repository

StoatFlow artifacts are served from a private, authenticated repository at https://maven.stoatflow.io/releases. You can wire it up two ways — directly on each developer machine (below), or once through your corporate artifact manager.

Store your credentials

# ~/.gradle/gradle.properties   — your HOME dir, never committed
stoatflowRepoUser=customer-your-slug
stoatflowRepoToken=PASTE_YOUR_MAVEN_TOKEN_FROM_THE_ONBOARDING_EMAIL

<!-- ~/.m2/settings.xml   — your HOME dir, never committed -->
<settings>
  <servers>
    <server>
      <id>stoatflow-releases</id>
      <username>customer-your-slug</username>
      <password>PASTE_YOUR_MAVEN_TOKEN_FROM_THE_ONBOARDING_EMAIL</password>
    </server>
  </servers>
</settings>

Point your build at the repository

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven {
            url = uri("https://maven.stoatflow.io/releases")
            credentials {
                username = providers.gradleProperty("stoatflowRepoUser").get()
                password = providers.gradleProperty("stoatflowRepoToken").get()
            }
        }
    }
}

<!-- pom.xml -->
<repositories>
  <repository>
    <id>stoatflow-releases</id>
    <url>https://maven.stoatflow.io/releases</url>
    <releases><enabled>true</enabled></releases>
  </repository>
</repositories>

The <id> in pom.xml must match the <server><id> in settings.xml — that's how Maven applies your credentials.

2. Add the dependency

Most applications want stoatflow-runtime — the batteries-included wrapper (YAML config, HTTP admin + health endpoints, Prometheus metrics, graceful shutdown). It transitively pulls in stoatflow-core, so it's the only dependency you need. If you want just the DSL and engine with no runtime scaffolding, depend on stoatflow-core instead.

// build.gradle.kts
dependencies {
    implementation("io.stoatflow:stoatflow-runtime:<stoatflow-version>")
    // ...or DSL only:
    // implementation("io.stoatflow:stoatflow-core:<stoatflow-version>")

    // In-memory topology testing (no broker required):
    testImplementation("io.stoatflow:stoatflow-test-utils:<stoatflow-version>")
}

<!-- pom.xml -->
<dependencies>
  <dependency>
    <groupId>io.stoatflow</groupId>
    <artifactId>stoatflow-runtime</artifactId>
    <version>${stoatflow.version}</version>
  </dependency>
  <!-- In-memory topology testing (no broker required): -->
  <dependency>
    <groupId>io.stoatflow</groupId>
    <artifactId>stoatflow-test-utils</artifactId>
    <version>${stoatflow.version}</version>
    <scope>test</scope>
  </dependency>
</dependencies>

3. Configure the JVM toolchain

StoatFlow needs a JDK 25 toolchain and two JVM flags at both compile and run time:

• --enable-preview — StoatFlow is built on JDK preview features.
• --enable-native-access=ALL-UNNAMED — RocksDB's state store uses the Foreign Function & Memory API.
• -XX:+UseG1GC keeps GC pauses short and predictable — which matters for stream processing, where a long stop-the-world pause stalls commit barriers and inflates end-to-end latency. The JVM only auto-selects G1 on "server-class" hardware (≥ 2 CPUs and ≥ ~2 GB of memory), falling back to the single-threaded Serial collector below that — so set it explicitly to get consistent pause behaviour even on a single core or a small container. (The StoatFlow build conventions already apply this flag to the local run task and to the Docker image they build.)

Option A — the StoatFlow build conventions (recommended)

StoatFlow ships build conventions for both Gradle and Maven — the JDK 25 toolchain, the preview + native-access JVM args (compile, test, and run), and a runnable fat JAR — so you don't hand-maintain any of it. This page covers just the toolchain setup; the full walkthrough (container images, native image, every knob) is in Project setup.

Gradle — the io.stoatflow plugin

Add a pluginManagement repository for the plugin marker in settings.gradle.kts:

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        maven {
            url = uri("https://maven.stoatflow.io/releases")
            credentials {
                username = providers.gradleProperty("stoatflowRepoUser").get()
                password = providers.gradleProperty("stoatflowRepoToken").get()
            }
        }
    }
}

Then apply it in build.gradle.kts:

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.4.0"   // omit for a Java-only project
    id("io.stoatflow") version "<stoatflow-version>"
}

stoatflow {
    mainClass.set("com.example.MainKt")  // your application entry point
}

Maven — the stoatflow-parent POM

Inherit from the parent POM; it applies the toolchain, the JVM flags, the fat JAR, and the test split. Your dependency's version comes from the bundled BOM, so you omit it:

<!-- pom.xml -->
<parent>
  <groupId>io.stoatflow</groupId>
  <artifactId>stoatflow-parent</artifactId>
  <version>REPLACE-WITH-CURRENT-RELEASE</version>  <!-- literal — Maven can't resolve a property in <parent> -->
  <relativePath/>
</parent>

<properties>
  <stoatflow.mainClass>com.example.Main</stoatflow.mainClass>
</properties>

See the Maven reference for the BOM, every property, and the container + native builds.

Option B — configure it yourself

If you'd rather not use the plugin, set the toolchain and JVM args directly:

// build.gradle.kts — with the `application` plugin applied
java {
    toolchain { languageVersion = JavaLanguageVersion.of(25) }
}
tasks.withType<JavaCompile> { options.compilerArgs.add("--enable-preview") }

application {
    applicationDefaultJvmArgs = listOf(
        "--enable-preview",
        "--enable-native-access=ALL-UNNAMED",
        "-XX:+UseG1GC",
    )
}

<!-- pom.xml -->
<properties>
  <maven.compiler.release>25</maven.compiler.release>
</properties>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <configuration>
        <compilerArgs><arg>--enable-preview</arg></compilerArgs>
      </configuration>
    </plugin>
  </plugins>
</build>

<!-- Run with: java --enable-preview --enable-native-access=ALL-UNNAMED -XX:+UseG1GC -jar your-app.jar -->

Next steps

• License configuration — every license env var / system property / YAML key, for local development and CI/CD.
• Your first app — build and run a complete word-count app on the runtime.
• Architecture — the single-instance model, lane dispatcher, and commit barriers.
• Stuck? Get in touch — real people read every email during the alpha.