Skip to main content


This quickstart describes how to install Nussknacker configured to use Lite engine in Request-Response Processing mode using helm and Kubernetes and goes through sample scenarios.

If you want really quick look, you can run some parts of this quickstart with embedded engine with:

docker run -it --network host touk/nussknacker:latest

After it started go to http://localhost:8080 and login using credentials: admin/admin. REST endpoints of deployed scenarios will be exposed at http://localhost:8181/scenario/<slug>. Slug is defined in Properties, and by default it is scenario name. Be aware that some things (e.g. metrics) will not work, and this engine is not intended for production use.


  • helm, kubectl (more or less latest version) installed
  • access to Kubernetes cluster
    • for local installation with k3d see below
    • cluster should have ingress configured
  • Linux or MacOS

Running on local K3d

If you don't have K8s available, we recommend installing k3d. You can use helper script .k3d/ to bootstrap a K3d cluster and k3d/ to clean up when you finish experimenting. If you want to want to do it manually, remember that instructions below assume that the cluster was created with ingress port mapped to 8081 - see guide for the details.


  • Clone Nussknacker-quickstart project from GitHub.
  • If you have configured TLD connected to your ingress (not applicable with e.g. k3d setup), set DOMAIN parameter in k8s-helm/.env file.
  • Install additional sample customer service, not included in the standard chart with ./k8s-helm/additional/ Wait until they're running.
  • Run ./k8s-helm/ and wait until all components start.

In all links below we assume using k3d setup, described above. If you use ingress with TLD configured, please replace http://localhost:8081 with http(s)://nu-quickstart-nussknacker.$DOMAIN/ in all links below.

Now you are ready to check your newly created environment:

Defining a new scenario

  • Go to Nussknacker
  • Click Create new scenario button - name it LoanRequest
  • You'll see an empty workspace
  • Click Import on right panel and upload k8s-helm/scenarios/LoanRequest.json

This scenario determines acceptable amount for loan request. It uses only data available in request in this step.

Input and output schemas are available after clicking properties button:

"type": "object",
"properties": {
"customerId": {
"type": "string"
"location": {
"properties": {
"city": {
"type": "string"
"street": {
"type": "string"
"requestType": {
"type": "string"
"requestedAmount": {
"type": "number"
"required": ["customerId", "location", "requestType", "requestedAmount"],
"additionalProperties": false
  • Double-click on nodes to see scenario logic
  • Click Save

You have just created your first scenario!

Test scenario with data

  • Click Deploy on the right panel
  • Wait until deployment status shows running
  • After that your scenario should be exposed as nu-quickstart-loan service inside Kubernetes. First part of service name (nu-quickstart) is taken from helm release name. The second part is defined in "slug" scenario property. You can change it if you want. You can now communicate with deployed k8s service from other POD deployed on the same cluster. For our purpose we expose service port (80) on our machine port (3181) via:
kubectl port-forward service/nu-quickstart-loan 3181:80
  • Now service is available at http://localhost:3181. You can communicate with it using web interface at http://localhost:3181/swagger-ui or you can use curl command for that:
curl -d '{customerId: "anon", requestedAmount: 1555, requestType: "mortgage", location: { city: "Warszawa", street: "Marszałkowska" }}' -HContent-Type:application/json -i http://localhost:3181

or you can run script, that sends similar sample requests:

./k8s-helm/scripts/ <number between 1 and 6>

You should see result similar to below:

$ ./ 1
Sending request:

{customerId: "anon", requestedAmount: 1555, requestType: "mortgage", location: { city: "Warszawa", street: "Marszałkowska" }}

HTTP/1.1 200 OK
Server: akka-http/10.2.9
Date: Fri, 16 Sep 2022 08:17:25 GMT
Content-Type: application/json
Content-Length: 58

{"acceptedAmount":1000,"message":"Large sum for Warszawa"}
  • You can check Metrics tab on Nussknacker. You should see that data were changing a moment after each request.

Test your scenario in a sandbox

For Request-Response scenarios generate feature is currently unavailable, but you can test your scenario with some own prepared file with requests separated by newline. You can use for that ./k8s-helm/scripts/sampleLoanRequests.txt which was used by script described above.

  • Click from file button and upload file with sample requests
  • After a while you will see test results - how many records passed filters, and what where variables values

Add more behaviour to the scenario

After creating and running basic scenario it's time to add more sophisticated behaviour - in this (optional) section you'll see how to use a bit more complex components. After each step you can deploy, test and see modified results.

Integration with external system

In next step we'll see how to enrich data using external system, exposing customer data via OpenAPI. We implemented sample service in python (see customerservice folder), to show you don't have use Java to integrate with Nussknacker.

You can look at k8s-helm/values.yaml file (look for components.openAPI setting) to see how easy it is to configure additional OpenAPI services.

Click Import on right panel and upload k8s-helm/scenarios/LoanRequestWithEnrichers.json

You can see how we use new Enricher getcustomer to retrieve additional customer data to be able to categorize suspicious situations based on customer category

On the video you can see how Nussknacker detect fields from external service and how you can see metrics for OpenAPI intergration.

Clean up

When you done and you want to clean upo your environment you can use k8s-helm/ script. It will remove K8S deployments, pods and services created during your experimenting with Lite engine.
Moreover, if you used our script to bootstrap K3d cluster, you can use .k3d/ script to remove the cluster.