ifdef::env-github[]
:artifactId: helloworld
endif::[]
//***********************************************************************************
// Enable the following flag to build README.html files for JBoss EAP product builds.
// Comment it out for WildFly builds.
//***********************************************************************************
//:ProductRelease:
//***********************************************************************************
// Enable the following flag to build README.html files for EAP XP product builds.
// Comment it out for WildFly or JBoss EAP product builds.
//***********************************************************************************
//:EAPXPRelease:
// This is a universal name for all releases
:ProductShortName: JBoss EAP
// Product names and links are dependent on whether it is a product release (CD or JBoss)
// or the WildFly project.
// The "DocInfo*" attributes are used to build the book links to the product documentation
ifdef::ProductRelease[]
// JBoss EAP release
:productName: JBoss EAP
:productNameFull: Red Hat JBoss Enterprise Application Platform
:productVersion: 8.0
:DocInfoProductNumber: {productVersion}
:WildFlyQuickStartRepoTag: 8.0.x
:productImageVersion: 8.0.0
:helmChartName: jboss-eap/eap8
endif::[]
ifdef::EAPXPRelease[]
// JBoss EAP XP release
:productName: JBoss EAP XP
:productNameFull: Red Hat JBoss Enterprise Application Platform expansion pack
:productVersion: 3.0
:DocInfoProductNumber: 7.4
:WildFlyQuickStartRepoTag: XP_3.0.0.GA
:productImageVersion: 3.0
:helmChartName: jboss-eap/eap-xp3
endif::[]
ifdef::ProductRelease,EAPXPRelease[]
:githubRepoUrl: https://github.com/jboss-developer/jboss-eap-quickstarts/
:githubRepoCodeUrl: https://github.com/jboss-developer/jboss-eap-quickstarts.git
:jbossHomeName: EAP_HOME
:DocInfoProductName: Red Hat JBoss Enterprise Application Platform
:DocInfoProductNameURL: red_hat_jboss_enterprise_application_platform
:DocInfoPreviousProductName: jboss-enterprise-application-platform
:quickstartDownloadName: {productNameFull} {productVersion} Quickstarts
:quickstartDownloadUrl: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform&downloadType=distributions
:helmRepoName: jboss-eap
:helmRepoUrl: https://jbossas.github.io/eap-charts/
// END ifdef::ProductRelease,EAPXPRelease[]
endif::[]
ifndef::ProductRelease,EAPXPRelease[]
// WildFly project
:productName: WildFly
:productNameFull: WildFly Application Server
:ProductShortName: {productName}
:jbossHomeName: WILDFLY_HOME
:productVersion: 31
:productImageVersion: 31.0
:githubRepoUrl: https://github.com/wildfly/quickstart/
:githubRepoCodeUrl: https://github.com/wildfly/quickstart.git
:WildFlyQuickStartRepoTag: 31.0.0.Final
:DocInfoProductName: Red Hat JBoss Enterprise Application Platform
:DocInfoProductNameURL: red_hat_jboss_enterprise_application_platform
:DocInfoProductNumber: 8.0
:DocInfoPreviousProductName: jboss-enterprise-application-platform
:helmRepoName: wildfly
:helmRepoUrl: http://docs.wildfly.org/wildfly-charts/
:helmChartName: wildfly/wildfly
// END ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[]
endif::[]
:source: {githubRepoUrl}
// Values for Openshift S2i sections attributes
:CDProductName: {productNameFull} for OpenShift
:CDProductShortName: {ProductShortName} for OpenShift
:CDProductTitle: {CDProductName}
:CDProductNameSentence: Openshift release for {ProductShortName}
:CDProductAcronym: {CDProductShortName}
:CDProductVersion: {productVersion}
:EapForOpenshiftBookName: {productNameFull} for OpenShift
:EapForOpenshiftOnlineBookName: {EapForOpenshiftBookName} Online
:xpaasproduct: {productNameFull} for OpenShift
:xpaasproductOpenShiftOnline: {xpaasproduct} Online
:xpaasproduct-shortname: {CDProductShortName}
:xpaasproductOpenShiftOnline-shortname: {xpaasproduct-shortname} Online
:ContainerRegistryName: Red Hat Container Registry
:EapForOpenshiftBookName: Getting Started with {ProductShortName} for OpenShift Container Platform
:EapForOpenshiftOnlineBookName: Getting Started with {ProductShortName} for OpenShift Online
:OpenShiftOnlinePlatformName: Red Hat OpenShift Container Platform
:OpenShiftOnlineName: Red Hat OpenShift Online
:ImagePrefixVersion: eap80
:ImageandTemplateImportBaseURL: https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates
:ImageandTemplateImportURL: {ImageandTemplateImportBaseURL}/{ImagePrefixVersion}/
:BuildImageStream: jboss-{ImagePrefixVersion}-openjdk11-openshift
:RuntimeImageStream: jboss-{ImagePrefixVersion}-openjdk11-runtime-openshift
// OpenShift repository and reference for quickstarts
:EAPQuickStartRepo: https://github.com/jboss-developer/jboss-eap-quickstarts
:EAPQuickStartRepoRef: 8.0.x
:EAPQuickStartRepoTag: EAP_8.0.0.GA
// Links to the OpenShift documentation
:LinkOpenShiftGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_with_jboss_eap_for_openshift_container_platform/
:LinkOpenShiftOnlineGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_with_jboss_eap_for_openshift_online/
ifdef::EAPXPRelease[]
// Attributes for XP releases
:EapForOpenshiftBookName: {productNameFull} for OpenShift
:EapForOpenshiftOnlineBookName: {productNameFull} for OpenShift Online
:xpaasproduct: {productNameFull} for OpenShift
:xpaasproductOpenShiftOnline: {productNameFull} for OpenShift Online
:xpaasproduct-shortname: {ProductShortName} for OpenShift
:xpaasproductOpenShiftOnline-shortname: {ProductShortName} for OpenShift Online
:ContainerRegistryName: Red Hat Container Registry
:EapForOpenshiftBookName: {productNameFull} for OpenShift
:EapForOpenshiftOnlineBookName: {productNameFull} for OpenShift Online
:ImagePrefixVersion: eap-xp3
:ImageandTemplateImportURL: {ImageandTemplateImportBaseURL}/{ImagePrefixVersion}/
:BuildImageStream: jboss-{ImagePrefixVersion}-openjdk11-openshift
:RuntimeImageStream: jboss-{ImagePrefixVersion}-openjdk11-runtime-openshift
// OpenShift repository and reference for quickstarts
:EAPQuickStartRepoRef: xp-3.0.x
// Links to the OpenShift documentation
:LinkOpenShiftGuide: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/{DocInfoProductNumber}/html/using_eclipse_microprofile_in_jboss_eap/using-the-openshift-image-for-jboss-eap-xp_default
:LinkOpenShiftOnlineGuide: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/{DocInfoProductNumber}/html/using_eclipse_microprofile_in_jboss_eap/using-the-openshift-image-for-jboss-eap-xp_default
endif::[]
ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[]
:ImageandTemplateImportURL: https://raw.githubusercontent.com/wildfly/wildfly-s2i/v{productVersion}.0/
endif::[]
//*************************
// Other values
//*************************
:buildRequirements: Java 11.0 (Java SDK 11) or later and Maven 3.6.0 or later
:jbdsEapServerName: Red Hat JBoss Enterprise Application Platform 7.3
:javaVersion: Jakarta EE 10
ifdef::EAPXPRelease[]
:javaVersion: Eclipse MicroProfile
endif::[]
:githubRepoBranch: master
:guidesBaseUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/
:useEclipseUrl: {guidesBaseUrl}USE_JBDS.adoc#use_red_hat_jboss_developer_studio_or_eclipse_to_run_the_quickstarts
:useEclipseDeployJavaClientDocUrl: {guidesBaseUrl}USE_JBDS.adoc#deploy_and_undeploy_a_quickstart_containing_server_and_java_client_projects
:useEclipseDeployEARDocUrl: {guidesBaseUrl}USE_JBDS.adoc#deploy_and_undeploy_a_quickstart_ear_project
:useProductHomeDocUrl: {guidesBaseUrl}USE_OF_{jbossHomeName}.adoc#use_of_product_home_and_jboss_home_variables
:configureMavenDocUrl: {guidesBaseUrl}CONFIGURE_MAVEN_JBOSS_EAP.adoc#configure_maven_to_build_and_deploy_the_quickstarts
:arquillianTestsDocUrl: {guidesBaseUrl}RUN_ARQUILLIAN_TESTS.adoc#run_the_arquillian_tests
:addUserDocUrl: {guidesBaseUrl}CREATE_USERS.adoc#create_users_required_by_the_quickstarts
:addApplicationUserDocUrl: {guidesBaseUrl}CREATE_USERS.adoc#add_an_application_user
:addManagementUserDocUrl: {guidesBaseUrl}CREATE_USERS.adoc#add_an_management_user
:startServerDocUrl: {guidesBaseUrl}START_JBOSS_EAP.adoc#start_the_jboss_eap_server
:configurePostgresDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#configure_the_postgresql_database_for_use_with_the_quickstarts
:configurePostgresDownloadDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#download_and_install_postgresql
:configurePostgresCreateUserDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#create_a_database_user
:configurePostgresAddModuleDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#add_the_postgres_module_to_the_jboss_eap_server
:configurePostgresDriverDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#configure_the_postgresql_driver_in_the_jboss_eap_server
:configureBytemanDownloadDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#download_and_configure_byteman
:configureBytemanDisableDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#disable_the_byteman_script
:configureBytemanClearDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#clear_the_transaction_object_store
:configureBytemanQuickstartDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#configure_byteman_for_use_with_the_quickstarts
:configureBytemanHaltDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#use_byteman_to_halt_the_application[
:configureBytemanQuickstartsDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#configure_byteman_for_use_with_the_quickstarts
:EESubsystemNamespace: urn:jboss:domain:ee:4.0
:IiopOpenJdkSubsystemNamespace: urn:jboss:domain:iiop-openjdk:2.0
:MailSubsystemNamespace: urn:jboss:domain:mail:3.0
:SingletonSubsystemNamespace: urn:jboss:domain:singleton:1.0
:TransactionsSubsystemNamespace: urn:jboss:domain:transactions:4.0
// LinkProductDocHome: https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/
:LinkProductDocHome: https://access.redhat.com/documentation/en/jboss-enterprise-application-platform-continuous-delivery
:LinkConfigGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/configuration_guide/
:LinkDevelopmentGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/development_guide/
:LinkGettingStartedGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_guide/
:LinkOpenShiftWelcome: https://docs.openshift.com/online/welcome/index.html
:LinkOpenShiftSignup: https://docs.openshift.com/online/getting_started/choose_a_plan.html
:OpenShiftTemplateName: JBoss EAP CD (no https)
:ConfigBookName: Configuration Guide
:DevelopmentBookName: Development Guide
:GettingStartedBookName: Getting Started Guide
:JBDSProductName: Red Hat CodeReady Studio
:JBDSVersion: 12.15
:LinkJBDSInstall: https://access.redhat.com/documentation/en-us/red_hat_codeready_studio/{JBDSVersion}/html-single/installation_guide/
:JBDSInstallBookName: Installation Guide
:LinkJBDSGettingStarted: https://access.redhat.com/documentation/en-us/red_hat_codeready_studio/{JBDSVersion}/html-single/getting_started_with_codeready_studio_tools/
:JBDSGettingStartedBookName: Getting Started with CodeReady Studio Tools
= helloworld: Helloworld Example
:author: Pete Muir
:level: Beginner
:technologies: Servlet
:openshift: true
[abstract]
The `helloworld` quickstart demonstrates the use of Servlet 6 and is a good starting point to verify {productName} is configured correctly.
:standalone-server-type: default
:archiveType: war
== What is it?
The `helloworld` quickstart demonstrates the use of _Servlet 6_ in {productNameFull} {productVersion}.
// Link to the quickstart source
:leveloffset: +1
ifndef::ProductRelease,EAPXPRelease[]
link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source]
endif::[]
:leveloffset!:
// System Requirements
:leveloffset: +1
[[system_requirements]]
= System Requirements
//******************************************************************************
// Include this template to describe the standard system requirements for
// running the quickstarts.
//
// The Forge quickstarts define a `forge-from-scratch` attribute because they
// run entirely in CodeReady Studio and have different requirements .
//******************************************************************************
The application this project produces is designed to be run on {productNameFull} {productVersion} or later.
All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts.
:leveloffset!:
// Use of {jbossHomeName}
:leveloffset: +1
ifdef::requires-multiple-servers[]
[[use_of_jboss_home_name]]
= Use of the {jbossHomeName}_1, {jbossHomeName}_2, and QUICKSTART_HOME Variables
This quickstart requires that you clone your `__{jbossHomeName}__` installation directory and run two servers. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of __{jbossHomeName}__ and __JBOSS_HOME__ Variables].
In the following instructions, replace `__{jbossHomeName}_1__` with the path to your first {productName} server and replace `__{jbossHomeName}_2__` with the path to your second cloned {productName} server.
When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts.
endif::[]
ifdef::optional-domain-or-multiple-servers[]
[[use_of_jboss_home_name]]
= Use of the {jbossHomeName}_1, {jbossHomeName}_2, and QUICKSTART_HOME Variables
When deploying this quickstart to a managed domain, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of __{jbossHomeName}__ and __JBOSS_HOME__ Variables].
When deploying this quickstart to multiple standalone servers, this quickstart requires that you clone your `__{jbossHomeName}__` installation directory and run two servers. In the following instructions, replace `__{jbossHomeName}_1__` with the path to your first {productName} server and replace `__{jbossHomeName}_2__` with the path to your second cloned {productName} server.
When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts.
endif::[]
ifndef::requires-multiple-servers,optional-domain-or-multiple-servers[]
[[use_of_jboss_home_name]]
= Use of the {jbossHomeName} and QUICKSTART_HOME Variables
In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of __{jbossHomeName}__ and __JBOSS_HOME__ Variables].
When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts.
endif::[]
:leveloffset!:
// build and run with standard server distribution
[[build_and_run_the_quickstart_with_server_dist]]
== Building and running the quickstart application with a {productName} server distribution
// Start the {productName} Standalone Server
:leveloffset: +2
[[start_the_eap_standalone_server]]
= Start the {productName} Standalone Server
//******************************************************************************
// Include this template if your quickstart requires a normal start of a single
// standalone server.
//
// You must define the `standalone-server-type`. Supported values are:
// default
// full
// full-ha
// ha
// custom
//
// * For mobile applications, you can define the `mobileApp` variable in the
// `README.adoc` file to add `-b 0.0.0.0` to the command line. This allows
// external clients, such as phones, tablets, and desktops, to connect
// to the application through through your local network
// ::mobileApp: {artifactId}-service
//
//******************************************************************************
//******************************************************************************
// This template sets attributes for the different standalone server profiles.
//
// You must define the `standalone-server-type`. Supported values are:
// default
// full
// full-ha
// ha
// microprofile
// custom
//******************************************************************************
// Standalone server with the default profile.
ifeval::["{standalone-server-type}"=="default"]
:serverProfile: default profile
:configFileName: standalone/configuration/standalone.xml
:serverArguments:
endif::[]
// Standalone server with the full profile.
ifeval::["{standalone-server-type}"=="full"]
:serverProfile: full profile
:configFileName: standalone/configuration/standalone-full.xml
:serverArguments: -c standalone-full.xml
endif::[]
// Standalone server with the full HA profile.
ifeval::["{standalone-server-type}"=="full-ha"]
:serverProfile: full HA profile
:configFileName: standalone/configuration/standalone-full-ha.xml
:serverArguments: -c standalone-full-ha.xml
endif::[]
// Start the standalone server with the HA profile.
ifeval::["{standalone-server-type}"=="ha"]
:serverProfile: HA profile
:configFileName: standalone/configuration/standalone-ha.xml
:serverArguments: -c standalone-ha.xml
endif::[]
// Start the standalone server with the Eclipse MicroProfile profile.
ifeval::["{standalone-server-type}"=="microprofile"]
:serverProfile: MicroProfile profile
:configFileName: standalone/configuration/standalone-microprofile.xml
:serverArguments: -c standalone-microprofile.xml
endif::[]
// Standalone server with the custom profile.
// NOTE: This profile requires that you define the `serverArguments` variable
// within the quickstart README.adoc file. For example:
// :serverArguments: --server-config=../../docs/examples/configs/standalone-xts.xml
ifeval::["{standalone-server-type}"=="custom"]
:serverProfile: custom profile
endif::[]
// If there is no match, use the default profile.
ifndef::serverProfile[]
:standalone-server-type: default
:serverProfile: default profile
:configFileName: standalone/configuration/standalone.xml
:serverArguments:
endif::serverProfile[]
. Open a terminal and navigate to the root of the {productName} directory.
. Start the {productName} server with the {serverProfile} by typing the following command.
+
ifdef::uses-jaeger[]
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1__ __{jbossHomeName}__/bin/standalone.sh {serverArguments}
----
endif::[]
ifndef::uses-jaeger[]
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/standalone.sh {serverArguments}
----
endif::[]
+
NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script.
ifdef::mobileApp[]
+
Adding `-b 0.0.0.0` to the above command allows external clients, such as phones, tablets, and desktops, to connect through your local network. For example:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/standalone.sh {serverArguments} -b 0.0.0.0
----
endif::[]
:leveloffset!:
// Build and Deploy the Quickstart
:leveloffset: +2
[[build_and_deploy_the_quickstart]]
= Build and Deploy the Quickstart
//******************************************************************************
// Include this template if your quickstart does a normal deployment of a archive.
//
// * Define the `archiveType` variable in the quickstart README file.
// Supported values:
// :archiveType: ear
// :archiveType: war
// :archiveType: jar
//
// * To override the archive name, which defaults to the {artifactId),
// define the `archiveName` variable, for example:
// :archiveName: {artifactId}-service
//
// * To override the archive output directory,
// define the `archiveDir` variable, for example:
// :archiveDir: ear/target
//
// * To override the Maven command, define the `mavenCommand` variable,
// for example:
// :mavenCommand: clean install wildfly:deploy
//******************************************************************************
// The archive name defaults to the artifactId if not overridden
ifndef::archiveName[]
:archiveName: {artifactId}
endif::archiveName[]
// The archive type defaults to war if not overridden
ifndef::archiveType[]
:archiveType: war
endif::archiveType[]
// Define the archive file name as the concatenation of "archiveName" + "." + "archiveType+
:archiveFileName: {archiveName}.{archiveType}
// If they have not defined the target archive directory, make it the default for the archive type.
ifndef::archiveDir[]
ifeval::["{archiveType}"=="ear"]
:archiveDir: {artifactId}/ear/target
endif::[]
ifeval::["{archiveType}"=="war"]
:archiveDir: {artifactId}/target
endif::[]
ifeval::["{archiveType}"=="jar"]
:archiveDir: {artifactId}/target
endif::[]
endif::archiveDir[]
ifndef::mavenCommand[]
ifeval::["{archiveType}"=="ear"]
:mavenCommand: clean install
endif::[]
ifeval::["{archiveType}"=="war"]
:mavenCommand: clean package
endif::[]
ifeval::["{archiveType}"=="jar"]
:mavenCommand: clean install
endif::[]
endif::mavenCommand[]
. Make sure {productName} server is started.
. Open a terminal and navigate to the root directory of this quickstart.
ifdef::reactive-messaging[]
. Run this command to enable the MicroProfile Reactive Messaging functionality on the server
+
[source,subs="attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-reactive-messaging.cli
----
endif::reactive-messaging[]
. Type the following command to build the quickstart.
+
[source,subs="attributes+",options="nowrap"]
----
$ mvn {mavenCommand}
----
. Type the following command to deploy the quickstart.
+
[source,subs="attributes+",options="nowrap"]
----
$ mvn wildfly:deploy
----
This deploys the `{archiveDir}/{archiveFileName}` to the running instance of the server.
You should see a message in the server log indicating that the archive deployed successfully.
:leveloffset!:
=== Access the Application
The application will be running at the following URL: http://localhost:8080/{artifactId}/.
// Server Distribution Testing
:leveloffset: +2
[[run_the_integration_tests_with_server_distribution]]
= Run the Integration Tests
ifndef::integrationTestsDirectory[:integrationTestsDirectory: src/test/]
ifndef::extraStandardDistTestParams[:extraStandardDistTestParams: ]
This quickstart includes integration tests, which are located under the `{integrationTestsDirectory}` directory. The integration tests verify that the quickstart runs correctly when deployed on the server.
Follow these steps to run the integration tests.
. Make sure {productName} server is started.
. Make sure the quickstart is deployed.
. Type the following command to run the `verify` goal with the `integration-testing` profile activated.
+
[source,subs="attributes+",options="nowrap"]
----
$ mvn verify -Pintegration-testing {extraStandardDistTestParams}
----
:leveloffset!:
// Undeploy the Quickstart
:leveloffset: +2
[[undeploy_the_quickstart]]
= Undeploy the Quickstart
//*******************************************************************************
// Include this template if your quickstart does a normal undeployment of an archive.
//*******************************************************************************
When you are finished testing the quickstart, follow these steps to undeploy the archive.
. Make sure {productName} server is started.
. Open a terminal and navigate to the root directory of this quickstart.
. Type this command to undeploy the archive:
+
[source,options="nowrap"]
----
$ mvn wildfly:undeploy
----
:leveloffset!:
// Build and run sections for other environments/builds
ifndef::ProductRelease,EAPXPRelease[]
:leveloffset: +1
[[build_and_run_the_quickstart_with_provisioned_server]]
= Building and running the quickstart application with provisioned {productName} server
ifndef::mavenServerProvisioningCommand[]
ifeval::["{archiveType}"=="ear"]
:mavenServerProvisioningCommand: clean install
endif::[]
ifeval::["{archiveType}"=="war"]
:mavenServerProvisioningCommand: clean package
endif::[]
ifeval::["{archiveType}"=="jar"]
:mavenServerProvisioningCommand: clean install
endif::[]
endif::mavenServerProvisioningCommand[]
ifndef::deploymentTargetDir[]
ifndef::deploymentDir[:deploymentTargetDir: target]
ifdef::deploymentDir[:deploymentTargetDir: {deploymentDir}/target]
endif::deploymentTargetDir[]
Instead of using a standard {productName} server distribution, you can alternatively provision a {productName} server to deploy and run the quickstart, by activating the Maven profile named `provisioned-server` when building the quickstart:
[source,subs="attributes+",options="nowrap"]
----
$ mvn {mavenServerProvisioningCommand} -Pprovisioned-server
----
The provisioned {productName} server, with the quickstart deployed, can then be found in the `{deploymentTargetDir}/server` directory, and its usage is similar to a standard server distribution, with the simplification that there is never the need to specify the server configuration to be started.
ifdef::addQuickstartUser[]
The quickstart user should be added before running the provisioned server:
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ {deploymentTargetDir}/server/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command}
----
[NOTE]
====
For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script.
====
endif::[]
ifdef::addQuickstartAdmin[]
The quickstart admin should be added before running the provisioned server:
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ {deploymentTargetDir}/server/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' {admin-group-command}
----
[NOTE]
====
For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script.
====
endif::[]
The server provisioning functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the quickstart `pom.xml`:
[source,xml,subs="attributes+"]
----
provisioned-server
org.wildfly.plugins
wildfly-maven-plugin
org.wildfly:wildfly-galleon-pack:${version.server}
...
ROOT.war
package
...
----
[NOTE]
====
Since the plugin configuration above deploys quickstart on root web context of the provisioned server, the URL to access the application should not have the `/{artifactId}` path segment after `HOST:PORT`.
====
// Server Provisioning Testing
:leveloffset: +1
[[run_the_integration_tests_with_provisioned_server_]]
= Run the Integration Tests with a provisioned server
//******************************************************************************
// This template sets attributes for the different standalone server profiles.
//
// You must define the `standalone-server-type`. Supported values are:
// default
// full
// full-ha
// ha
// microprofile
// custom
//******************************************************************************
// Standalone server with the default profile.
ifeval::["{standalone-server-type}"=="default"]
:serverProfile: default profile
:configFileName: standalone/configuration/standalone.xml
:serverArguments:
endif::[]
// Standalone server with the full profile.
ifeval::["{standalone-server-type}"=="full"]
:serverProfile: full profile
:configFileName: standalone/configuration/standalone-full.xml
:serverArguments: -c standalone-full.xml
endif::[]
// Standalone server with the full HA profile.
ifeval::["{standalone-server-type}"=="full-ha"]
:serverProfile: full HA profile
:configFileName: standalone/configuration/standalone-full-ha.xml
:serverArguments: -c standalone-full-ha.xml
endif::[]
// Start the standalone server with the HA profile.
ifeval::["{standalone-server-type}"=="ha"]
:serverProfile: HA profile
:configFileName: standalone/configuration/standalone-ha.xml
:serverArguments: -c standalone-ha.xml
endif::[]
// Start the standalone server with the Eclipse MicroProfile profile.
ifeval::["{standalone-server-type}"=="microprofile"]
:serverProfile: MicroProfile profile
:configFileName: standalone/configuration/standalone-microprofile.xml
:serverArguments: -c standalone-microprofile.xml
endif::[]
// Standalone server with the custom profile.
// NOTE: This profile requires that you define the `serverArguments` variable
// within the quickstart README.adoc file. For example:
// :serverArguments: --server-config=../../docs/examples/configs/standalone-xts.xml
ifeval::["{standalone-server-type}"=="custom"]
:serverProfile: custom profile
endif::[]
// If there is no match, use the default profile.
ifndef::serverProfile[]
:standalone-server-type: default
:serverProfile: default profile
:configFileName: standalone/configuration/standalone.xml
:serverArguments:
endif::serverProfile[]
ifndef::mavenServerProvisioningCommand[]
ifeval::["{archiveType}"=="ear"]
:mavenServerProvisioningCommand: clean install
endif::[]
ifeval::["{archiveType}"=="war"]
:mavenServerProvisioningCommand: clean package
endif::[]
ifeval::["{archiveType}"=="jar"]
:mavenServerProvisioningCommand: clean install
endif::[]
endif::mavenServerProvisioningCommand[]
ifndef::deploymentTargetDir[]
ifndef::deploymentDir[:deploymentTargetDir: target]
ifdef::deploymentDir[:deploymentTargetDir: {deploymentDir}/target]
endif::deploymentTargetDir[]
ifndef::server_provisioning_server_host[]
:server_provisioning_server_host: http://localhost:8080
endif::server_provisioning_server_host[]
ifndef::extraStartParams[:extraStartParams: ]
ifndef::extraProvisioningTestParams[:extraProvisioningTestParams: ]
The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a provisioned server.
Follow these steps to run the integration tests.
. Make sure the server is provisioned.
+
[source,subs="attributes+",options="nowrap"]
----
$ mvn {mavenServerProvisioningCommand} -Pprovisioned-server
----
ifdef::addQuickstartUser[]
. Add the quickstart user:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ {deploymentTargetDir}/server/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command}
----
endif::[]
ifdef::addQuickstartAdmin[]
. Add the quickstart admin:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ {deploymentTargetDir}/server/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' {admin-group-command}
----
[NOTE]
====
For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script.
====
endif::[]
. Start the {productName} provisioned server, this time using the {productName} Maven Plugin, which is recommended for testing due to simpler automation. The path to the provisioned server should be specified using the `jbossHome` system property.
+
ifndef::deploymentDir[]
[source,subs="attributes+",options="nowrap"]
----
$ mvn wildfly:start -DjbossHome=target/server {extraStartParams}
----
endif::[]
ifdef::deploymentDir[]
[source,subs="attributes+",options="nowrap"]
----
$ mvn -f {deploymentDir}/pom.xml wildfly:start -DjbossHome={deploymentDir}/target/server {extraStartParams}
----
endif::[]
. Type the following command to run the `verify` goal with the `integration-testing` profile activated, and specifying the quickstart's URL using the `server.host` system property, which for a provisioned server by default is `{server_provisioning_server_host}`.
+
[source,subs="attributes+",options="nowrap"]
----
$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} {extraProvisioningTestParams}
----
. Shutdown the {productName} provisioned server, this time using the {productName} Maven Plugin too.
+
ifndef::deploymentDir[]
[source,subs="attributes+",options="nowrap"]
----
$ mvn wildfly:shutdown
----
endif::[]
ifdef::deploymentDir[]
[source,subs="attributes+",options="nowrap"]
----
$ mvn -f {deploymentDir}/pom.xml wildfly:shutdown
----
endif::[]
:leveloffset: 1
:leveloffset!:
endif::[]
:leveloffset: +1
ifndef::helm-app-name[]
:helm-app-name: {artifactId}
endif::helm-app-name[]
[[build_and_run_the_quickstart_on_openshift]]
= Building and running the quickstart application with OpenShift
// The openshift profile
:leveloffset: +1
[[build-the-quickstart-for-openshift]]
== Build the {productName} Source-to-Image (S2I) Quickstart to OpenShift with Helm Charts
On OpenShift, the S2I build with Apache Maven uses an `openshift` Maven profile to provision a {productName} server, deploy and run the quickstart in OpenShift environment.
ifndef::ProductRelease,EAPXPRelease[]
The server provisioning functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the quickstart `pom.xml`:
endif::[]
ifdef::ProductRelease,EAPXPRelease[]
The server provisioning functionality is provided by the EAP Maven Plugin, and you may find its configuration in the quickstart `pom.xml`:
endif::[]
// Render XML Snippet of openshift Maven profile...
ifndef::ProductRelease[]
// ... for WildFly
[source,xml,subs="attributes+"]
----
openshift
org.wildfly.plugins
wildfly-maven-plugin
org.wildfly:wildfly-galleon-pack:${version.server}
org.wildfly.cloud:wildfly-cloud-galleon-pack:${version.pack.cloud}
...
ROOT.war
package
...
----
endif::[]
ifdef::ProductRelease[]
ifndef::EAPXPRelease[]
// ... for EAP
[source,xml,subs="attributes+"]
----
openshift
org.jboss.eap.plugins
eap-maven-plugin
...
org.jboss.eap:wildfly-ee-galleon-pack
org.jboss.eap.cloud:eap-cloud-galleon-pack
...
ROOT.war
package
...
----
endif::[]
ifdef::EAPXPRelease[]
// ... for EAP XP
[source,xml,subs="attributes+"]
----
openshift
org.jboss.eap.plugins
eap-maven-plugin
...
org.jboss.eap.xp:wildfly-galleon-pack
org.jboss.eap.cloud:eap-cloud-galleon-pack
...
ROOT.war
package
...
----
endif::[]
endif::[]
ifndef::ProductRelease,EAPXPRelease[]
You may note that unlike the `provisioned-server` profile it uses the cloud feature pack which enables a configuration tuned for OpenShift environment.
endif::[]
ifdef::ProductRelease,EAPXPRelease[]
You may note that the cloud feature pack is used, this enables a configuration tuned for OpenShift environment.
endif::[]
ifdef::EAPXPRelease[]
[NOTE]
====
Previous {productName} releases used the WildFly JAR Maven Plugin to package the quickstart in a Bootable JAR, when deploying it on OpenShift, and while that's still supported it's no longer recommended.
====
endif::[]
:leveloffset: 1
// Getting Started with Helm
:leveloffset: +1
[[getting_started_with_helm]]
= Getting Started with {xpaasproduct-shortname} and Helm Charts
This section contains the basic instructions to build and deploy this quickstart to {xpaasproduct-shortname} or {xpaasproductOpenShiftOnline-shortname} using Helm Charts.
[[prerequisites_helm_openshift]]
== Prerequisites
* You must be logged in OpenShift and have an `oc` client to connect to OpenShift
* https://helm.sh[Helm] must be installed to deploy the backend on OpenShift.
Once you have installed Helm, you need to add the repository that provides Helm Charts for {productName}.
ifndef::ProductRelease,EAPXPRelease[]
[source,options="nowrap"]
----
$ helm repo add wildfly https://docs.wildfly.org/wildfly-charts/
"wildfly" has been added to your repositories
$ helm search repo wildfly
NAME CHART VERSION APP VERSION DESCRIPTION
wildfly/wildfly ... ... Build and Deploy WildFly applications on OpenShift
wildfly/wildfly-common ... ... A library chart for WildFly-based applications
----
endif::[]
ifdef::ProductRelease[]
[source,options="nowrap",subs="+attributes"]
----
$ helm repo add jboss-eap https://jbossas.github.io/eap-charts/
"jboss-eap" has been added to your repositories
$ helm search repo jboss-eap
NAME CHART VERSION APP VERSION DESCRIPTION
{helmChartName} ... ... A Helm chart to build and deploy EAP {productVersion} applications
----
endif::[]
ifdef::EAPXPRelease[]
[source,options="nowrap",subs="+attributes"]
----
$ helm repo add jboss-eap https://jbossas.github.io/eap-charts/
"jboss-eap" has been added to your repositories
$ helm search repo jboss-eap
NAME CHART VERSION APP VERSION DESCRIPTION
{helmChartName} ... ... A Helm chart to build and deploy EAP XP {productVersion} applications
----
endif::[]
:leveloffset: 1
ifdef::helm-install-prerequisites[]
// Additional steps needed before deploying in Helm
[[deploy_helm_prerequisites]]
include::{helm-install-prerequisites}[leveloffset=+1]
endif::helm-install-prerequisites[]
//Prepare Helm for Quickstart Deployment
:leveloffset: +1
ifeval::[{useHelmChartDir} == true]
:helm_chart_values: charts
endif::[]
ifndef::useHelmChartDir[]
:helm_chart_values: -f charts/helm.yaml {helmChartName}
endif::[]
[[deploy_helm]]
== Deploy the {ProductShortName} Source-to-Image (S2I) Quickstart to OpenShift with Helm Charts
Log in to your OpenShift instance using the `oc login` command.
The backend will be built and deployed on OpenShift with a Helm Chart for {productName}.
Navigate to the root directory of this quickstart and run the following command:
[source,options="nowrap",subs="+attributes"]
----
$ helm install {helm-app-name} {helm_chart_values} --wait --timeout=10m0s
NAME: {helm-app-name}
...
STATUS: deployed
REVISION: 1
----
This command will return once the application has successfully deployed. In case of a timeout, you can check the status of the application with the following command in another terminal:
[source,options="nowrap",subs="+attributes"]
----
oc get deployment {helm-app-name}
----
The Helm Chart for this quickstart contains all the information to build an image from the source code using S2I on Java 17:
ifndef::requires-http-route[]
ifdef::useHelmChartDir[]
[source,yaml]
----
include::{docdir}/charts/Chart.yaml[]
----
endif::useHelmChartDir[]
ifndef::useHelmChartDir[]
[source,yaml]
----
build:
uri: https://github.com/wildfly/quickstart.git
ref: main
contextDir: helloworld
deploy:
replicas: 1
----
endif::useHelmChartDir[]
endif::requires-http-route[]
ifdef::requires-http-route[]
[source,options="nowrap",subs="+attributes"]
----
build:
uri: {githubRepoCodeUrl}
ref: {WildFlyQuickStartRepoTag}
contextDir: {artifactId}
deploy:
replicas: 1
route:
tls:
enabled: false
----
endif::requires-http-route[]
This will create a new deployment on OpenShift and deploy the application.
If you want to see all the configuration elements to customize your deployment you can use the following command:
[source,options="nowrap",subs="+attributes"]
----
$ helm show readme {helmChartName}
----
Get the URL of the route to the deployment.
[source,options="nowrap",subs="+attributes"]
----
$ oc get route {helm-app-name} -o jsonpath="{.spec.host}"
----
Access the application in your web browser using the displayed URL.
[NOTE]
====
The Maven profile named `openshift` is used by the Helm chart to provision the server with the quickstart deployed on the root web context, and thus the application should be accessed with the URL without the `/{artifactId}` path segment after `HOST:PORT`.
====
ifdef::post-helm-install-actions[]
include::{post-helm-install-actions}[leveloffset=+1]
endif::post-helm-install-actions[]
:leveloffset: 1
// Testing on Openshift
:leveloffset: +1
[[run_the_integration_tests_with_openshift]]
= Run the Integration Tests with OpenShift
The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with the quickstart running on OpenShift.
[NOTE]
====
The integration tests expect a deployed application, so make sure you have deployed the quickstart on OpenShift before you begin.
====
ifdef::extra-openshift-testing-actions[]
include::{extra-openshift-testing-actions}[leveloffset=+1]
endif::extra-openshift-testing-actions[]
ifndef::extra-openshift-test-arguments[:extra-openshift-test-arguments:]
Run the integration tests using the following command to run the `verify` goal with the `integration-testing` profile activated and the proper URL:
ifndef::requires-http-route[]
[source,options="nowrap",subs="+attributes"]
----
$ mvn verify -Pintegration-testing -Dserver.host=https://$(oc get route {helm-app-name} --template='{{ .spec.host }}') {extra-openshift-test-arguments}
----
endif::requires-http-route[]
ifdef::requires-http-route[]
[source,options="nowrap",subs="+attributes"]
----
$ mvn verify -Pintegration-testing -Dserver.host=http://$(oc get route {helm-app-name} --template='{{ .spec.host }}') {extra-openshift-test-arguments}
----
endif::requires-http-route[]
[NOTE]
====
The tests are using SSL to connect to the quickstart running on OpenShift. So you need the certificates to be trusted by the machine the tests are run from.
====
:leveloffset: 1
//Prepare Helm for Quickstart Deployment
:leveloffset: +1
[[undeploy_helm]]
== Undeploy the {ProductShortName} Source-to-Image (S2I) Quickstart from OpenShift with Helm Charts
[source,options="nowrap",subs="+attributes"]
----
$ helm uninstall {helm-app-name}
----
:leveloffset: 1
:leveloffset!: