docs/modules/ROOT/pages/first-steps.adoc

= First steps

We recommend you to choose an example from our https://github.com/apache/camel-quarkus/tree/master/examples[source tree]
as a base for your real world project.

== Prerequisites

* A `git` client
* An IDE
* JDK 1.8+ with JAVA_HOME configured appropriately
* Apache Maven 3.5.3+
* GraalVM with `native-image` command installed and `GRAALVM_HOME` environment variable set, see
  https://quarkus.io/guides/building-native-image-guide[Building a native executable] section of the Quarkus
  documentation.
* If your are on Linux, `docker` is sufficient for the native mode too. Use `-Pnative,docker` instead of `-Pnative`
  if you choose this option.

== Step by step with the `rest-json` example

1. Clone Camel Quarkus and checkout the latest release tag
+
[source,shell]
----
$ git clone https://github.com/apache/camel-quarkus.git
$ cd camel-quarkus
# checkout the latest tag
$ git checkout $(git describe --abbrev=0)
----

2. Copy the `rest-json` example out of the Camel Quarkus source tree.
+
[source,shell]
----
$ cd ..
$ cp -r camel-quarkus/examples/rest-json .
$ cd rest-json
----

3. Open the `pom.xml` file in your IDE.
+
Make sure that the parent is `org.apache.camel.quarkus:camel-quarkus-bom` and do the changes as
sketched below:
+
[source,xml,subs="attributes+"]
----
<project>
    <parent>
        <groupId>org.apache.camel.quarkus</groupId>
        <artifactId>camel-quarkus-bom</artifactId><!--1-->
        <version>{camel-quarkus-last-release}</version>
        <!-- <relativePath>../../bom/pom.xml</relativePath> --><!--2-->
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.my-org</groupId><!--3-->
    <artifactId>my-app</artifactId><!--4-->
    <version>0.0.1-SNAPSHOT</version><!--5-->

    ...

</project>
----
<1> Change the `<artifactId>` element to `camel-quarkus-bom`.
<2> Remove the `<relativePath>` element.
<3> Add a `groupId` of your choice.
<4> Change the `artifactId` to whatever you like
<5> Add the `version`

== Explore the application code

The application has just two compile dependencies:

[source,xml,subs="attributes+"]
----
<dependency>
    <groupId>org.apache.camel.quarkus</groupId>
    <artifactId>camel-quarkus-platform-http</artifactId>
</dependency>
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-jackson</artifactId>
</dependency>
----

They are managed in `camel-quarkus-bom` that we use as the Maven parent. `camel-quarkus-bom` and its ancestors also
manage plugins necessary for a typical Camel Quarkus application. In case you cannot use `camel-quarkus-bom` as a
parent of your application, make sure that you add those plugins manually.

There are only three classes in the application: `Routes` defining the Camel routes and a couple of entity classes
(`Fruit` and `Legume`).

`src/main/resources/application.properties` configure the application. E.g. the `camel.context.name` is set there.

== Development mode

[source,shell]
----
$ mvn clean compile quarkus:dev
----

This command compiles the project, starts your application and lets the Quarkus tooling watch for changes in your
workspace. Any modifications in your project will automatically take effect in the running application.

Check the application in the browser, e.g. http://localhost:8080/fruits[http://localhost:8080/fruits]
for the `rest-json` example

Then change something in the code and see the changes applied by refreshing the browser.

Please refer to https://quarkus.io/guides/maven-tooling#development-mode[Quarkus documentation] for more details.

== Testing

There are two test classes in our example: `RestJsonTest` is for the JVM mode while `RestJsonIT` is there for the native
mode.

The JVM mode tests are run by `maven-surefire-plugin` in the `test` Maven phase:

[source,shell]
----
$ mvn clean test
----

This should take about 15 seconds.

The native mode tests are verified by `maven-failsafe-plugin` in the `verify` phase. Pass the `native` property to
activate the profile that runs them:

[source,shell]
----
$ mvn clean verify -Pnative
----

This takes about 2.5 minutes (once you have all dependencies cached).

== Package and run the application

=== JVM mode

`mvn package` prepares a thin `jar` for running on a stock JVM:

[source,shell]
----
$ mvn clean package
$ ls -lh target
...
-rw-r--r--. 1 ppalaga ppalaga 238K Oct 11 18:55  my-app-0.0.1-SNAPSHOT-runner.jar
...
----

You can run it as follows:

[source,shell]
----
$ java -jar target/*-runner.jar
...
[io.quarkus] (main) Quarkus 0.23.2 started in 1.163s. Listening on: http://[::]:8080
----

Notice the boot time around a second.

The thin `jar` contains just the application code. To run it, the dependencies in `target/lib` are required too.

=== Native mode

To prepare a native executable using GraalVM, run the following command:

[source,shell]
----
$ mvn clean package -Pnative
$ ls -lh target
...
-rwxr-xr-x. 1 ppalaga ppalaga  46M Oct 11 18:57  my-app-0.0.1-SNAPSHOT-runner
...
----

Note that the `runner` in the listing above has no `.jar` extension and has the `x` (executable) permission set. Thus
it can be run directly:

[source,shell]
----
$ ./target/*-runner
...
[io.quarkus] (main) Quarkus 0.23.2 started in 0.013s. Listening on: http://[::]:8080
...
----

Check how fast it started and check how little memory it consumes:

[source,shell]
----
$ ps -o rss,command -p $(pgrep my-app)
  RSS COMMAND
34916 ./target/my-app-0.0.1-SNAPSHOT-runner
----

That's under 35 MB of RAM!

TIP: https://quarkus.io/guides/building-native-image-guide.html[Quarkus Native executable quide] contains more details
including
https://quarkus.io/guides/building-native-image-guide.html#creating-a-container[steps for creating a container image].