Skip to main content

Introduction

Kugelblitz is a Spring Boot application template that lets us set up REST JSON API webservice with minimal effort. Its goal is to swiftly productionize a persistence webservice with all the elements of modern microservices with features including:

  • Explicit interface: Kugelblitz specifically serves impersonation-free CRUD operations
  • Tech agnostic API: In a world of constant and rapid changes, Kugelblitz does not require integration technology that dictates what technology stack to use for interactions
  • Simple: Kugelblitz allows clients full freedom in technology choice by API Doc Badge

Kugelblitz is designed for:

  • non-business persistence capabilities that maximizes functions while minimizes the conceptual complexities (everything is built on top of exiting best practices; no new concept invented)
  • performance-wise caching

It is not for:

  • security aspect, such as Authentication or Authorization
  • any business layer logics

For this reason, Kugelblitz is suitable for a microservice architecture.

Quick Start​

Getting Podman Image​

wget https://kugelblitz.openml.io/openml-kugelblitz.tar
podman load -i openml-kugelblitz.tar

Setting Environment Variables​

tip
  • Feel free to change the values of KUGELBLITZ_ARANGO_USERNAME and KUGELBLITZ_ARANGO_PASSWORD. The values below are examples only.
  • Please do NOT, however, modify the values http://arango-db:8529 and $KUGELBLITZ_ARANGO_PASSWORD
export KUGELBLITZ_ARANGO_HOSTS=http://arango-db:8529 && \
export KUGELBLITZ_ARANGO_USERNAME=root && \
export KUGELBLITZ_ARANGO_PASSWORD=root && \
export ARANGO_ROOT_PASSWORD=$KUGELBLITZ_ARANGO_PASSWORD

Spinning Up Services​

Save the reference compose.yaml below where we could use for production. Simply execute

services:
  kugelblitz:
    image: localhost/openmlio-kugelblitz
    ports:
      - "8080:8080"
    environment:
      KUGELBLITZ_ARANGO_HOSTS: ${KUGELBLITZ_ARANGO_HOSTS}
      KUGELBLITZ_ARANGO_USERNAME: ${KUGELBLITZ_ARANGO_USERNAME}
      KUGELBLITZ_ARANGO_PASSWORD: ${KUGELBLITZ_ARANGO_PASSWORD}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      timeout: 10s
      retries: 10
    depends_on:
      arango-db:
        condition: service_healthy

  arango-db:
    image: arangodb:latest
    ports:
      - "8529:8529"
    environment:
      ARANGO_ROOT_PASSWORD: ${ARANGO_ROOT_PASSWORD}
    volumes:
      - arango-data:/var/lib/arangodb3
      - arango-app:/var/lib/arangodb3-apps
    healthcheck:
      test: [ "CMD", "arangosh", "--server.endpoint", "tcp://localhost:8529", "--server.username", "root", "--server.password", "${ARANGO_ROOT_PASSWORD}", "--javascript.execute-string", "db._version()" ]
      timeout: 3s
      retries: 10
      start_period: 20s

volumes:
  arango-data:
  arango-app:

Then start the service with

podman-compose up

When we see the output like the following

arango-db-1  | 2025-05-11T15:26:29Z [1] INFO [cf3f4] {general} ArangoDB (version 3.11.13 [linux]) is ready for business. Have fun!
kugelblitz-1  |
kugelblitz-1  |   .   ____          _            __ _ _
kugelblitz-1  |  /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
kugelblitz-1  | ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
kugelblitz-1  |  \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
kugelblitz-1  |   '  |____| .__|_| |_|_| |_\__, | / / / /
kugelblitz-1  |  =========|_|==============|___/=/_/_/_/
kugelblitz-1  |
kugelblitz-1  |  :: Spring Boot ::                (v3.4.4)
kugelblitz-1  |
...
kugelblitz-1  | 2025-05-11T15:27:29.539Z  INFO 1 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed initialization in 2 ms

it means we are ready to play with Kugelblitz. Let's create a book entity first

curl -X 'POST' \
  'http://localhost:8080/arango/createDocument/library/books' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Pride and Prejudice",
  "author": "Jane Austen"
}'

Next we will verify the data has been saved into database. The quick start uses ArangoDB as the persistence database. We can first hit the Arando web console at http://localhost:8529/ which should take us to a page like the following:

ArangoDB web console login.

Use root and root as username and password, respectively. Then navigate to the data page by Login -> selecting library in database dropdown menu -> click Select DB: library -> click books collection -> click Content in the top navigation bar. As we can see the data already exists as an Arango document in the database:

Example Data in ArangoDB

tip

One could find more endpoints at http://localhost:8080/swagger-ui/index.html

Troubleshooting​

Healthcheck is Failing​

Inspect healthcheck logs with podman inspect --format "{{json .State.Health }}" <container name> | jq

ArangoDB Healthcheck is Failing with "ArangoError: not connected"​

This is mostly due to the wrong password during the "connection" via arangosh used in healthcheck. Wrong password could be