Chapter 1. Getting started with Red Hat build of Quarkus

Procedure

1. Open the Maven $HOME/.m2/settings.xml file in a text editor or an integrated development environment (IDE).

   Note

   If no settings.xml file is present in the $HOME/.m2/ directory, copy the settings.xml file from the $MAVEN_HOME/conf/ directory into the $HOME/.m2/ directory.

2. Add the following lines to the <profiles> element of the settings.xml file:

   <!-- Configure the Red Hat build of Quarkus Maven repository -->
   <profile>
     <id>red-hat-enterprise-maven-repository</id>
     <repositories>
       <repository>
         <id>red-hat-enterprise-maven-repository</id>
         <url>https://maven.repository.redhat.com/ga/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>red-hat-enterprise-maven-repository</id>
         <url>https://maven.repository.redhat.com/ga/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>

3. Add the following lines to the <activeProfiles> element of the settings.xml file and save the file.

   <activeProfile>red-hat-enterprise-maven-repository</activeProfile>

Procedure

1. Open the config.yaml file that contains your extension registry configuration. When you configure your extension registries for the first time, you might need to create a config.yaml file in the $HOME/.quarkus directory on your machine.

2. Add the new registry to the config.yaml file. For example:

   config.yaml

   registries:
     - registry.quarkus.redhat.com
     - registry.quarkus.io

Procedure

1. To verify that Maven is using OpenJDK 17 or 21, that the Maven version is 3.8.6 or later, and that mvn is accessible from the PATH environment variable, enter the following command:

   mvn --version

2. If the preceding command does not return OpenJDK 17 or 21, add the path to OpenJDK 17 or 21 to the PATH environment variable and enter the preceding command again.

3. To generate the project, enter one of the following commands:

   • If you are using Linux or Apple macOS, enter the following command:

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.8.4.redhat-00002:create \
         -DprojectGroupId=org.acme \
         -DprojectArtifactId=getting-started \
         -DplatformGroupId=com.redhat.quarkus.platform \
         -DplatformVersion=3.8.4.redhat-00002 \
         -DclassName="org.acme.quickstart.GreetingResource" \
         -Dpath="/hello"
     cd getting-started

   • If you are using the Microsoft Windows command line, enter the following command:

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.8.4.redhat-00002:create
     -DprojectGroupId=org.acme -DprojectArtifactId=getting-started
     -DplatformGroupId=com.redhat.quarkus.platform
     -DplatformVersion=3.8.4.redhat-00002
     -DclassName="org.acme.quickstart.GreetingResource"
     -Dpath="/hello"

   • If you are using the Microsoft Windows PowerShell, enter the following command:

     mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.8.4.redhat-00002:create
     "-DprojectGroupId=org.acme"
     "-DprojectArtifactId=getting-started"
     "-DplatformVersion=3.8.4.redhat-00002"
     "-DplatformGroupId=com.redhat.quarkus.platform"
     "-DclassName=org.acme.quickstart.GreetingResource"
     "-Dpath=/hello"

     These commands create the following elements in the ./getting-started directory:

     • The Maven project directory structure
     • An org.acme.quickstart.GreetingResource resource exposed on /hello
     • Associated unit tests for testing your application in native mode and JVM mode
     • A landing page that is accessible on http://localhost:8080 after you start the application
     • Example Dockerfiles in the src/main/docker directory

     • The application configuration file

       Note

       Because Mandrel does not support macOS, you can use Oracle GraalVM to build native executables on this operating system.

       You can also build native executables by using Oracle GraalVM directly on bare metal Linux or Windows distributions. For more information about this process, see the Oracle GraalVM README and release notes.

       For more information about supported configurations, see Red Hat build of Quarkus Supported configurations.

4. After the directory structure is created, open the pom.xml file in a text editor and examine the contents of the file:

   pom.xml

   <project>
     ...
     <properties>
        ...
        <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
        <quarkus.platform.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
        <quarkus.platform.version>3.8.4.redhat-00002</quarkus.platform.version>
        ...
     </properties>
     ...
     <dependencyManagement>
         <dependencies>
           <dependency>
             <groupId>${quarkus.platform.group-id}</groupId>
             <artifactId>${quarkus.platform.artifact-id}</artifactId>
             <version>${quarkus.platform.version}</version>
             <type>pom</type>
             <scope>import</scope>
           </dependency>
         </dependencies>
     </dependencyManagement>
     ...
     <build>
         ...
         <plugins>
           ...
           <plugin>
             <groupId>${quarkus.platform.group-id}</groupId>
             <artifactId>quarkus-maven-plugin</artifactId>
             <version>${quarkus.platform.version}</version>
             <extensions>true</extensions>
             <executions>
               <execution>
                 <goals>
                   <goal>build</goal>
                   <goal>generate-code</goal>
                   <goal>generate-code-tests</goal>
                 </goals>
               </execution>
             </executions>
           </plugin>
           ...
         </plugins>
         ...
     </build>
    ...
   </project>

   The <dependencyManagement> section of the pom.xml file contains the Quarkus BOM. Therefore, you do not need to list the versions of individual Quarkus dependencies in the pom.xml file. In this configuration file, you can also find the quarkus-maven-plugin plugin that is responsible for packaging the application.

5. Review the quarkus-resteasy-reactive dependency in the pom.xml file. This dependency enables you to develop REST applications:

   <dependency>
       <groupId>io.quarkus</groupId>
       <artifactId>quarkus-resteasy-reactive</artifactId>
   </dependency>

6. Review the src/main/java/org/acme/quickstart/GreetingResource.java file:

   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   @Path("/hello")
   public class GreetingResource {
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "Hello from RESTEasy Reactive";
       }
   }

   This file contains a simple REST endpoint that returns Hello from RESTEasy Reactive as a response to a request that you send to the /hello endpoint.

   Note

   With Quarkus, the Application class for Jakarta REST (formerly known as JAX-RS) is supported but not required. In addition, only one instance of the GreetingResource class is created and not one per request. You can configure this by using different *Scoped annotations, for example ApplicationScoped, RequestScoped, and so on.

Procedure

1. On your web browser, go to https://code.quarkus.redhat.com.

2. Specify basic details about your project:

   
   1. Enter a group name for your project. The name format follows the Java package naming convention; for example, org.acme.
   2. Enter a name for the Maven artifacts generated by your project, such as code-with-quarkus.

   3. Select the build tool you want to use to compile and start your application. The build tool that you choose determines the following setups:

      • The directory structure of your generated project
      • The format of configuration files that are used in your generated project

      • The custom build script and command for compiling and starting your application that code.quarkus.redhat.com displays for you after you generate your project

        Note

        Red Hat provides support for using code.quarkus.redhat.com to create Quarkus Maven projects only.

3. Specify additional details about your application project:

   1. To display the fields that contain further application details, select More options.
   2. Enter a version you want to use for artifacts generated by your project. The default value of this field is 1.0.0-SNAPSHOT. Using semantic versioning is preferred; however, you can choose to specify a different type of versioning.

   3. Select whether you want code.quarkus.redhat.com to add starter code to your project. When you add extensions that are marked with "STARTER-CODE" to your project, you can enable this option to automatically create example class and resource files for those extensions when you generate your project. However, this option does not affect your generated project if you do not add any extensions that provide an example code.

      
   Note

   The code.quarkus.redhat.com application automatically uses the latest release of Red Hat build of Quarkus. However, should you require, it is possible to manually change to an earlier BOM version in the pom.xml file after you generate your project, but this is not recommended.

4. Select the extensions that you want to use. The Quarkus application includes the extensions you select as dependencies. The Quarkus platform also ensures these extensions are compatible with future versions.

   Important

   Do not use the RESTEasy and the RESTEasy Reactive extensions in the same project.

   The quark icon ( ) next to an extension indicates that the extension is part of the Red Hat build of Quarkus platform release. Red Hat prefers using extensions from the same platform because they are tested and verified together and are therefore easier to use and upgrade.

   You can enable the option to automatically generate starter code for extensions marked with "STARTER-CODE".

   

5. To confirm your choices, select Generate your application. The dialog box that appears displays the following items:

   • A link to download the archive that contains your generated project
   • A command that you can use to compile and start your application
6. To save the archive with the generated project files to your machine, select Download the ZIP.
7. Extract the contents of the archive.

8. Go to the directory that contains your extracted project files:

   cd <directory_name>

9. To compile and start your application in dev mode, use one of the following methods:

   • Using Maven:

     ./mvnw quarkus:dev

   • Using the Quarkus CLI:

     quarkus dev

Procedure

1. To generate the project, in a command terminal, enter the following command:

   quarkus create && cd code-with-quarkus

   Note

   You can also specify the 'app' subcommand, for example, quarkus create app. However, it is not mandatory to do so because the 'app' subcommand is implied if it is not specified.

   With this command, you create the Quarkus project in a folder called 'code-with-quarkus' in your current working directory.

2. By default, the groupId, artifactId, and version attributes are specified with the following default values:

   • groupId='org.acme'
   • artifactId='code-with-quarkus'

   • version='1.0.0-SNAPSHOT'

     To change the values of the groupId, artifactId, and version attributes, issue the quarkus create command and specify the following syntax on the CLI:

     groupId:artifactId:version

     For example, quarkus create app mygroupId:myartifactid:version

   Note

   To view information about all the available Quarkus commands, specify the help parameter:

   quarkus --help

3. Review the src/main/java/org/acme/GreetingResource.java file in a text editor:

   package org.acme;
   
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   @Path("/hello")
   public class GreetingResource {
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return "Hello from RESTEasy Reactive";
       }
   }

   This file contains a simple REST endpoint that returns Hello from RESTEasy Reactive as a response to a request that you send to the /hello endpoint.

Verification

1. Compile and start your application in dev mode. For more information, see Compiling and starting the Red Hat build of Quarkus Getting Started project.
2. Package and run your Getting Started project from the Quarkus CLI. For more information, see Packaging and running the Red Hat build of Quarkus Getting Started application.