How-to Guides

• 1: Install Jikkou
• 2: Install Jikkou API Server
• 3: Automating
• 3.1: Automate Jikkou with GitHub Actions
• 4: Migration
• 4.1: Migrating to Jikkou 1.0

1 - Install Jikkou

From SDKMan! (recommended)

The latest stable release of jikkou (x86) for Linux, and macOS can be retrieved via SDKMan!:

sdk install jikkou

From The Jikkou Project

Releases

Every release released versions of Jikkou is available:

• As a zip/tar.gz package from GitHub Releases (for Linux, MacOS)
• As a fatJar available from Maven Central
• As a docker image available from Docker Hub.

These are the official ways to get Jikkou releases that you manually downloaded and installed.

Install From Release distribution

1. Download your desired version
2. Unpack it (unzip jikkou-<version>-linux-x86_64.zip)
3. Move the unpacked directory to the desired destination (mv jikkou-<version>-linux-x86_64 /opt/jikkou)
4. Add the executable to your PATH (export PATH=$PATH:/opt/jikkou/bin)

From there, you should be able to run the client: jikkou help.

It is recommended to install the bash/zsh completion script jikkou_completion:

wget https://raw.githubusercontent.com/streamthoughts/jikkou/main/jikkou_completion -O jikkou_completion

or alternatively, run the following command for generation the completion script.

$ source <(jikkou generate-completion)

Using Docker Image

# Create a Jikkou configfile (i.e., jikkouconfig)
cat << EOF >jikkouconfig
{
  "currentContext" : "localhost",
  "localhost" : {
    "configFile" : null,
    "configProps" : {
     "provider.kafka.config.client.bootstrap.servers" : "localhost:9092"
    }
  }
}
EOF

# Run Docker
docker run -it \
--net host \
--mount type=bind,source="$(pwd)"/jikkouconfig,target=/etc/jikkou/config \
streamthoughts/jikkou:latest -V

Development Builds

In addition to releases you can download or install development snapshots of Jikkou.

From Docker Hub

Docker images are built and push to Docker Hub from the latest main branch. They are not official releases, and may not be stable. However, they offer the opportunity to test the cutting edge features.

$ docker run -it streamthoughts/jikkou:main

From Source (Linux, macOS)

Building Jikkou from source is slightly more work, but is the best way to go if you want to test the latest ( pre-release) Jikkou version.

Prerequisites

To build the project you will need:

• Java 25 (i.e. $JAVA_HOME environment variable is configured).
• GraalVM 25.0.2 or newer to create native executable
• TestContainer to run integration tests

Create Native Executable

# Build and run all tests
./mvnw clean verify -Pnative

You can then execute the native executable with: ./jikkou-cli/target/jikkou-$PROJECT_VERSION-runner

Build Debian Package (.deb)

# Build and run all tests
./mvnw clean package -Pnative
./mvnw package -Pdeb

You can then install the package with: sudo dpkg -i ./dist/jikkou-$PROJECT_VERSION-linux-x86_64.deb

NOTE: Jikkou will install itself in the directory : /opt/jikkou

Build RPM Package

# Build and run all tests
./mvnw clean package -Pnative
./mvnw package -Prpm

The RPM package will available in the ./target/rpm/jikkou/RPMS/noarch/ directory.

2 - Install Jikkou API Server

Releases

The latest stable release of Jikkou API Server is available:

• As a Java binary distribution (.zip) from GitHub Releases
• As a docker image available from Docker Hub.

Standalone Installation

Follow these few steps to download the latest stable versions and get started.

Prerequisites

To be able to run Jikkou API Server, the only requirement is to have a working Java 21 installation. You can check the correct installation of Java by issuing the following command:

java -version

Step 1: Download

Download the latest Java binary distribution from the GitHub Releases (e.g. jikkou-api-server-0.36.0.zip)

Unpack the download distribution and move the unpacked directory to a desired destination

unzip jikkou-api-server-$LATEST_VERSION.zip
mv jikkou-api-server-$LATEST_VERSION /opt/jikkou

Step 2: Start the API Server

Launch the application with:

./bin/jikkou-api-server.sh

Step 3: Test the API Server

$ curl -sX GET http://localhost:28082 -H "Accept: application/json" | jq

{
  "version": "0.31.0",
  "build_time": "2023-11-14T18:07:38+0000",
  "commit_id": "dae1be11c092256f36c18c8f1d90f16b0c951716",
  "_links": {
    "self": {
      "href": "/",
      "templated": false
    },
    "get-apis": {
      "href": "/apis",
      "templated": false
    }
  }
}

Step 4: Stop the API Server

PID=`ps -ef | grep -v grep | grep JikkouApiServer | awk '{print $2}'`
kill $PID

Docker

# Run Docker
docker run -it \
--net host \
streamthoughts/jikkou-api-server:latest

Development Builds

In addition to releases you can download or install development snapshots of Jikkou API Server.

From Docker Hub

Docker images are built and push to Docker Hub from the latest main branch.

They are not official releases, and may not be stable. However, they offer the opportunity to test the cutting edge features.

$ docker run -it streamthoughts/jikkou-api-server:main

3 - Automating

3.1 - Automate Jikkou with GitHub Actions

Setup Jikkou

The streamthoughts/setup-jikkou action is a JavaScript action that sets up Jikkou in your GitHub Actions workflow by:

• Downloading a specific version of Jikkou CLI and adding it to the PATH.
• Configuring JIKKOU CLI with a custom configuration file.

After you’ve used the action, subsequent steps in the same job can run arbitrary Jikkou commands using the GitHub Actions run syntax. This allows most Jikkou commands to work exactly like they do on your local command line.

Usage

steps:
  - uses: streamthoughts/setup-jikkou@v1

A specific version of Jikkou CLI can be installed:

steps:
  - uses: streamthoughts/setup-jikkou@v0.1.0
    with:
      jikkou_version: 0.37.0

A custom configuration file can be specified:

steps:
  - uses: streamthoughts/setup-jikkou@v0.1.0
    with:
      jikkou_config: ./config/jikkouconfig.json

Inputs

This Action additionally supports the following inputs :

4 - Migration

4.1 - Migrating to Jikkou 1.0

Jikkou 1.0.0 is a major release. The good news: the project’s first real breaking change — the move from io.streamthoughts.jikkou.* to io.jikkou.* — ships with a runtime deprecation shim, so most existing setups will run unchanged with warnings while you migrate at your own pace.

This guide walks through the upgrade end to end.

Before You Upgrade

A short checklist before you start:

1. Pin your current version. Make sure your CI and any automation reference 0.37.3 (or whichever 0.37.x you run today) explicitly, not latest, so you can roll back fast.
2. Back up your configurations. Commit any uncommitted Jikkou configuration and resource files. The migration is mechanical, but a clean baseline makes review easier.
3. Plan a window. The shim means you don’t need downtime, but if you operate Jikkou as a service (jikkou-api-server), the upgrade is a normal rolling deploy.
4. Read the v1.0.0 release notes. This guide is focused on change recipes; the release notes explain the why.

1. Update Maven / Gradle Coordinates

The Maven group changed from io.streamthoughts to io.jikkou. Artifact names are unchanged.

Maven

<!-- Before -->
<dependency>
  <groupId>io.streamthoughts</groupId>
  <artifactId>jikkou-core</artifactId>
  <version>0.37.3</version>
</dependency>

<!-- After -->
<dependency>
  <groupId>io.jikkou</groupId>
  <artifactId>jikkou-core</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

// Before
implementation("io.streamthoughts:jikkou-core:0.37.3")

// After
implementation("io.jikkou:jikkou-core:1.0.0")

If you depend on multiple Jikkou modules (jikkou-extension-rest-client, individual providers, etc.), update them all in one pass — they all moved together.

2. Rename Java Imports

If you maintain custom extensions, providers, or any Java code that imports Jikkou classes, replace the package prefix:

io.streamthoughts.jikkou.   →   io.jikkou.

With your IDE. Use the project-wide find-and-replace, scoped to *.java files. IntelliJ’s “Refactor → Rename” on the package root handles imports and pom.xml references in one step.

With sed (POSIX-friendly):

# From the repo root
git ls-files '*.java' '*.kt' '*.scala' \
  | xargs sed -i 's|io\.streamthoughts\.jikkou|io.jikkou|g'

Don’t rename your own packages. Only the prefix io.streamthoughts.jikkou.* belonging to Jikkou itself moved.

You don’t have to do this immediately. The runtime keeps resolving old class names through a deprecation shim and logs a warning. This means a staged rollout is safe: upgrade the dependency first, observe warnings in your logs, then schedule the import rename. The shim is scheduled for removal in 1.1.0.

3. Migrate Off Deprecated JikkouApi Overloads

Four JikkouApi overloads that take a raw Configuration have been deprecated since 0.37.0 (@Deprecated(forRemoval = true)) and will be removed in a future release. If you have custom Java code calling them, switch to the GetContext / ListContext builders:

Recipe:

// Before
KafkaTopic topic = api.getResource(KafkaTopic.class, "events", configuration);

ResourceList<KafkaTopic> topics = api.listResources(
    KafkaTopic.class, selector, configuration);

// After
KafkaTopic topic = api.getResource(
    ResourceType.of(KafkaTopic.class),
    "events",
    GetContext.builder().configuration(configuration).build()
);

ResourceList<KafkaTopic> topics = api.listResources(
    ResourceType.of(KafkaTopic.class),
    ListContext.builder().selector(selector).configuration(configuration).build()
);

The new context objects also accept a provider (string) — that’s how you target a specific provider instance when you have several configured.

4. CLI Changes

get is now grouped by provider

jikkou get subcommands are organised under their provider. The canonical form is now:

jikkou get kafka topics
jikkou get kafka acls
jikkou get schema-registry subjects

Existing scripts that call the old flat form (jikkou get topics, jikkou get kafkatopics, jikkou get kt, …) still work — the old names are registered as hidden, deprecated subcommands that print a deprecation notice on each invocation. Plan to switch your scripts to the provider-grouped form before 1.1.0.

New flags on reconciliation commands

apply, create, update, patch, replace, delete, and diff accept three new options for multi-provider setups:

--provider, --provider-all, and --provider-group are mutually exclusive. None of them are required: if you have a single provider of each type, your existing commands keep working unchanged.

Output format options

-o/--output now accepts JSON, YAML, or TABLE on list and get commands.

5. REST API Additions

ResourceReconcileRequest accepts two new optional fields:

{
  "resources": [ ... ],
  "providers": ["kafka-prod-eu", "kafka-prod-us"],
  "continueOnError": true
}

Both fields are additive. Existing clients that omit them are unaffected.

6. Verify the Upgrade

After updating coordinates and (optionally) imports:

# Confirm the version
jikkou --version

# Check that resources still parse and providers still load
jikkou api-providers list
jikkou api-resources

# Validate your manifests against the running providers
jikkou validate --files <your-manifests>

If you’re running custom extensions, watch the logs on first start for Class name 'io.streamthoughts.jikkou.…' is deprecated warnings — those are your remaining import-rename targets.

7. Rolling Back

If something goes wrong, revert the coordinate change to fall back to 0.37.3. Pin to the previous version via the original group:

<groupId>io.streamthoughts</groupId>
<artifactId>jikkou-core</artifactId>
<version>0.37.3</version>

Or download the binary from the v0.37.3 GitHub release.

Need Help?

• 🐛 Open an issue: https://github.com/streamthoughts/jikkou/issues
• 💬 Ask on Slack: https://join.slack.com/t/jikkou-io/shared_invite/zt-27c0pt61j-F10NN7d7ZEppQeMMyvy3VA