Getting started with Quarkus

Procedure

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

   Note

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

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

   <!-- Configure the 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>

   Copy to Clipboard Toggle word wrap

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>

   Copy to Clipboard Toggle word wrap

Procedure

1. Download the Quarkus Maven repository ZIP file from the Software Downloads page of the Red Hat Customer Portal (login required).
2. Extract the downloaded archive.
3. Change the directory to the ~/.m2/ directory and open the Maven settings.xml file in a text editor or integrated development environment (IDE).

4. Add the path of the Quarkus Maven repository that you downloaded to the <profiles> element of the settings.xml file. The format of the path of the Quarkus Maven repository must be file://$PATH, for example, file:///home/userX/<root-directory-of-the-downloaded-archive>/maven-repository.

   <!-- Configure the Quarkus Maven repository -->
   <profile>
     <id>red-hat-enterprise-maven-repository</id>
     <repositories>
       <repository>
         <id>red-hat-enterprise-maven-repository</id>
         <url>file:///path/to/Quarkus/Maven/repository/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>red-hat-enterprise-maven-repository</id>
         <url>file:///path/to/Quarkus/Maven/repository/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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 <user_home_directory_name>/.quarkus directory on your machine.

2. Add the new registry to this file. For example:

   config.yaml

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

   Copy to Clipboard Toggle word wrap

Procedure

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

   mvn --version

   Copy to Clipboard Toggle word wrap
2. If the preceding command does not return OpenJDK 11 or 17, add the path to OpenJDK 11 or 17 to the PATH environment variable and enter the preceding command again.

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

   Note

   Apple macOS and Microsoft Windows are supported as developer environments, but are not supported as production environments.

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

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

     Copy to Clipboard Toggle word wrap

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

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

     Copy to Clipboard Toggle word wrap

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

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

     Copy to Clipboard Toggle word wrap

     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

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.group-id>com.redhat.quarkus.platform</quarkus.platform.group-id>
        <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
        <quarkus.platform.version>2.7.7.Final-redhat-00005</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>

   Copy to Clipboard Toggle word wrap

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

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

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

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

   Note

   With Quarkus, the Application class for 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, navigate 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 that you want to use for Maven artifacts generated from your project, for example, 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 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 that is used in artifacts generated from your project. The default value of this field is 1.0.0-SNAPSHOT. Using semantic versioning is recommended, but you can use a different type of versioning if you prefer.

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

      
      Note

      The code.quarkus.redhat.com repository automatically uses the latest release of Red Hat build of Quarkus. You can manually change the BOM version in the pom.xml file after you generate your project.

4. Select the extensions you want to use. The extensions that you select are included as dependencies of your Quarkus application and the Quarkus platform also ensures that the extensions are compatible in future versions.

   Important

   Ensure that you 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 recommends that you use 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 that are marked with STARTER-CODE.

   

5. To confirm your choices, select Generate your application. The download link for the archive that contains your generated project displays. The custom command that you can use to compile and start your application also displays.
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. Navigate to the directory that contains your extracted project files:

   cd <directory_name>

   Copy to Clipboard Toggle word wrap

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

   • Using Maven:

     ./mvnw quarkus:dev

     Copy to Clipboard Toggle word wrap

   • Using the Quarkus CLI:

     quarkus dev

     Copy to Clipboard Toggle word wrap

Procedure

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

   quarkus create && cd code-with-quarkus

   Copy to Clipboard Toggle word wrap
   Note

   You can also specify the 'app' subcommand, for example, quarkus create app, however, it is not mandatory as the 'app' subcommand is implied if it is not specified.

   With this command, the Quarkus project is created 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 on all the available Quarkus commands, specify the ‘help’ parameter:

   quarkus --help

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap

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

Verification

1. Compile and start your application in development mode.
2. Package and run your Getting Started project from the Quarkus CLI.