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!: