This guide describes a basic example of an Helidon MP application using Docker and Kubernetes.

What You Need

For this 5 minute tutorial, you will need the following:

Java SE 21 (Open JDK 21)

Helidon requires Java 21+ (25+ recommended).

Maven 3.8+

Helidon requires Maven 3.8+.

Docker 18.09+

If you want to build and run Docker containers.

Kubectl 1.16.5+

If you want to deploy to Kubernetes, you need kubectl and a Kubernetes cluster (you can install one on your desktop.

Helidon CLI

If you want to use the Helidon CLI to create and build your application
Verify Prerequisites
java -version
mvn --version
docker --version
kubectl version
Setting JAVA_HOME
# On Mac
export JAVA_HOME=`/usr/libexec/java_home -v 21`

# On Linux
# Use the appropriate path to your JDK
export JAVA_HOME=/usr/lib/jvm/jdk-21

Generate the Project

Generate the project sources using the Helidon Maven archetype. The result is a simple project that shows the basics of a MicroProfile application.

Run the Maven archetype
mvn -U archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-mp \
    -DarchetypeVersion=4.3.0-SNAPSHOT \
    -DgroupId=io.helidon.examples \
    -DartifactId=helidon-quickstart-mp \
    -Dpackage=io.helidon.examples.quickstart.mp
Tip
 If you are using an earlier version of Helidon and the above command fails with java.lang.NoSuchMethodError then you can work-around the error by replacing archetype:generate with org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate. Or use the helidon CLI.
Or alternatively run the helidon CLI
helidon init --batch -Dflavor=mp -Dapp-type=quickstart

The archetype generates a Maven project in your current directory (for example, helidon-quickstart-mp). Change into this directory.

cd helidon-quickstart-mp
Tip
 If you want to use the generated project as a starter for your own application, then you can replace groupId, artifactId and package with values appropriate for your application.
Build the Application
mvn package

The project builds an application jar for the example and saves all runtime dependencies in the target/libs directory. This means you can easily start the application by running the application jar file:

Run the application
java -jar target/helidon-quickstart-mp.jar

The example is a very simple "Hello World" greeting service. It supports GET requests for generating a greeting message, and a PUT request for changing the greeting itself. The response is encoded using JSON. For example:

Try the Application
curl -X GET http://localhost:8080/greet
{"message":"Hello World!"}

curl -X GET http://localhost:8080/greet/Joe
{"message":"Hello Joe!"}

curl -X PUT -H "Content-Type: application/json" -d '{"greeting" : "Hola"}' http://localhost:8080/greet/greeting

curl -X GET http://localhost:8080/greet/Jose
{"message":"Hola Jose!"}

Health and Metrics

Helidon provides built-in support for health and metrics endpoints.

Health
curl -s -X GET http://localhost:8080/health
Metrics in Prometheus Format
curl -s -X GET http://localhost:8080/metrics
Metrics in JSON Format
curl -H 'Accept: application/json' -X GET http://localhost:8080/metrics

Build a Docker Image

The project also contains a Dockerfile so that you can easily build and run a Docker image. To build the Docker image, you need to have Docker installed and running on your system.

Docker build
docker build -t helidon-quickstart-mp .
Run Docker Image
docker run --rm -p 8080:8080 helidon-quickstart-mp:latest

Then you can try the application as you did before.

Deploy the Application to Kubernetes

If you don’t have access to a Kubernetes cluster, you can install one on your desktop. Then deploy the example:

Verify connectivity to cluster
kubectl cluster-info
kubectl get nodes
Deploy the application to Kubernetes
kubectl create -f app.yaml
kubectl get pods # Wait for quickstart pod to be RUNNING

The step above created a service that is exposed into any node port. Lookup the service to find the port.

Lookup the service
kubectl get service helidon-quickstart-mp

Note the PORTs. You can now exercise the application as you did before but use the second port number (the NodePort) instead of 8080. For example:

curl -X GET http://localhost:31431/greet

After you’re done, cleanup.

Remove the application from Kubernetes
kubectl delete -f app.yaml

Building Native and Custom Runtime Images

Helidon also includes support for GraalVM Native Images and Java Custom Runtime Images. For more information see:

The Helidon CLI

With the Helidon CLI you can create additional types of Helidon applications and use the "dev loop" to do fast, iterative development. Try it now.