From 3312dd7f2d5c0037511258b3db59c04f290cae02 Mon Sep 17 00:00:00 2001 From: emmartins Date: Fri, 17 May 2024 13:01:09 +0000 Subject: [PATCH] Commit from GitHub Actions (WildFly Quickstarts Update 'README.adoc's) --- messaging-clustering-singleton/README.adoc | 258 +++++++++++++++------ 1 file changed, 185 insertions(+), 73 deletions(-) diff --git a/messaging-clustering-singleton/README.adoc b/messaging-clustering-singleton/README.adoc index fd2577e719..2455ac9bc8 100644 --- a/messaging-clustering-singleton/README.adoc +++ b/messaging-clustering-singleton/README.adoc @@ -247,6 +247,11 @@ Here, you can see that only one of the MDBs, `HelloWorldTopicMDB`, is associated If a delivery group is used in conjunction with singleton, as is the case of this quickstart, the MDB will be active in the singleton provider node only if that node has `delivery-group` enabled. If not, the MDB will be inactive in that node and all remainder nodes of the cluster. +//************************************************* +// Product Release content only +//************************************************* + + // Link to the quickstart source :leveloffset: +1 @@ -255,6 +260,11 @@ link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{arti endif::[] :leveloffset!: + +== Running the Quickstart + +This quickstart demonstrates its functionalities on <<_running_in_a_bare_metal_environment, bare metal>> and using {productName} Maven plugin. + // System Requirements :leveloffset: +1 @@ -309,7 +319,9 @@ endif::[] :leveloffset!: -== Build the Project +== Running in a bare metal environment + +=== Build the Project Follow these steps to build the project without deploying it. @@ -318,15 +330,15 @@ Follow these steps to build the project without deploying it. + [source,options="nowrap"] ---- -$ mvn clean install +$ mvn clean package ---- -== Configure the Server and Deploy the Quickstart +=== Configure the Server and Deploy the Quickstart You can choose to configure and deploy this quickstart to a xref:configure_the_server_and_deploy_the_quickstart_to_a_managed_domain[managed domain] or to a xref:configure_the_server_and_deploy_the_quickstart_to_a_standalone_server[standalone server]. The sections below describe how to configure and start the server for each configuration. [[configure_the_server_and_deploy_the_quickstart_to_a_managed_domain]] -=== Configure the Server and Deploy the Quickstart to a Managed Domain +==== Configure the Server and Deploy the Quickstart to a Managed Domain You configure the server by running the `install-domain.cli` script provided in the root directory of this quickstart. @@ -384,7 +396,7 @@ NOTE: For Windows, use the `__{jbossHomeName}__\bin\domain.bat` script. :leveloffset!: -==== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI +===== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI . Review the `install-domain.cli` file located in the root of this quickstart directory. This script creates the server group and servers and configures messaging clustering for testing this quickstart. You will note it does the following: @@ -427,14 +439,14 @@ The batch executed successfully ---- [[configure_the_server_and_deploy_the_quickstart_to_a_standalone_server]] -=== Configure the Server and Deploy the Quickstart to a Standalone Server +==== Configure the Server and Deploy the Quickstart to a Standalone Server If you choose to use standalone servers rather than a managed domain, you need two instances of the application server. The second server must be started with a port offset parameter provided to the startup script as `-Djboss.socket.binding.port-offset=100`. Since both application servers must be configured in the same way, you must configure the first server and then clone it. // Back Up the {productName} Standalone Server Configuration -:leveloffset: +3 +:leveloffset: +4 [[back_up_standalone_server_configuration]] = Back Up the {productName} Standalone Server Configuration @@ -516,7 +528,7 @@ After you have completed testing this quickstart, you can replace this file to r :leveloffset!: // Start the {productName} Standalone Server -:leveloffset: +3 +:leveloffset: +4 [[start_the_eap_standalone_server]] = Start the {productName} Standalone Server @@ -632,14 +644,13 @@ endif::[] :leveloffset!: -==== Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI +===== Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI . Review the `install-standalone.cli` file located in the root of this quickstart directory. This script configures clustering for a standalone server. You will note it does the following: ** Because the console is disabled by default in the Full HA profile, it enables console logging to allow you to view the quickstart output. ** Enables clustering and sets a cluster password. ** Creates a delivery group named `my-mdb-delivery-group`, with initial active value set to `true`. -** Deploys the `{artifactId}.war` archive. ** Reloads the server configuration. . Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server: + @@ -659,7 +670,18 @@ The batch executed successfully process-state: reload-required ---- -==== Clone the {productName} Directory +. 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. + +===== Clone the {productName} Directory After you have successfully configured the server, you must make a copy of this {productName} directory structure to use for the second server. @@ -674,7 +696,7 @@ __{jbossHomeName}_2__/standalone/data/activemq/journal __{jbossHomeName}_2__/standalone/data/activemq/largemessages ---- -==== Start the {productName} Standalone Servers with the Full HA Profile +===== Start the {productName} Standalone Servers with the Full HA Profile Use the following commands to start the standalone servers with the full HA profile. @@ -686,9 +708,9 @@ $ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-full-ha.xml -Djboss.sock NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. -== Access the Application +=== Access the Application -=== Access the Application Running in a Managed Domain +==== Access the Application Running in a Managed Domain The application will be running at the following URL: http://localhost:9080/{artifactId}/HelloWorldMDBServletClient. @@ -696,7 +718,7 @@ It will send some messages to the queue. To send messages to the topic, use the following URL: http://localhost:9080/{artifactId}/HelloWorldMDBServletClient?topic -=== Access the Application Running in a Standalone Server +==== Access the Application Running in a Standalone Server The application will be running at the following URL: http://localhost:8080/{artifactId}/HelloWorldMDBServletClient. @@ -704,7 +726,7 @@ It will send some messages to the queue. To send messages to the topic, use the following URL: http://localhost:8080/{artifactId}/HelloWorldMDBServletClient?topic -== Investigate the Server Console Output +=== Investigate the Server Console Output Review the messages in both {productName} server consoles or logs. @@ -732,7 +754,7 @@ INFO [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-9 (ActiveM You will notice that only one of the nodes, elected as the singleton provider node, will be receiving the messages. For that, check both servers, only one will contain the received message log entries. -== Server Log: Expected Warnings and Errors +=== Server Log: Expected Warnings and Errors You will see the following warnings in the server logs. You can ignore these warnings as they are intended for production servers. @@ -744,7 +766,7 @@ WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImp WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) ---- -== Electing a New Singleton Provider Server +=== Electing a New Singleton Provider Server If you reboot the singleton server node, the other node will be elected the new singleton provider, and will start receiving the MDB messages instead. @@ -791,22 +813,22 @@ at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:61 at java.lang.Thread.run(Thread.java:745) ---- -=== Rebooting the Singleton Provider Server Node in a Managed Domain +==== Rebooting the Singleton Provider Server Node in a Managed Domain Run the following command, replacing `__{jbossHomeName}__` with the path to your server, and replacing `NODE_X` in the script name with either `node1` or `node2`, depending on whether the current singleton provider is `node1` or `node2`. [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli ---- NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. -=== Rebooting the Singleton Provider Server Node in a Standalone Server +==== Rebooting the Singleton Provider Server Node in a Standalone Server Stop the provider server and restart it again, using the same command you used to start the server initially. -== Disable and Enable the Delivery Group +=== Disable and Enable the Delivery Group To disable the delivery group "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-domain.cli` or `disable-delivery-group-standalone.cli` script, located in the root directory of this quickstart. Follow the instructions in the next sections, depending on the server configuration you choose to run. @@ -814,13 +836,13 @@ After disabling the delivery group, try sending messages to the topic, You shoul Next, enable the delivery group using the appropriate `enable-delivery-group-domain.cli` or `enable-delivery-group-standalone.cli` script, also located in the root directory of this quickstart, so that the topic messages can be delivered again. -=== Disable and Enable Delivery Group in a Managed Domain +==== Disable and Enable Delivery Group in a Managed Domain To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-domain.cli` script, replacing `__{jbossHomeName}__` with the path to your server: [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli ---- NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. @@ -829,18 +851,18 @@ Similarly, to enable the delivery group, run the `enable-delivery-group-domain.c [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli ---- NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. -=== Disable and Enable Delivery Group in a Standalone Server +==== Disable and Enable Delivery Group in a Standalone Server To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-standalone.cli` script on both servers, replacing `__{jbossHomeName}__` with the path to your server: [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file==disable-delivery-group-standalone.cli +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file==disable-delivery-group-standalone.cli $ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli ---- @@ -851,48 +873,97 @@ Similarly, to enable the delivery group, run the `enable-delivery-group-standalo [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file==enable-delivery-group-standalone.cli +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file==enable-delivery-group-standalone.cli $ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect controller=localhost:10090 --file=enable-delivery-group-standalone.cli ---- NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. -== Undeploy the Archive + +// 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!: + +==== Run the Integration Tests in a Managed Domain + +The integration tests may also be run with the domain server by typing the following command. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host="http://localhost:9080/messaging-clustering-singleton" +---- + +=== Undeploy the Archive When you are finished testing, use the following instructions to undeploy the quickstart. -=== Undeploy the quickstart in a Managed Domain +==== Undeploy the quickstart in a Managed Domain . xref:start_eap_managed_domain[Start the {productName} managed domain] as described above. . Open a new terminal, navigate to the root directory of this quickstart, and run the `undeploy-domain.cli` script, replacing `__{jbossHomeName}__` with the path to your server: + [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file==undeploy-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file==undeploy-domain.cli ---- NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. -=== Undeploy the quickstart in a Standalone Server +==== Undeploy the quickstart in a Standalone Server +:leveloffset: +4 + +[[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. -. xref:start_the_eap_standalone_server[Start the {productName} server with the standalone full HA profile] as described above. -. Open a terminal, navigate to the root directory of this quickstart, and run the `undeploy-standalone.cli` script, replacing `__{jbossHomeName}_1__` and `__{jbossHomeName}_2__` with the path to the appropriate server: +. 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,subs="+quotes,attributes+",options="nowrap"] +[source,options="nowrap"] ---- -$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file==undeploy-standalone.cli -$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect controller=localhost:10090 --file==undeploy-standalone.cli +$ mvn wildfly:undeploy ---- -NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. +:leveloffset!: + +Repeat the last step for the second server: -== Restore the Server Configuration +[source,sh,options="nowrap"] +---- +$ mvn wildfly:undeploy -Dwildfly.port=10090 +---- -=== Restore the Domain Server Configuration +=== Restore the Server Configuration -You can Restore the domain configuration by manually restoring the backup configuration files or by running the management CLI script. +==== Restore the Domain Server Configuration -==== Restore the Domain Server Configuration Manually +You can restore the domain configuration by manually restoring the backup configuration files or by running the management CLI script. + +===== Restore the Domain Server Configuration Manually IMPORTANT: This method ensures the server is restored to its prior configuration. @@ -900,7 +971,7 @@ IMPORTANT: This method ensures the server is restored to its prior configuration . Restore the `__{jbossHomeName}__/domain/configuration/domain.xml` and `__{jbossHomeName}__/domain/configuration/host.xml` files with the back-up copies of the files. Make sure you replace `__{jbossHomeName}__` with the path to your server. -==== Restore the Domain Server Configuration by Running the Management CLI Script +===== Restore the Domain Server Configuration by Running the Management CLI Script IMPORTANT: This script returns the server to a default configuration and the result might not match the server configuration prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to manually restore the configuration to its previous state. @@ -910,7 +981,7 @@ IMPORTANT: This script returns the server to a default configuration and the res + [source,subs="+quotes,attributes+",options="nowrap"] ---- -$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-domain.cli ---- + NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. @@ -923,19 +994,19 @@ This script removes the server configuration that was done by the `install-domai The batch executed successfully ---- -=== Restore the Standalone Server Configuration +==== Restore the Standalone Server Configuration -You can Restore the domain configuration by manually restoring the back-up copies the configuration files or by running the management CLI script. +You can Restore the standalone configuration by manually restoring the back-up copies the configuration files or by running the management CLI script. [[restore_the_standalone_server_configuration_manually]] -==== Restore the Standalone Server Configuration Manually +===== Restore the Standalone Server Configuration Manually IMPORTANT: This method ensures the server is restored to its prior configuration. . If they are running, stop both {productName} servers. . Restore the `__{jbossHomeName}_1__/standalone/configuration/standalone-full-ha.xml` file with the back-up copies of the file. Make sure you replace `__{jbossHomeName}_1__` with the path to your server. -==== Restore the Standalone Configuration by Running the Management CLI Script +===== Restore the Standalone Configuration by Running the Management CLI Script IMPORTANT: This script returns the server to the default configuration, which might not match the server configuration that existed prior to testing this quickstart. If you were not running with the default configuration before testing this quickstart, you should follow the intructions above to xref:restore_the_standalone_server_configuration_manually[manually restore the standalone configuration] to its previous state. @@ -965,40 +1036,81 @@ This script removes the server configuration that was done by the install-standa The batch executed successfully ---- -=== Delete the Cloned Standalone {productName} Directory +==== Delete the Cloned Standalone {productName} Directory . If it is running, stop the second instance of the {productName} server. . Delete the cloned directory. -// Run the Quickstart in Red Hat CodeReady Studio or Eclipse -:leveloffset: +1 +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] -[[run_the_quickstart_in_redhat_codeready_studio_or_eclipse]] -= Run the Quickstart in {JBDSProductName} or Eclipse -//****************************************************************************** -// Include this template to provide instructions to run the quickstart -// in Red Hat CodeReady Studio. -// -// If the quickstart is not supported, create the `jbds-not-supported` attribute. -//****************************************************************************** -ifdef::jbds-not-supported[] -This quickstart is not supported in {JBDSProductName}. -endif::jbds-not-supported[] +[[build_and_run_the_quickstart_with_provisioned_server]] +== Building and running the quickstart application with provisioned {productName} server -ifndef::jbds-not-supported[] -You can also start the server and deploy the quickstarts or run the Arquillian tests in {JBDSProductName} or from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use {JBDSProductName} or Eclipse to Run the Quickstarts]. -endif::jbds-not-supported[] +Instead of using a standard {productName} server distribution, the two {productName} servers to deploy and run the quickstart can be alternatively provisioned by activating the Maven profile named `provisioned-server` when building the quickstart: +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +$ mvn clean package -Pprovisioned-server +---- -// Add additional instructions specific to running this quickstart in an IDE here. +The provisioned {productName} servers, with the quickstart deployed, can then be found in the `target` directory, and their 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. -:leveloffset!: +The server provisioning functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the pom.xml files of the quickstart. -//************************************************* -// Product Release content only -//************************************************* -ifdef::ProductRelease[] +=== Run the Integration Tests with a provisioned server -// Quickstart not compatible with OpenShift -include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with provisioned server. + +Follow these steps to run the integration tests. + +. Make sure the servers are provisioned by running the commands reported in <> + +. Start the {productName} provisioned servers in three distinct terminals, this time using the {productName} Maven Plugin, which is recommended for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly:start -Djboss-as.home=target/server +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly:start -Djboss-as.home=target/server2 \ + -Dwildfly.port=10090 \ + -Dwildfly.javaOpts="-Djboss.socket.binding.port-offset=100" +---- + +. 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. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host="http://localhost:8080" +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host="http://localhost:8180" +---- + +. To shut down the {productName} provisioned servers using the {productName} Maven Plugin: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly:shutdown +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly:shutdown -Dwildfly.port=10090 +---- endif::[] + +// Quickstart not compatible with OpenShift +:leveloffset: +1 + +[[openshift_incompatibility]] += {xpaasproduct-shortname} Incompatibility + +This quickstart is not compatible with {xpaasproduct-shortname}. + +:leveloffset!: