diff --git a/helloworld-jms/README.adoc b/helloworld-jms/README.adoc index 4f61b83627..9244ef36d8 100644 --- a/helloworld-jms/README.adoc +++ b/helloworld-jms/README.adoc @@ -695,6 +695,279 @@ This script removes the `test` queue from the `messaging` subsystem in the serve The batch executed successfully ---- +// 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 + + + ${version.server} + + + ROOT.war + ... + + + + + package + + + + + ... + + + +---- +The plugin uses https://github.com/wildfly/wildfly-glow[WildFly Glow] to discover the feature packs and layers required to run the application, and provisions a server containing those layers. + +If you get an error or the server is missing some functionality which cannot be auto-discovered, you can download the https://github.com/wildfly/wildfly-glow/releases/tag[WildFly Glow CLI] and run the following command to see more information about what add-ons are available: + +[source,shell] +---- +wildfly-glow show-add-ons +---- + +[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 [[openshift_incompatibility]]