se.guides.quickstart.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2018, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Helidon SE Quickstart
:description: Helidon SE Quickstart Guide
:keywords: helidon
:rootdir: {docdir}/../..
include::{rootdir}/includes/se.adoc[]
This guide describes a basic example of an Helidon SE application using Docker and Kubernetes.
== What You Need
For this 5 minute tutorial, you will need the following:
include::{rootdir}/includes/prerequisites.adoc[tag=prerequisites]
== Generate The Project
Generate the project sources using the Helidon Maven archetype.
The result is a simple project that shows the basics of
a Helidon SE application using simple WebServer routing rules.
[source,bash,subs="attributes+"]
.Run the Maven archetype
----
mvn -U archetype:generate -DinteractiveMode=false \
-DarchetypeGroupId=io.helidon.archetypes \
-DarchetypeArtifactId=helidon-quickstart-se \
-DarchetypeVersion={helidon-version} \
-DgroupId=io.helidon.examples \
-DartifactId=helidon-quickstart-se \
-Dpackage=io.helidon.examples.quickstart.se
----
[source,bash]
.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-se`). Change into this directory.
[source,bash]
----
cd helidon-quickstart-se
----
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.
[source,bash]
.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:
[source,bash]
.Run the application
----
java -jar target/helidon-quickstart-se.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:
[source,bash]
.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.
[source,bash]
.Health
----
curl -sv -X GET http://localhost:8080/observe/health
----
Notice we use the `-v` option to curl so that you can see that the health endpoint returns 204 (No Content) by default.
[source,bash]
.Metrics in Prometheus Format
----
curl -s -X GET http://localhost:8080/observe/metrics
----
[source,bash]
.Metrics in JSON Format
----
curl -H 'Accept: application/json' -X GET http://localhost:8080/observe/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.
[source,bash]
.Docker build
----
docker build -t helidon-quickstart-se .
----
[source,bash]
.Run Docker Image
----
docker run --rm -p 8080:8080 helidon-quickstart-se: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
xref:../../about/kubernetes.adoc[install one on your desktop].
Then deploy the example:
[source,bash]
.Verify connectivity to cluster
----
kubectl cluster-info
kubectl get nodes
----
[source,bash]
.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.
[source,bash]
.Lookup the service
----
kubectl get service helidon-quickstart-se
----
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:
[source,bash]
curl -X GET http://localhost:31431/greet
After you're done, cleanup.
[source,bash]
.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:
* xref:graalnative.adoc[GraalVM Native Images]
* xref:jlink-image.adoc[Custom Runtime Images using `jlink`]
== 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.
xref:../../about/cli.adoc[Try it now].