Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Getting started with developing applications for JBoss EAP deployment

Red Hat JBoss Enterprise Application Platform 8.0

Get started creating applications for JBoss EAP deployment.

Red Hat Customer Content Services

Abstract

Get started creating applications for JBoss EAP deployment by using Maven as the project management tool.Deploy your applications to JBoss EAP runing on bare metal or on OpenShift Container Platform.

Providing feedback on JBoss EAP documentation
Copy link

To report an error or to improve our documentation, log in to your Red Hat Jira account and submit an issue. If you do not have a Red Hat Jira account, then you will be prompted to create an account.

Procedure

  1. Click the following link to create a ticket.
  2. Enter a brief description of the issue in the Summary.
  3. Provide a detailed description of the issue or enhancement in the Description. Include a URL to where the issue occurs in the documentation.
  4. Clicking Submit creates and routes the issue to the appropriate documentation team.

Making open source more inclusive
Copy link

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

The best way to become familiar with a new programming language or a technology is to create a "Hello World" application. You can create a "Hello World" application for JBoss EAP by using Maven as the project management tool.

To create a Hello World application, deploy it and test the deployment, follow these procedures:

Bare metal deployment
OpenShift Container Platform deployment

A Maven project contains a pom.xml configuration file and has the directory structure required for creating an application. You can configure the pom.xml configuration file to add dependencies for your application.

To create a Maven project for a hello world application, follow these procedures:

Use the maven-archetype-webapp archetype to create a Maven project for building applications for JBoss EAP deployment. Maven provides different archetypes for creating projects based on templates specific to project types. The maven-archetype-webapp creates a project with the structure required to develop simple web-applications.

Prerequisites

Procedure

  1. Set up a Maven project by using the mvn command. The command creates the directory structure for the project and the pom.xml configuration file. 

    $ mvn archetype:generate                          \
-DgroupId=org.jboss.as.quickstarts                \
    1 
    
-DartifactId=helloworld                           \
    2 
    
-DarchetypeGroupId=org.apache.maven.archetypes    \
    3 
    
-DarchetypeArtifactId=maven-archetype-webapp      \
    4 
    
-DinteractiveMode=false
    5
    1
    groupID uniquely identifies the project.
    2
    artifactID is the name for the generated jar archive.
    3
    The groupID of maven-archetype-webapp.
    4
    The artifactID of maven-archetype-webapp.
    5
    Tell Maven to use the supplied parameters rather than starting interactive mode.

  2. Navigate to the generated directory. 

    $ cd helloworld
  3. Open the generated pom.xml configuration file in a text editor.

  4. Remove the content inside the <project> section of pom.xml configuration file after the <name>helloworld Maven Webapp</name> line.

    Ensure that the file looks like this: 

    <?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.jboss.as.quickstarts</groupId>
    <artifactId>helloworld</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    <name>helloworld Maven Webapp</name>

</project>

    The content was removed because it is not required for the application.

1.2. Defining properties in a Maven project
Copy link

You can define properties in a Maven pom.xml configuration file as place holders for values. Define the value for JBoss EAP server as a property to use the value consistently in the configuration.

Prerequisites

Procedure

  • Define a property <version.bom.microprofile> as the JBoss EAP version on which you will deploy the configured application. 

    <project>
    ...
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <version.bom.microprofile>5.0.0.GA-redhat-00009</version.bom.microprofile>
    </properties>
</project>

1.3. Defining the repositories in a Maven project
Copy link

Define the artifact and plug-in repositories in which Maven looks for artifacts and plug-ins to download.

Prerequisites

Procedure

  1. Define the artifacts repository. 

    <project>
    ...
    <repositories>
        <repository>
    1 
    
            <id>jboss-public-maven-repository</id>
            <name>JBoss Public Maven Repository</name>
            <url>https://repository.jboss.org/nexus/content/groups/public/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </releases>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </snapshots>
            <layout>default</layout>
        </repository>
        <repository>
    2 
    
            <id>redhat-ga-maven-repository</id>
            <name>Red Hat GA Maven Repository</name>
            <url>https://maven.repository.redhat.com/ga/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </releases>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>never</updatePolicy>
            </snapshots>
            <layout>default</layout>
        </repository>
    </repositories>
</project>
    1
    The Red Hat GA Maven repository provides all the productized JBoss EAP and other Red Hat artifacts.
    2
    The JBoss Public Maven Repository provides artifacts such as WildFly Maven plug-ins

  2. Define the plug-ins repository. 

    <project>
    ...
    <pluginRepositories>
        <pluginRepository>
            <id>jboss-public-maven-repository</id>
            <name>JBoss Public Maven Repository</name>
            <url>https://repository.jboss.org/nexus/content/groups/public/</url>
            <releases>
               <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
        <pluginRepository>
            <id>redhat-ga-maven-repository</id>
            <name>Red Hat GA Maven Repository</name>
            <url>https://maven.repository.redhat.com/ga/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>
</project>

Import the JBoss EAP EE With Tools Bill of materials (BOM) to control the versions of runtime Maven dependencies. When you specify a BOM in the <dependencyManagement> section, you do not need to individually specify the versions of the Maven dependencies defined in the provided scope.

Prerequisites

Procedure

  1. Add a property for the BOM version in the properties section of the pom.xml configuration file. 

    <properties>
    ....
    <version.bom.microprofile>5.0.0.GA-redhat-00009</version.bom.microprofile>
</properties>

    The value defined in the property <version.bom.microprofile> is used as the value for BOM version.

  2. Import the JBoss EAP BOMs dependency management. 

    <project>
    ...
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.jboss.bom</groupId>
    1 
    
                <artifactId>jboss-eap-ee-with-tools</artifactId>
    2 
    
                <version>${version.bom.ee}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>
    1
    GroupID of the JBoss EAP-provided BOM.
    2
    ArtifactID of the JBoss EAP-provided BOM that provides supported JBoss EAP Java EE APIs plus additional JBoss EAP API JARs and client BOMs, and development tools such as Arquillian.

1.5. Adding plug-in management in a Maven project
Copy link

Add Maven plug-in management section to the pom.xml configuration file to get plug-ins required for Maven CLI commands.

Prerequisites

Procedure

  1. Define the versions for wildfly-maven-plugin and maven-war-plugin, in the <properties> section. 

    <properties>
    ...
    <version.plugin.wildfly>4.2.1.Final</version.plugin.wildfly>
    <version.plugin.war>3.3.2</version.plugin.war>
</properties>

  2. Add <pluginManagement> in <build> section inside the <project> section. 

    <project>
    ...
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
    1 
    
                    <groupId>org.wildfly.plugins</groupId>
                    <artifactId>wildfly-maven-plugin</artifactId>
                    <version>${version.plugin.wildfly}</version>
                </plugin>
                <plugin>
    2 
    
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-war-plugin</artifactId>
                    <version>${version.plugin.war}</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>
    1
    You can use the wildfly-maven-plugin to deploy an application to JBoss EAP using the wildfly:deploy command.
    2
    You need to manage the war plugin version to ensure compatibility with JDK17+.

1.6. Verifying a maven project
Copy link

Verify that the Maven project you configured builds.

Prerequisites

Procedure

  • Install the Maven dependencies added in the pom.xml locally. 

    $ mvn package

    You get an output similar to the following: 

    ...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

Chapter 2. Creating a hello world servlet
Copy link

Create a servlet that returns "Hello world!" when accessed.

In this procedure, <application_home> refers to the directory that contains the pom.xml configuration file for the application.

Prerequisites

Procedure

  1. Add the required dependency to pom.xml configuration file after the <dependencyManagement> section. 

    <project>
    ...
    <dependencies>
        <dependency>
    1 
    
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
            <scope>provided</scope>
    2 
    
        </dependency>
    </dependencies>
    1
    jakarta.servlet-api dependency provides Jakarta Servlet API.
    2
    Define the scope as provided so that the dependency is not included in the application. The reason for not including the dependency in the application is that this dependency is managed by the jboss-eap-ee-with-tools BOM and such dependencies are are included with JBoss EAP.
    Note

    The dependency is defined without a version because jboss-eap-ee-with-tools BOM was imported in the <dependencyManagement> section.

  2. Navigate to the <application_home> directory.

  3. Create a directory to store the Java files. 

    $ mkdir -p src/main/java/org/jboss/as/quickstarts/helloworld

  4. Navigate to the new directory. 

    $ cd src/main/java/org/jboss/as/quickstarts/helloworld

  5. Create the Servlet HelloWorldServlet.java that returns "Hello World!". 

    package org.jboss.as.quickstarts.helloworld;

import java.io.IOException;
import java.io.PrintWriter;
import jakarta.servlet.ServletException;
import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@WebServlet("/HelloWorld")
    1 
    
public class HelloWorldServlet extends HttpServlet {

    static String PAGE_HEADER = "<html><head><title>helloworld</title></head><body>";

    static String PAGE_FOOTER = "</body></html>";

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.setContentType("text/html");
        PrintWriter writer = resp.getWriter();
        writer.println(PAGE_HEADER);
        writer.println("<h1> Hello World! </h1>");
        writer.println(PAGE_FOOTER);
        writer.close();
    }
}
    1
    The @WebServlet("/HelloWorld") annotation provides the following information to JBoss EAP:
    • This class is a servlet.

    • Make the servlet available at the URL "<application_URL>/HelloWorld".

      For example, if JBoss EAP is running on the localhost and is available at the default HTTP port, 8080, the URL is http://localhost:8080/helloworld/HelloWorld.

  6. Navigate to the <application_home>/src/main/webapp directory.

    You find the file "index.jsp" that Maven created. This file prints "Hello World!" when you access the application.

  7. Update the "index.jsp" file to redirect to the Hello World servlet by replacing its content with the following content: 

    <html>
    <head>
        <meta http-equiv="Refresh" content="0; URL=HelloWorld">
    </head>
</html>
  8. Navigate to the <application_home> directory.

  9. Compile and package the application as a web archive (WAR) with the following command: 

    $ mvn package

    Example output

    ...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

Chapter 3. Deploying an application to the server
Copy link

You can deploy your application on a JBoss EAP server running on bare metal or on OpenShift Container Platform.

To deploy your application on a JBoss EAP server running on bare metal, follow this procedure:

To deploy your application on a JBoss EAP server running on OpenShift Container Platform, follow these procedures:

You can deploy an application to JBoss EAP by using the JBoss EAP deploy plug-in.

Prerequisites

Procedure

  1. Navigate to the application root directory.

    The application root directory contains the pom.xml configuration file.

  2. Add the following build configuration to the pom.xml configuration file in the <project> section to define the application archive filename. 

    <build>
    ...
    <finalName>${project.artifactId}</finalName>
    1 
    
</build>
    1
    Set the name of the deployment to the project’s artifact ID.

  3. Build and deploy the application by using the JBoss EAP deploy plug-in. 

    $ mvn package wildfly:deploy

Verification

You can use the source-to-image (S2I) workflow to deploy your applications to JBoss EAP on OpenShift Container Platform. The S2I workflow takes source code from a Git repository and injects it into a container that’s based on the language and framework you want to use. After the S2I workflow is completed, the src code is compiled, the application is packaged and is deployed to the JBoss EAP server.

OpenShift Container Platform uses application hosted on a Git repository. To deploy your application on OpenShift, you must first push your application to a Git repository. After that, you can use JBoss EAP helm chart to configure your application deployment.

Prerequisites

Procedure

  1. Move the application to your local Git repository, if it already is not in it. 

    $ mv -r helloworld/ <your_git_repo>

  2. Define the following property in the pom.xml configuration file: 

    <properties>
    ...
    <version.plugin.eap>1.0.0.Final-redhat-00013</version.plugin.eap>
    1 
    
</properties>
    1
    <version.plugin.eap> defines the version for JBoss EAP Maven plug-in.

  3. Add the JBoss EAP maven plugin to <pluginManagement>, in <build> section inside the <project> section. 

    <project>
    ...
    <build>
        <pluginManagement>
            <plugins>
                ...
                <plugin>
                    <groupId>org.jboss.eap.plugins</groupId>
                    <artifactId>eap-maven-plugin</artifactId>
                    <version>${version.plugin.eap}</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

  4. Create a profile "openshift" in the pom.xml configuration file.

    This profile defines the plug-ins, feature packs, and layers required for deployment on OpenShift Container Platform. 

    <profiles>
    <profile>
        <id>openshift</id>
        <build>
            <plugins>
                <plugin>
                     <groupId>org.jboss.eap.plugins</groupId>
                     <artifactId>eap-maven-plugin</artifactId>
    1 
    
                     <configuration>
                         <channels>
                             <channel>
                                 <manifest>
                                     <groupId>org.jboss.eap.channels</groupId>
                                     <artifactId>eap-8.0</artifactId>
                                 </manifest>
                             </channel>
                         </channels>
                         <feature-packs>
                             <feature-pack>
    2 
    
                                 <location>org.jboss.eap:wildfly-ee-galleon-pack</location>
                             </feature-pack>
                             <feature-pack>
                                 <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location>
                             </feature-pack>
                         </feature-packs>
                         <layers>
    3 
    
                             <layer>cloud-server</layer>
                         </layers>
                         <name>ROOT.war</name>
    4 
    
                     </configuration>
                     <executions>
                         <execution>
                             <goals>
                                 <goal>package</goal>
                             </goals>
                         </execution>
                     </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>
    1
    wildfly-maven-plugin is a JBoss EAP plug-in for provisioning a JBoss EAP instance, with the application deployed, on OpenShift Container Platform.
    2
    feature-packs defines the feature-packs (zipped files that contains features to dynamically provision a server). In this case we need the feature-packs org.wildfly:wildfly-galleon-pack and org.wildfly.cloud:wildfly-cloud-galleon-pack.
    3
    layers defines the layers (from the configured feature-packs) to include in the provisioned server. Each layer identifies one or more server capabilities that can be installed on its own, or in combination with other layers. In our case we opt for the cloud-server layer, which provisions just the basic features of JBoss EAP, well suited for a cloud server.
    4
    <name>ROOT.war</name>: Defines the resulting name of the application’s web archive (WAR). If ROOT.war is specified then the application is deployed at the root path of the server, otherwise it is deployed at <name/> relative path.

  5. Verify that the applications compiles. 

    $ mvn package -Popenshift
  6. Push the changes to your repository.

Use the JBoss EAP Helm chart to configure and deploy application to JBoss EAP on OpenShift with Helm.

Prerequisites

Procedure

  1. Create a directory called charts in the application root directoy and navigate to it. Application root directory is the one that contains pom.xml configuration file. 

    $ mkdir charts; cd charts

  2. Create a file helm.yaml with the following content: 

    build:
  uri: https://github.com/<user>/<repository>.git
    1 
    
  ref: <branch_name>
    2 
    
  contextDir: helloworld
    3 
    
deploy:
  replicas: 1
    4
    1
    Specify the URL for your Git repository that contains the application to deploy on OpenShift Container Platform.
    2
    Specify the Git branch that contains your application.
    3
    Specify the directory containing the application.
    4
    Specify the number of pods to create.

  3. Configure the JBoss EAP repository in Helm.

    • If you haven’t added the JBoss EAP repository to Helm before, add it. 

      $ helm repo add jboss-eap https://jbossas.github.io/eap-charts/

    • If you already have added the JBoss EAP repository to Helm, update it. 

      $ helm repo update jboss-eap

  4. Deploy the application using helm. 

    $ helm install helloworld -f helm.yaml jboss-eap/eap8

    The deployment can take a few minutes to complete.

Verification

  1. Get the URL of the route to the deployment. 

    $ APPLICATION_URL=https://$(oc get route helloworld --template='{{ .spec.host }}') &&
echo "" &&
echo "Application URL: $APPLICATION_URL"

  2. Navigate to the "Application URL" in a browser.

    You are redirected to the servlet at path "/HelloWorld" and you get the following message: 

    Hello World!

To ensure that the Hello World application deployed on JBoss EAP is working, you can add integration tests.

To add tests for an application deployed on a JBoss EAP server running on bare metal, follow these procedures:

To add tests for an application deployed on a JBoss EAP server running on OpenShift Container Platform, follow these procedures:

To create integration tests for your applications, add the required Maven dependencies.

Prerequisites

Procedure

  1. Define the following properties in the pom.xml configuration file: 

    <properties>
    ...
    <version.plugin.failsafe>3.2.2</version.plugin.failsafe>
</properties>

  2. Add the dependency required for tests. 

    <project>
    ...
    <dependencies>
        ...
        <dependency>
           <groupId>junit</groupId>
           <artifactId>junit</artifactId>
           <scope>test</scope>
        </dependency>
    </dependencies>
</project>

  3. Define a profile to add the plug-ins required for integration tests. 

    <project>
    ...
    <profiles>
    ...
        <profile>
            <id>integration-testing</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-failsafe-plugin</artifactId>
    1 
    
                        <version>${version.plugin.failsafe}</version>
                        <configuration>
                            <includes>
                                <include>**/HelloWorldServletIT</include>
    2 
    
                            </includes>
                        </configuration>
                        <executions>
                            <execution>
                               <goals>
                                   <goal>integration-test</goal>
                                   <goal>verify</goal>
                               </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>
</project>
    1
    Maven plug-in for running integration tests.
    2
    The name of the Java class that tests the application.

4.2. Creating a test class to test an application
Copy link

Create an integration test that verifies that the application is deployed and running on JBoss EAP on OpenShift Container Platform, by checking that the HTTP GET of its web page returns 200 OK.

In this procedure, <application_home> refers to the directory that contains the pom.xml configuration file for the application.

Prerequisites

Procedure

  1. Navigate to the <application_home> directory.

  2. Create a directory to store the test class. 

    $ mkdir -p src/test/java/org/jboss/as/quickstarts/helloworld

  3. Navigate to the new directory. 

    $ cd src/test/java/org/jboss/as/quickstarts/helloworld

  4. Create a Java class HelloWorldServletIT.java that tests the deployment. 

    package org.jboss.as.quickstarts.helloworld;

import org.junit.Test;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import static org.junit.Assert.assertEquals;

public class HelloWorldServletIT {

    private static final String DEFAULT_SERVER_HOST = "http://localhost:8080/helloworld";
    1 
    

    @Test
    public void testHTTPEndpointIsAvailable() throws IOException, InterruptedException, URISyntaxException {
        String serverHost = System.getProperty("server.host");
        if (serverHost == null) {
            serverHost = DEFAULT_SERVER_HOST;
        }
        final HttpRequest request = HttpRequest.newBuilder()
                .uri(new URI(serverHost+"/HelloWorld"))
                .GET()
                .build();
    2 
    
        final HttpClient client = HttpClient.newBuilder()
                .followRedirects(HttpClient.Redirect.ALWAYS)
                .connectTimeout(Duration.ofMinutes(1))
                .build();
    3 
    
        final HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    4 
    
        assertEquals(200, response.statusCode());
    5 
    
    }
}
    1
    The URL at which the application is running. This value is used if sever.host is undefined.
    2
    Create an HttpRequest instance for the application URI.
    3
    Create an HttpClient to send requests to and receive response from the application.
    4
    Get response from the application.
    5
    Test that the response revieved from the application is "200" indicating that the application is rechable.

Test the application deployed on JBoss EAP that is running on bare metal.

Prerequisites

Procedure

  1. Navigate to the <application_home> directory.

  2. Run the integration test by using the verify command with the integration-testing profile. 

    $ mvn verify -Pintegration-testing

    Example output

    [INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- maven-failsafe-plugin:3.2.2:verify (default) @ helloworld ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  9.982 s
[INFO] Finished at: 2023-11-22T14:53:54+05:30
[INFO] ------------------------------------------------------------------------

Test the application deployed to JBoss EAP on OpenShift Container Platform.

Prerequisites

Procedure

  1. Push the changes to your Git repository.
  2. Navigate to the <application_home> directory.

  3. Run the test by using the verify command, activating the integration-testing profile and specifying the URL to the application. 

    $ mvn verify -Pintegration-testing -Dserver.host=https://$(oc get route helloworld --template='{{ .spec.host }}')
    Note

    The tests use SSL/TLS to connect to the deployed application. Therefore, you need the certificates to be trusted by the machine the tests are run from.

    To trust the certificates, you must add it to a Java trust store.

    Example

    $ keytool -trustcacerts -keystore _<path-to-java-truststore>_ -storepass _<trust-store-password>_ -importcert -alias _<alias-for-the-certificate>_ -file _<path-to-certificate>_/_<certificate-name>_

    Example output

    [INFO] Running org.jboss.as.quickstarts.helloworld.HelloWorldServletIT
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.345 s -- in org.jboss.as.quickstarts.helloworld.HelloWorldServletIT
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO] --- maven-failsafe-plugin:3.2.2:verify (default) @ helloworld ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.984 s
[INFO] Finished at: 2023-11-30T15:51:22+05:30
[INFO] ------------------------------------------------------------------------

Red Hat OpenShift Dev Spaces is a web-based IDE that you can use to develop applications. It provides developers and other IT team members with a consistent, secure, and zero-configuration development environment. OpenShift Dev Spaces includes Microsoft Visual Studio Code, and JetBrains IntelliJ IDEA integrated development environments (IDE).

You can use devfile to define different aspects of your workspace , such as the following:

  • Resource allocation
  • Pre-defined commands to build, test, debug, and run applications
  • Containers with development tools
  • Containers or Kubernetes manifests for services required for testing
  • Workspace start and stop events
  • Source code repositories
Note

The following procedures demonstrate the minimum required OpenShift Dev Spaces configurations to build, run, and debug your application in OpenShift Dev Spaces and also describe how to deploy your application to OpenShift Container Platform. For a complete list of configuration options, see product documentation for Red Hat OpenShift Dev Spaces.

To get started with using OpenShift Dev Spaces for developing JBoss EAP applications, follow these procedures:

Create a devfile in your application to configure a Red Hat OpenShift Dev Spaces workspace for your application. The devfile defines different aspects of your workspace such as source code repositories, resource allocation, containers with development tools, and so on.

This procedure uses Visual Studio Code as the integrated development environment (IDE) and defines both innerloop and outerloop commands. Innerloop commands refer to the commands that run within the OpenShift Dev Spaces workspace and outerloop commands are those that deploy your application externally.

Note

The following procedure describes the minimum steps required to get started with developing JBoss EAP applications in OpenShift Dev Spaces. For more information, see product documentation for Red Hat OpenShift Dev Spaces.

Prerequisites

Procedure

  1. Create a devfile, named devfile.yaml, at the root of the repository.

  2. Add schema and metadata information to the devfile. 

    schemaVersion: 2.2.0
    1 
    
metadata:
    2 
    
  name: <workspace-name>
    3 
    
  version: <version>
    4 
    
  displayName: <display-name>
    5
    1
    The schema version of the devfile.
    2
    Define metadata for your workspace.
    3
    Define a name for your workspace.
    4
    Define the version of the devfile.
    5
    Define the display name to use on a devfile registry.

  3. Define variables. You can use the value of the variable throughout the devfile by referencing the variable. 

    variables:
  imageRegistry: 'image-registry.openshift-image-registry.svc:5000'
    1 
    
  imageName: 'helloworld'
    2 
    
  nodeName: 'helloworld'
    3 
    
  target-namespace: 'getting-started'
    4
    1
    Define the registry to which you want to deploy your application image. The example uses the internal OpenShift registry.
    2
    Define a name for the image that will be built for the application.
    3
    Define a name for the node that will contain the application.
    4
    The namespace in which the application is to be deployed.

  4. Incorporate tools into the workspace for building your application within the workspace.

    Note

    When running OpenShift Dev Spaces in the developer sandbox, you can only use the predefined namespace. Therefore, you must comment out the following lines inside the env definition: 

    - name: TARGET_NAMESPACE
 .value: '{{target-namespace}}'
     
    components:
    1 
    
  - name: tools
    container:
    2 
    
      image: registry.redhat.io/devspaces/udi-rhel8:3.11-14
      memoryLimit: 1512Mi
      mountSources: true
      volumeMounts:
        - name: m2
          path: /home/user/.m2
      env:
    3 
    
        - name: JAVA_OPTS
          value: '-Djava.security.egd=file:/dev/urandom -Djboss.host.name=localhost'
        - name: DEBUG_PORT
          value: '5005'
        - name: NODE_NAME
          value: '{{nodeName}}'
        - name: IMAGE_REGISTRY
          value: '{{imageRegistry}}'
        - name: IMAGE
          value: '{{imageName}}'
        - name: TARGET_NAMESPACE
         .value: '{{target-namespace}}'
        - name: VSCODE_DEFAULT_WORKSPACE
          value: /projects/wildfly-devfile-examples/.code-workspace
        - name: USE_JAVA17
          value: 'true'
      endpoints:
    4 
    
        - name: debug
          exposure: internal
          protocol: tcp
          targetPort: 5005
        - name: 'http'
          protocol: http
          targetPort: 8080
          exposure: public
        - name: 'management'
          targetPort: 9990
          protocol: http
          exposure: internal
        - name: 'transactions'
          targetPort: 4172
          protocol: tcp
          exposure: internal
  - name: m2
    5 
    
    volume:
      size: 3Gi
    1
    Define a component named tools of the type container.
    2
    Use the udi-rhel8:3.11-14 UDI container from the registry.redhat.io/devspaces registry with the specified configuration.
    3
    Define environment variables.
    4
    Define the container endpoints as follows:
    • exposure: Define how the endpoint should be exposed on the network.
    • protocol: Define the application and transport protocols of the traffic that will go through this endpoint.
    • targetPort: The port number to be used within the container component. The same port cannot be used by two different container components.
    5
    Define a volume component. This is used in the tools component to mount the Maven repository.

  5. Add innerloop and outerloop commands. 

    commands:
  - id: package
    1 
    
    exec:
      label: "InnerLoop 01 - Build the application"
      component: tools
      commandLine: mvn clean package -Popenshift -Dmaven.wagon.http.ssl.insecure=true
      workingDir: ${PROJECT_SOURCE}/helloworld
      group:
        kind: build
        isDefault: true
  - id: run
    2 
    
    exec:
      label: "InnerLoop 02 - Run the application in dev mode"
      component: tools
      commandLine: ./target/server/bin/standalone.sh -Djboss.host.name=${NODE_NAME}
      workingDir: ${PROJECT_SOURCE}/helloworld
      group:
        kind: run
        isDefault: true
  - id: debug
    3 
    
    exec:
      label: "InnerLoop 03 - Debug the application in dev mode"
      component: tools
      commandLine: ./target/server/bin/standalone.sh -Djboss.host.name=${NODE_NAME} --debug
      workingDir: ${PROJECT_SOURCE}/helloworld
      group:
        kind: debug
        isDefault: true
  - id: shutdown
    4 
    
    exec:
      label: "InnerLoop 04 - Shutdown the server"
      component: tools
      commandLine: ./target/server/bin/jboss-cli.sh -c --command=shutdown
      workingDir: ${PROJECT_SOURCE}/helloworld
      hotReloadCapable: false
      group:
        kind: run
        isDefault: false
  - id: deploy-image
    5 
    
    exec:
      label: "OuterLoop 01 - Deploy Image to OpenShift"
      component: tools
      workingDir: ${PROJECT_SOURCE}/helloworld
      # When using developer sandbox, prefix the following command with export "IMAGE_REGISTRY_NAMESPACE=$(oc project -q) &&" because you can only use the predefined namespace in the developer sandbox
      commandLine: "helm repo add jboss https://jbossas.github.io/eap-charts/ && helm install ${IMAGE} --namespace=${IMAGE_REGISTRY_NAMESPACE} -f ./charts/helm.yaml jboss/eap8"
      group:
        kind: run
        isDefault: false
  - id: undeploy-image
    6 
    
    exec:
      label: "OuterLoop 02 - Undeploy Image from OpenShift"
      component: tools
      workingDir: ${PROJECT_SOURCE}/helloworld
      commandLine: "helm uninstall ${IMAGE}"
      group:
        kind: run
        isDefault: false
    1
    Define a command to build the application. This executes mvn clean package -Popenshift -Dmaven.wagon.http.ssl.insecure=true in the workspace to provision a server with the application deployed to the server.
    2
    Define a command to run the application. This executes ./target/server/bin/standalone.sh -Djboss.host.name=${NODE_NAME} to start the provisioned server within the workspace.
    3
    Define a command to debug the application. This starts the server with the --debug option.
    4
    Define a command to shut down the running server.
    5
    Define a command to deploy the application to OpenShift Container Platform with helm.
    6
    Define a command to undeploy the application from OpenShift Container Platform with helm.

  6. Optionally, configure Visual Studio Code.

    1. Create a directory .vscode for Visual Studio Code configuration.

    2. Navigate to the .vscode directory. 

      $ cd .vscode

    3. Create a file extensions.json to configure the extensions to be installed in Visual Studio Code.

      Note

      You might need to configure a registry to install the extensions. For more information, see Managing IDE extensions in the OpenShift Dev Spaces Administration guide guide. 

      {
  // See https://go.microsoft.com/fwlink/?LinkId=827846
  // for the documentation about the extensions.json format
  "recommendations": [
    "redhat.java",
    "vscjava.vscode-java-debug",
    "vscjava.vscode-java-test",
    "redhat.fabric8-analytics",
    "cnshenj.vscode-task-manager"
      1 
      
  ]
}
      1
      Task manager extension. Provides a custom activity view for the commands in the devfile.

    4. Create a file launch.json to configure a debug session in Visual Studio Code. 

      {
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Attach to running server",
      "request": "attach",
      "hostName": "localhost",
      "port": 5005
    }
  ]
}

  7. Create a file settings.json. 

    {
  "java.server.launchMode": "Standard",
  "editor.codeActionsOnSave": {
  }
}
  8. Push the changes to your repository.

After you create a workspace in OpenShift Dev Spaces, ensure that your application builds correctly. The InnerLoop 01 - Build the application command defined in the devfile runs the Maven package goal to provision a server with the application deployed.

Prerequisites

Procedure

  • To build the application, use the InnerLoop 01 - Build the application command.

    • If you have installed the optional task manager Visual Studio Code extension:

      1. On the Activity Bar, click the Task Manager icon. The list of commands you defined in the devfile are displayed.
      2. Select InnerLoop 01 - Build the application and click the Run Task icon that is displayed.

    • Otherwise:

      1. Press the F1 key.
      2. In the search field that is displayed, enter "run task".
      3. From the results, select Tasks: Run task.
      4. In the search field, enter "devfile".

      5. From the results, select InnerLoop 01 - Build the application.

        The application will start building and the progress will be displayed in the Visual Studio Code terminal.

Verification

  • Inspect the Visual Studio Code terminal output. You should see a build success message like the following: 

    [INFO] Copy deployment /projects/test/helloworld/target/helloworld.war to /projects/test/helloworld/target/server/standalone/deployments/ROOT.war
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  27.889 s
[INFO] Finished at: 2024-04-29T10:31:45Z
[INFO] ------------------------------------------------------------------------

Ensure that your application runs properly in OpenShift Dev Spaces before you deploy it to OpenShift Container Platform. The InnerLoop 02 - Run the application in dev mode command defined in the devfile starts the provisioned server.

Prerequisites

Procedure

  1. To run the application, use the InnerLoop 02 - Run the application in dev mode command .

    • If you have installed the optional task manager Visual Studio Code extension:

      1. On the Activity Bar, click the Task Manager icon. The list of commands you defined in the devfile are displayed.
      2. Select InnerLoop 02 - Run the application in dev mode and click the Run Task icon that is displayed.

    • Otherwise:

      1. Press the F1 key.
      2. In the search field that is displayed, enter "run task".
      3. From the results, select Tasks: Run task.
      4. In the search field, enter "devfile".
      5. From the results, select InnerLoop 02 - Run the application in dev mode.

  2. In the pop-up window that is displayed with the following message, click no:

    A new process is now listening on port 4712 but is listening on interface ::ffff:7f00:1 which is internal. You should change to be remotely available. Would you want to add a redirect for this port so it becomes available ?

  3. In the pop-up window that is displayed with the following message, click Open In New Tab:

    Process http is now listening on port 8080. Open it ?

Verification

  • You will see "Hello World!" in the new tab.

Being able to set breakpoints in the source when debugging is necessary to pause the debugger and examine the call stack or values of variables. You can also add breakpoints to specific lines of the application source code in OpenShift Dev Spaces when debugging. The InnerLoop 03 - Debug the application in dev mode command defined in the devfile starts the provisioned server in debug mode.

Prerequisites

Procedure

  1. To add a breakpoint, click in the left margin of the editor, next to the required line of code. A red dot is displayed in the margin to mark the breakpoint you added.

  2. To debug the application, use the InnerLoop 03 - InnerLoop 03 - Debug the application in dev mode command .

    • If you have installed the optional task manager Visual Studio Code extension:

      1. On the Activity Bar, click the Task Manager icon. The list of commands you defined in the devfile are displayed.
      2. Select InnerLoop 03 - InnerLoop 03 - Debug the application in dev mode and click the Run Task icon that is displayed.

    • Otherwise:

      1. Press the F1 key.
      2. In the search field that is displayed, enter "run task".
      3. From the results, select Tasks: Run task.
      4. In the search field, enter "devfile".
      5. From the results, select InnerLoop 03 - Debug the application in dev mode .

To free up resources, stop the application running in OpenShift Dev Spaces.

Prerequisites

Procedure

  • To stop the server, use the InnerLoop 04 - Shutdown the server command.

    • If you have installed the optional task manager Visual Studio Code extension:

      1. On the Activity Bar, click the Task Manager icon. The list of commands you defined in the devfile are displayed.
      2. Select InnerLoop 04 - Shutdown the server and click the Run Task icon that is displayed.

    • Otherwise:

      1. Press the F1 key.
      2. In the search field that is displayed, enter "run task".
      3. From the results, select Tasks: Run task.
      4. In the search field, enter "devfile".
      5. From the results, select InnerLoop 04 - Shutdown the server.

Deploy your application to OpenShift Container Platform by using helm. The OuterLoop 01 - Deploy Image to OpenShift command defined in the devfile uses helm to deploy the application to OpenShift Container Platform. The helm chart, helm.yaml, defined in your application is used for the deployment.

Prerequisites

Procedure

  • To deploy your application to OpenShift Container Platform, use the OuterLoop 01 - Deploy Image to OpenShift command .

    • If you have installed the optional task manager Visual Studio Code extension:

      1. On the Activity Bar, click the Task Manager icon. The list of commands you defined in the devfile are displayed.
      2. Select OuterLoop 01 - Deploy Image to OpenShift and click the Run Task icon that is displayed.

    • Otherwise:

      1. Press the F1 key.
      2. In the search field that is displayed, enter "run task".
      3. From the results, select Tasks: Run task.
      4. In the search field, enter "devfile".

      5. From the results, select OuterLoop 01 - Deploy Image to OpenShift.

        You get the following output: 

        Your application is building! To follow the build, run:

$ oc get build -w

Note that your Deployment will report "ErrImagePull" and "ImagePullBackOff" until the build is complete. Once the build is complete, your image will be automatically rolled out.

To follow the deployment of your application, run:

$ oc get deployment helloworld -w
 *  Terminal will be reused by tasks, press any key to close it.

Verification

  1. Obtain the application URL. 

    $ oc get route helloworld

  2. Navigate to the URL.

    You get the following output: 

    Hello World!

You can undeploy your application from OpenShift Container Platform in OpenShift Dev Spaces.

Prerequisites

Procedure

  • To undeploy your application from OpenShift Container Platform, use the OuterLoop 02 - Undeploy Image from OpenShift command.

    • If you have installed the optional task manager Visual Studio Code extension:

      1. On the Activity Bar, click the Task Manager icon. The list of commands you defined in the devfile are displayed.
      2. Select OuterLoop 02 - Undeploy Image from OpenShift and click the Run Task icon that is displayed.

    • Otherwise:

      1. Press the F1 key.
      2. In the search field that is displayed, enter "run task".
      3. From the results, select Tasks: Run task.
      4. In the search field, enter "devfile".
      5. From the results, select OuterLoop 02 - Undeploy Image from OpenShift.

After you undeploy the application, it is no longer available for clients.





Revised on 2025-05-08 10:45:47 UTC

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top