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

= First steps
:page-aliases: first-steps.adoc

This guide outlines various ways to create a new Camel Quarkus application.

== Prerequisites

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

== {link-quarkus-code-generator}

Projects can be generated at https://{link-quarkus-code-generator}[{link-quarkus-code-generator}].
All of the Camel Quarkus extensions can be found under the 'Integration' category.
Use the 'search' field to help with finding extensions that you are interested in.

Simply select the component extensions that you want to work with
and click the 'Generate your application' button to download a basic skeleton project.
There is also the option to push the project directly to GitHub.

When the project archive download has completed successfully, unzip and import into your favorite IDE.

== Maven plugin

Quarkus provides a Maven plugin that enables you to quickly bootstrap projects. For example, to create a project skeleton that includes the `timer` and `log` component extensions:

[source,shell,subs="attributes"]
----
$ mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions=camel-quarkus-log,camel-quarkus-timer

$ cd getting-started
----

NOTE: Windows users should omit the `\` if using `cmd`. When using `Powershell`, wrap the `-D` parameters in double quotes.


https://gradle.org/[Gradle] support is also available. See the https://quarkus.io/guides/gradle-tooling[Quarkus Gradle] guide for more information.

== IDE plugins

Quarkus has plugins for most of the popular development IDEs. They provide Quarkus language support, code / config completion, project creation wizards and much more. The plugins are available at each respective IDE marketplace.

* https://marketplace.eclipse.org/content/quarkus-tools[Eclipse plugin]
* https://plugins.jetbrains.com/plugin/13234-quarkus-tools[IntelliJ plugin]
* https://marketplace.visualstudio.com/items?itemName=redhat.vscode-quarkus[VSCode plugin]

Check the documentation of the given plugin to discover how to create projects in your preferred IDE.

=== Camel content assist

The following plugins provide support for content assist when editing Camel routes and `application.properties`:

* https://marketplace.visualstudio.com/items?itemName=redhat.vscode-apache-camel[VS Code Language support for Camel] - a part of the https://marketplace.visualstudio.com/items?itemName=redhat.apache-camel-extension-pack[Camel extension pack]
* https://marketplace.eclipse.org/content/language-support-apache-camel[Eclipse Desktop Language Support for Camel] - a part of https://tools.jboss.org/[Jboss Tools] and https://developers.redhat.com/products/codeready-studio[CodeReady Studio]
* https://plugins.jetbrains.com/plugin/9371-apache-camel-idea-plugin[Apache Camel IDEA plugin] (not always up to date)
* Users of other https://microsoft.github.io/language-server-protocol/implementors/tools/[IDEs supporting Language Server Protocol]
may choose to install and configure https://github.com/camel-tooling/camel-language-server[Camel Language Server] manually

== Example projects

Camel Quarkus provides a GitHub repository containing a set of xref:user-guide/examples.adoc[example projects].

https://github.com/apache/camel-quarkus-examples

The main branch is always aligned with the latest Camel Quarkus release.

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

1. Clone the Camel Quarkus examples repository:
+
[source,shell]
----
$ git clone https://github.com/apache/camel-quarkus-examples.git
----

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

3. Open the `pom.xml` file in your IDE. Change the project `groupId`, `artifactId` & `version` as necessary.

==== Explore the application code

The application has 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.quarkus</groupId>
    <artifactId>camel-quarkus-jackson</artifactId>
</dependency>
----

They are managed within the `io.quarkus.platform:quarkus-camel-bom` that is imported in `<dependencyManagement>`.

[NOTE]
====
More about xref:user-guide/dependency-management.adoc[BOMs].
====

There are only three classes in the application: `Routes` defines the Camel routes, whereas `Fruit` and `Legume` are entities.

The application is configured by properties defined within `src/main/resources/application.properties`. 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#dev-mode[Quarkus documentation] for more details about the development mode.

==== 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/quarkus-app
...
-rw-r--r--. 1 ppalaga ppalaga 238K Oct 11 18:55  quarkus-run.jar
...
----

You can run it as follows:

[source,shell]
----
$ java -jar target/quarkus-app/quarkus-run.jar
...
[io.quarkus] (main) Quarkus 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/quarkus-app/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 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 guide] contains more details
including
https://quarkus.io/guides/building-native-image-guide.html#creating-a-container[steps for creating a container image].

== What's next?

We recommend to continue with xref:user-guide/dependency-management.adoc[Dependency management].