///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2018 Oracle and/or its affiliates. All rights reserved.

    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.

///////////////////////////////////////////////////////////////////////////////

= Quickstart Examples
:description: Helidon Quickstart examples
:keywords: helidon

There are two quickstart samples, one for Helidon SE and one for Helidon
MP (MicroProfile). Generate the examples using Maven archetypes.
The resulting Maven projects contain support for Docker and Kubernetes.

== Prerequisites

If you haven't already, make sure you have satisfied the
<<getting-started/01_prerequisites.adoc,system prerequisites>>

== Generate The Project

Generate the project sources using one (or both) of the Helidon Maven archetypes.
Both examples result in a REST service that supports the same
REST API, but they implement it differently:

1. The Helidon SE example implements the REST service using the Helidon WebServer
   component directly. It shows the basics of configuring the WebServer
   and implementing basic routing rules.
2. The Helidon MP example implements the REST service using the JAX-RS
   support provided by the Helidon MicroProfile server.

[source,bash,subs="attributes+"]
.Helidon SE Example
----
mvn archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-se \
    -DarchetypeVersion={helidon-version} \
    -DgroupId=io.helidon.examples \
    -DartifactId=quickstart-se \
    -Dpackage=io.helidon.examples.quickstart.se
----

[source,bash,subs="attributes+"]
.Helidon MP Example
----
mvn archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-mp \
    -DarchetypeVersion={helidon-version} \
    -DgroupId=io.helidon.examples \
    -DartifactId=quickstart-mp \
    -Dpackage=io.helidon.examples.quickstart.mp
----

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

[source,bash]
----
cd quickstart-*
----

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

For either example:

[source,bash]
----
mvn package
----

== Run the Application

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]
.Helidon SE Example
----
java -jar target/quickstart-se.jar
----

[source,bash]
.Helidon MP Example
----
java -jar target/quickstart-mp.jar
----

== Try the Application

Both examples support the same REST interface, so you exercise both examples
the same way.

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:

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

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

curl -X PUT http://localhost:8080/greet/greeting/Hola
{"greeting":"Hola"}

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

== Build a Docker Image

The project also contains a Docker file so that you can easily
build and run a docker image. Because the example's runtime
dependencies are already in `target/libs`, the Docker file is
pretty simple (see `target/Dockerfile`). To build the Docker
image, you need to have Docker installed and running on your system.

[source,bash]
.Helidon SE Example
----
docker build -t quickstart-se target
----

[source,bash]
.Helidon MP Example
----
docker build -t quickstart-mp target
----

== Run Docker Image

[source,bash]
.Helidon SE Example
----
docker run --rm -p 8080:8080 quickstart-se:latest
----

[source,bash]
.Helidon MP Example
----
docker run --rm -p 8080:8080 quickstart-mp:latest
----

Then you can try the application as you did before.

[[deploy-to-k8s]]
== Deploy the application to Kubernetes

If you don't have access to a Kubernetes cluster, you can
<<getting-started/04_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 target/app.yaml
kubectl get pods                    # Wait for quickstart pod to be RUNNING
----

== Exercise the Application on Kubernetes

Start the Kubernetes proxy server so you can connect to your service via localhost:

[source,bash]
.Start kubctl proxy
----
kubectl proxy
----

Next get the service's info.

[source,bash]
.Helidon SE Example
----
kubectl get service quickstart-se
----

[source,bash]
.Helidon MP Example
----
kubectl get service 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.

[source,bash]
.Remove the application from Kubernetes
----
kubectl delete -f target/app.yaml
----

