diff --git a/.github/workflows/reduce_readme.yml b/.github/workflows/reduce_readme.yml new file mode 100644 index 0000000000..0b2275e51f --- /dev/null +++ b/.github/workflows/reduce_readme.yml @@ -0,0 +1,49 @@ +name: WildFly Quickstarts Update 'README.adoc's + +on: + push: + branches: + - main + +# Only run the latest job +concurrency: + group: '${{ github.workflow }} @ ${{ github.ref || github.run_id }}' + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout Repository + uses: actions/checkout@v3 + - name: Install Asciidoctor Reducer + run: sudo gem install asciidoctor-reducer + - name: Reduce README + run: | + CURRENT_DIR="$( pwd -P)" + #Get a list of subdirectories that don't start with a . + subdirs=`find . -maxdepth 1 -type d ! -iname ".*"` + #Loop over the subdirectories + for subdir in $subdirs + do + cd $subdir + #Check if the directory contains README-source.adoc + if [ -e README-source.adoc ] + then + #Get the dirname to define artifactId in the adoc + ARTIFACT_ID=":artifactId: $(basename `pwd`)" + #Use asciidoctor-reducer to create a flattened README.adoc + asciidoctor-reducer --preserve-conditionals -o README.adoc README-source.adoc + #Insert the directory name with env-github def so that this only affects GitHub rendering + sed -i "1s/^/ifdef::env-github[]\n$ARTIFACT_ID\nendif::[]\n\n/" README.adoc + fi + cd $CURRENT_DIR + done + #Updates the table of available quickstarts @ root README-source.adoc + mvn clean package -Pdocs -N + #Reduce root README + asciidoctor-reducer --preserve-conditionals -o README.adoc README-source.adoc + - name: Commit and Push README + uses: EndBug/add-and-commit@v9 + with: + add: '*.adoc' diff --git a/README-source.adoc b/README-source.adoc new file mode 100644 index 0000000000..dbcd548db9 --- /dev/null +++ b/README-source.adoc @@ -0,0 +1,183 @@ +include::shared-doc/attributes.adoc[] + +:toc: +:toclevels: 4 +:numbered: + +ifndef::ProductRelease,EAPXPRelease[] += {productName} Quickstarts + +[toc] + +[abstract] +The quickstarts demonstrate {javaVersion} and a few additional technologies from the {productNameFull} stack. They provide small, specific, working examples that can be used as a reference for your own project. + +[[introduction]] +== Introduction + +These quickstarts run on the WildFly application server. The quickstarts are configured to use the correct Maven dependencies and ensure that you test and compile the quickstarts against the correct runtime environment. + +Each quickstart folder contains a `README.adoc` file that describes the quickstart features and provides instructions about how to build and run it. Instructions are provided to build the more readable `README.html` files. + +Make sure you read this entire document before you attempt to work with the quickstarts. + +[[system_requirements]] +== System Requirements + +The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. + +All you need to build these projects is {buildRequirements}. + +[[use_of_product_home_and_jboss_home_variables]] +== Use of WILDFLY_HOME and QUICKSTART_HOME Variables + +The quickstart `README` files use the _replaceable_ value `__WILDFLY_HOME__` to denote the path to the WildFly server. When you encounter this value in a `README` file, make sure you replace it with the actual path to your WildFly server. + +When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts. + +[[suggested_approach_to_the_quickstarts]] +== Suggested Approach to the Quickstarts + +We recommend that you approach the quickstarts as follows: + +* Regardless of your level of expertise, we suggest you start with the `helloworld` quickstart. It is the simplest example and is an easy way to prove the server is configured and running correctly. +* If you are a beginner or new to JBoss, start with the quickstarts labeled `Beginner`, then try those marked as `Intermediate`. When you are comfortable with those, move on to the `Advanced` quickstarts. +* Some quickstarts are based upon other quickstarts but have expanded capabilities and functionality. If a prerequisite quickstart is listed, make sure you deploy and test it before looking at the expanded version. + +The root folder of each individual quickstart contains a `README.html` file with detailed instructions on how to build and run the example. + +// END ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[] +endif::[] + +//********************************************************************************** +// +// WildFly Developers: You can ignore the rest of this file. +// It is for the JBoss EAP product, CD and XP Releases. +// +//********************************************************************************** + +ifdef::ProductRelease,EAPXPRelease[] +// These instructions are only for the JBoss EAP product, CD and XP Releases. += {productNameFull} ({productName}) Quickstarts + +[abstract] +The quickstarts demonstrate {javaVersion} and a few additional technologies from the {productNameFull} stack. They provide small, specific, working examples that can be used as a reference for your own project. + +[[introduction]] +== Introduction + +These quickstarts run on {productNameFull} {productVersion}. + +We recommend that you use the *{quickstartDownloadName}* ZIP file, which you can download from the {quickstartDownloadUrl}[{productName} Software Download] page on the Red Hat Customer Portal. This version of the quickstarts uses the correct dependencies and ensures that you test and compile against the correct server runtime environment. + +Each quickstart folder contains a `README{outfilesuffix}` file that describes the quickstart features and provides instructions about how to build and run it. + +Make sure you read this entire document before you attempt to work with the quickstarts. + +ifdef::ProductRelease,EAPXPRelease[] +// System Requirements are not needed for the CD Releases, only for the Product and XP Release. +[[system_requirements]] +== System Requirements + +The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. + +All you need to build these projects is {buildRequirements}. + +[[use_of_product_home_and_jboss_home_variables]] +== Use of {jbossHomeName} and QUICKSTART_HOME Variables + +The quickstart `README` files use the _replaceable_ value `__{jbossHomeName}__` to denote the path to the {productName} installation. When you encounter this value in a `README` file, make sure you replace it 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. +// END ifdef::ProductRelease,EAPXPRelease[] +endif::[] + +[[suggested_approach_to_the_quickstarts]] +== Suggested Approach to the Quickstarts + +We suggest you approach the quickstarts as follows: + +* Regardless of your level of expertise, we suggest you start with the `helloworld` quickstart. It is the simplest example and is an easy way to prove the server is configured and running correctly. +* If you are a beginner or new to JBoss, start with the quickstarts labeled `Beginner`, then try those marked as `Intermediate`. When you are comfortable with those, move on to the `Advanced` quickstarts. +* Some quickstarts are based upon other quickstarts but have expanded capabilities and functionality. If a prerequisite quickstart is listed, make sure you deploy and test it before looking at the expanded version. + +// END ifdef::ProductRelease,EAPXPRelease[] +endif::[] + +// The following is included for all versions: WildFly, JBoss EAP, EAP CD and EAP XP +[[available_quickstarts]] +== Table of Available Quickstarts + +The sources for all available quickstarts, which are listed in the following table, can be found here: {githubRepoUrl}. + +Each quickstart provides the list of technologies demonstrated by the quickstart and the required experience level needed to build and deploy it. Click on the quickstart link in the table to see more detailed information about how to run it. Some quickstarts require deployment of other quickstarts. This information is noted in the `Prerequisites` section of the quickstart `README.html` file. + +NOTE: Some of these quickstarts use the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment! + +// +[cols="1,1,2,1,1", options="header"] +|=== +| Quickstart Name | Demonstrated Technologies | Description | Experience Level Required | Prerequisites +| link:batch-processing/README{outfilesuffix}[batch-processing]|CDI, Batch 1.0, JSF | The `batch-processing` quickstart shows how to use chunk oriented batch jobs to import a file to a database. | Intermediate | _none_ +| link:bmt/README{outfilesuffix}[bmt]|EJB, BMT | The `bmt` quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities. | Intermediate | _none_ +| link:cmt/README{outfilesuffix}[cmt]|EJB, CMT, JMS | The `cmt` quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container. | Intermediate | _none_ +| link:contacts-jquerymobile/README{outfilesuffix}[contacts-jquerymobile]|jQuery Mobile, jQuery, JavaScript, HTML5, REST | The `contacts-jquerymobile` quickstart demonstrates a {javaVersion} mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST. | Beginner | _none_ +| link:ee-security/README{outfilesuffix}[ee-security]|EE Security, Servlet, CDI | The `ee-security` quickstart demonstrates Jakarta EE security. | Intermediate | _none_ +| link:ejb-multi-server/README{outfilesuffix}[ejb-multi-server]|EJB, EAR | The `ejb-multi-server` quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation. | Advanced | _none_ +| link:ejb-remote/README{outfilesuffix}[ejb-remote]|EJB, JNDI | The `ejb-remote` quickstart uses EJB and JNDI to demonstrate how to access an EJB, deployed to {productName}, from a remote Java client application. | Intermediate | _none_ +| link:ejb-security-context-propagation/README{outfilesuffix}[ejb-security-context-propagation]|EJB, Security | The `ejb-security-context-propagation` quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration | Advanced | _none_ +| link:ejb-security-programmatic-auth/README{outfilesuffix}[ejb-security-programmatic-auth]|EJB, Security | The `ejb-security-programmatic-auth` quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB. | Intermediate | _none_ +| link:ejb-throws-exception/README{outfilesuffix}[ejb-throws-exception]|EJB, EAR | The `ejb-throws-exception` quickstart demonstrates how to throw and handle exceptions across JARs in an EAR. | Intermediate | _none_ +| link:ejb-timer/README{outfilesuffix}[ejb-timer]|EJB Timer | The `ejb-timer` quickstart demonstrates how to use the Jakarta Enterprise Bean timer service `@Schedule` and `@Timeout` annotations with {productName}. | Beginner | _none_ +| link:ejb-txn-remote-call/README{outfilesuffix}[ejb-txn-remote-call]|EJB, JTA, Clustering | The `ejb-txn-remote-call` quickstart demonstrates remote transactional EJB calls over two application servers of {productName}. | Intermediate | _none_ +| link:ha-singleton-deployment/README{outfilesuffix}[ha-singleton-deployment]|EJB, Singleton Deployments, Clustering | The `ha-singleton-deployment` quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton. | Advanced | _none_ +| link:ha-singleton-service/README{outfilesuffix}[ha-singleton-service]|JBoss MSC, Singleton Service, Clustering | The `ha-singleton-service` quickstart demonstrates how to deploy a cluster-wide singleton JBoss MSC service. | Advanced | _none_ +| link:helloworld/README{outfilesuffix}[helloworld]|Servlet | The `helloworld` quickstart demonstrates the use of Servlet 6 and is a good starting point to verify {productName} is configured correctly. | Beginner | _none_ +| link:helloworld-jms/README{outfilesuffix}[helloworld-jms]|JMS | The `helloworld-jms` quickstart demonstrates the use of external JMS clients with {productName}. | Intermediate | _none_ +| link:helloworld-mdb/README{outfilesuffix}[helloworld-mdb]|JMS, EJB, MDB | The `helloworld-mdb` quickstart uses JMS and EJB Message-Driven Bean (MDB) to create and deploy JMS topic and queue resources in {productName}. | Intermediate | _none_ +| link:helloworld-mutual-ssl/README{outfilesuffix}[helloworld-mutual-ssl]|Mutual TLS, Undertow | The `helloworld-mutual-ssl` quickstart is a basic example that demonstrates mutual TLS configuration in {productName} | Intermediate | _none_ +| link:helloworld-mutual-ssl-secured/README{outfilesuffix}[helloworld-mutual-ssl-secured]|Mutual TLS, Security, Undertow | The `helloworld-mutual-ssl-secured` quickstart demonstrates securing a Web application using client certificate authentication with authorization | Intermediate | _none_ +| link:helloworld-singleton/README{outfilesuffix}[helloworld-singleton]|EJB, Singleton | The `helloworld-singleton` quickstart demonstrates an EJB Singleton Bean that is instantiated once and maintains state for the life of the session. | Beginner | _none_ +| link:helloworld-ws/README{outfilesuffix}[helloworld-ws]|JAX-WS | The `helloworld-ws` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-WS to say Hello. | Beginner | _none_ +| link:hibernate/README{outfilesuffix}[hibernate]|Hibernate | The `hibernate` quickstart demonstrates how to use Hibernate ORM 6 over Persistence, using Bean Validation, and Enterprise Beans. | Intermediate | _none_ +| link:http-custom-mechanism/README{outfilesuffix}[http-custom-mechanism]|EJB, Security | The `http-custom-mechanism` quickstart demonstrates how to implement a custom HTTP authentication mechanism that can be registered with Elytron. | Intermediate | _none_ +| link:jaxrs-client/README{outfilesuffix}[jaxrs-client]|JAX-RS | The `jaxrs-client` quickstart demonstrates Jakarta REST Client API, which interacts with a Jakarta REST Web service that runs on {productName}. | Beginner | _none_ +| link:jaxrs-jwt/README{outfilesuffix}[jaxrs-jwt]|JAX-RS, Security | The `jaxrs-jwt` quickstart demonstrates a Jakarta REST secured application using JSON Web Tokens (JWT) with Elytron. | Intermediate | _none_ +| link:jaxws-ejb/README{outfilesuffix}[jaxws-ejb]|JAX-WS | The `jaxws-ejb` quickstart is a working example of the web service endpoint created from an EJB. | Beginner | _none_ +| link:jaxws-retail/README{outfilesuffix}[jaxws-retail]|JAX-WS | The `jaxws-retail` quickstart is a working example of a simple web service endpoint. | Beginner | _none_ +| link:jsonp/README{outfilesuffix}[jsonp]|CDI, JSF, JSON-P | The `jsonp` quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings. | Beginner | _none_ +| link:jta-crash-rec/README{outfilesuffix}[jta-crash-rec]|JTA, Crash Recovery | The `jta-crash-rec` quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash. | Advanced | _none_ +| link:jts/README{outfilesuffix}[jts]|JTS, EJB, JMS | The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. | Intermediate | link:cmt/README.html[cmt] +| link:kitchensink/README{outfilesuffix}[kitchensink]|CDI, JSF, JPA, EJB, JAX-RS, BV | The `kitchensink` quickstart demonstrates a localized {javaVersion} web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation. | Intermediate | _none_ +| link:logging/README{outfilesuffix}[logging]|Logging | The `logging` quickstart demonstrates how to configure different logging levels in {productName}. | Intermediate | _none_ +| link:mail/README{outfilesuffix}[mail]|JavaMail, CDI, JSF | The `mail` quickstart demonstrates how to send and receive emails using CDI and JSF and with custom Mail provider configured in {productName}. | Beginner | _none_ +| link:messaging-clustering-singleton/README{outfilesuffix}[messaging-clustering-singleton]|JMS, MDB, Clustering | The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using {productName} messaging with MDB singleton configuration where only one node in the cluster will be active. | Advanced | _none_ +| link:micrometer/README{outfilesuffix}[micrometer]|Micrometer | The `micrometer` quickstart demonstrates the use of the Micrometer library in {productName}. | Beginner | _none_ +| link:microprofile-config/README{outfilesuffix}[microprofile-config]|MicroProfile Config | The `microprofile-config` quickstart demonstrates the use of the MicroProfile Config specification in {productName}. | Beginner | _none_ +| link:microprofile-fault-tolerance/README{outfilesuffix}[microprofile-fault-tolerance]|MicroProfile, Fault Tolerance | The `microprofile-fault-tolerance` quickstart demonstrates how to use Eclipse MicroProfile Fault Tolerance in {productName}. | Intermediate | _none_ +| link:microprofile-health/README{outfilesuffix}[microprofile-health]|MicroProfile Health | The `microprofile-health` quickstart demonstrates the use of the MicroProfile Health specification in {productName}. | Beginner | _none_ +| link:microprofile-jwt/README{outfilesuffix}[microprofile-jwt]|JWT, Security, MicroProfile | The `microprofile-jwt` quickstart demonstrates the use of the MicroProfile JWT specification in {productName}. | Intermediate | _none_ +| link:microprofile-lra/README{outfilesuffix}[microprofile-lra]|MicroProfile LRA | The `microprofile-lra` quickstart demonstrates the use of the MicroProfile LRA specification in {productName}. | Beginner | _none_ +| link:microprofile-openapi/README{outfilesuffix}[microprofile-openapi]|MicroProfile OpenAPI | This guide demonstrate how to use the MicroProfile OpenAPI functionality in {productName} to expose an OpenAPI document for a simple REST application. | Beginner | _none_ +| link:microprofile-reactive-messaging-kafka/README{outfilesuffix}[microprofile-reactive-messaging-kafka]|MicroProfile Reactive Messaging | The `microprofile-reactive-messaging-kafka` quickstart demonstrates the use of the MicroProfile Reactive Messaging specification backed by Apache Kafka in {productName}. | Beginner | _none_ +| link:microprofile-rest-client/README{outfilesuffix}[microprofile-rest-client]|MicroProfile REST Client | The `microprofile-rest-client` quickstart demonstrates the use of the MicroProfile REST Client specification in {productName}. | Beginner | _none_ +| link:numberguess/README{outfilesuffix}[numberguess]|CDI, JSF | The `numberguess` quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in {productName}. | Beginner | _none_ +| link:opentelemetry-tracing/README{outfilesuffix}[opentelemetry-tracing]|OpenTelemetry Tracing | The `opentelemetry-tracing` quickstart demonstrates the use of the OpenTelemetry tracing specification in {productName}. | Beginner | _none_ +| link:remote-helloworld-mdb/README{outfilesuffix}[remote-helloworld-mdb]|JMS, EJB, MDB | The `remote-helloworld-mdb` quickstart demonstrates the use of JMS and EJB Message-Driven Bean in {productName} with a remote broker. | Intermediate | _none_ +| link:security-domain-to-domain/README{outfilesuffix}[security-domain-to-domain]|Servlet, EJB, Security | The `security-domain-to-domain` quickstart demonstrates the propagation of an identity across two different deployments using different security domains. | Advanced | _none_ +| link:servlet-async/README{outfilesuffix}[servlet-async]|Asynchronous Servlet, CDI, EJB | The `servlet-async` quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread. | Intermediate | _none_ +| link:servlet-filterlistener/README{outfilesuffix}[servlet-filterlistener]|Servlet Filter, Servlet Listener | The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in an application. | Intermediate | _none_ +| link:servlet-security/README{outfilesuffix}[servlet-security]|Servlet, Security | The `servlet-security` quickstart demonstrates the use of Jakarta EE declarative security to control access to Servlets and Security in {productName}. | Intermediate | _none_ +| link:spring-resteasy/README{outfilesuffix}[spring-resteasy]|Resteasy, Spring | The `spring-resteasy` quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration. | Beginner | _none_ +| link:tasks-jsf/README{outfilesuffix}[tasks-jsf]|JSF, JPA | The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. | Intermediate | _none_ +| link:temperature-converter/README{outfilesuffix}[temperature-converter]|CDI, JSF, SLSB EJB | The `temperature-converter` quickstart does temperature conversion using an EJB Stateless Session Bean (SLSB), CDI, and a JSF front-end client. | Beginner | _none_ +| link:thread-racing/README{outfilesuffix}[thread-racing]|Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets | A thread racing web application that demonstrates technologies introduced or updated in the latest Jakarta EE specification. | Beginner | _none_ +| link:todo-backend/README{outfilesuffix}[todo-backend]|JPA, JAX-RS, OpenShift, Galleon | The `todo-backend` quickstart demonstrates how to implement a backend that exposes a HTTP API with JAX-RS | Intermediate | _none_ +| link:websocket-endpoint/README{outfilesuffix}[websocket-endpoint]|CDI, WebSocket, JSON-P | Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in {productName}. | Beginner | _none_ +| link:websocket-hello/README{outfilesuffix}[websocket-hello]|WebSocket, CDI, JSF | The `websocket-hello` quickstart demonstrates how to create a simple WebSocket application. | Beginner | _none_ +| link:wsat-simple/README{outfilesuffix}[wsat-simple]|WS-AT, JAX-WS | The `wsat-simple` quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to {productName}. | Intermediate | _none_ +| link:wsba-coordinator-completion-simple/README{outfilesuffix}[wsba-coordinator-completion-simple]|WS-BA, JAX-WS | The `wsba-coordinator-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (CoordinatorCompletion protocol). | Intermediate | _none_ +| link:wsba-participant-completion-simple/README{outfilesuffix}[wsba-participant-completion-simple]|WS-BA, JAX-WS | The `wsba-participant-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol). | Intermediate | _none_ +|=== +// + diff --git a/README.adoc b/README.adoc index 46457445e8..623496a239 100644 --- a/README.adoc +++ b/README.adoc @@ -1,4 +1,197 @@ -include::shared-doc/attributes.adoc[] +//*********************************************************************************** +// 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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 :toc: :toclevels: 4 @@ -35,30 +228,6 @@ The quickstart `README` files use the _replaceable_ value `__WILDFLY_HOME__` to When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts. -[[prerequisites]] -== Prerequisites - -[[build_quickstart_readme_files]] -=== Build the Quickstart README.html Files - -The quickstart `README` files are written in AsciiDoc, not only because the language is much more powerful than Markdown, but also also because it is possible to extract common instructions into separate files to be reused across the quickstarts. While this makes them more flexible and easier to maintain, unfortunately, included files do not render in a readable format in GitHub or in most text editors. - -The Maven plugin that is used to build and deploy the quickstarts can also generate fully rendered `README.html` instructions from the `README.adoc` files. - -To build all of the quickstart `README.html` files, including the root `README.html` file that contains the table with links to all available quickstarts, navigate to the root folder of the quickstarts and run the following command. - -[source,options="nowrap"] ----- -$ mvn clean package -Pdocs ----- - -[TIP] -==== -To build the `README.html` file for a specific quickstart, navigate to the quickstart directory and run the above command. -==== - -If you see errors about missing dependencies, check the xref:prerequisites[prerequisites] section to determine whether you need to xref:build_wildfly_boms[build the WildFly BOMs] that corresponds to the version of the quickstarts that you are using. - [[suggested_approach_to_the_quickstarts]] == Suggested Approach to the Quickstarts @@ -141,7 +310,7 @@ NOTE: Some of these quickstarts use the H2 database included with {productNameFu // [cols="1,1,2,1,1", options="header"] |=== -| Quickstart Name | Demonstrated Technologies | Description | Experience Level Required | Prerequisites +| Quickstart Name | Demonstrated Technologies | Description | Experience Level Required | Prerequisites | link:batch-processing/README{outfilesuffix}[batch-processing]|CDI, Batch 1.0, JSF | The `batch-processing` quickstart shows how to use chunk oriented batch jobs to import a file to a database. | Intermediate | _none_ | link:bmt/README{outfilesuffix}[bmt]|EJB, BMT | The `bmt` quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities. | Intermediate | _none_ | link:cmt/README{outfilesuffix}[cmt]|EJB, CMT, JMS | The `cmt` quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container. | Intermediate | _none_ @@ -204,4 +373,3 @@ NOTE: Some of these quickstarts use the H2 database included with {productNameFu | link:wsba-participant-completion-simple/README{outfilesuffix}[wsba-participant-completion-simple]|WS-BA, JAX-WS | The `wsba-participant-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol). | Intermediate | _none_ |=== // - diff --git a/batch-processing/README-source.adoc b/batch-processing/README-source.adoc new file mode 100644 index 0000000000..9370abe18d --- /dev/null +++ b/batch-processing/README-source.adoc @@ -0,0 +1,144 @@ +include::../shared-doc/attributes.adoc[] + += batch-processing: Chunk oriented Batch 1.0 processing +:author: Rafael Benevides +:level: Intermediate +:technologies: CDI, Batch 1.0, JSF +:openshift: true + +[abstract] +The `batch-processing` quickstart shows how to use chunk oriented batch jobs to import a file to a database. + +:standalone-server-type: default +:archiveType: war +:uses-h2: + +== What is it? + +This quickstart simulates a file importation using batch jobs. To make it easy, this quickstart offers the user a way to generate files. The generated file can have its name and the number of records customized. The user can also specify if the file contains an error or not. + +The job contains two tasks: + +. It imports the file using a chunk oriented approach. + +* The chunk size is set to `3`. +* The `RecordsReader` is responsible for parsing the file and create an instance of `Contact`. +* The `ContactsFormatter` applies the proper case to the contact name and it also applies a mask to the phone number. +* Finally, `ContactsPersister` sends the contact instance to the database. + +. It logs the number of records imported. + +The database schema defines that the column for name is unique. For that reason, any attempt to persist a duplicate value will throw an exception. On the second attempt to run the job, the `ChunkCheckpoint` provides information to skip the contacts that were already persisted. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +Access the running application in a browser at the following URL: http://localhost:8080/{artifactId}/ + +You are presented with a simple form that allows you to generate sample files to be imported. + +=== Usage 1: Import the file without any errors + +. Click on *Generate a new file and start import job* button. This generates a new file with 10 unique records to be imported. The import job starts after the file is generated. + +. A table is displayed containing information about the task that was started. Click on the *Update jobs list* button and verify that the job was completed. + +. Investigate the console output. It shows that files with 10 records were processed, 3 records at a time. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.quickstarts.batch.controller.BatchController] (default task-3) Starting to generate 10 in file /var/folders/j8/63sgdmbn5tqdkyw0tz6df53r0000gn/T/temp-file.txt +INFO [org.jboss.as.quickstarts.batch.controller.BatchController] (default task-3) File generated at /var/folders/j8/63sgdmbn5tqdkyw0tz6df53r0000gn/T/temp-file.txt +INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 1) Job import-file - Execution #1 starting. +INFO [org.jboss.as.quickstarts.batch.job.ContactsPersister] (Batch Thread - 1) No checkpoint detected. Cleaning the Database +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #1 - Changing name ZIqYKITxiM -> Ziqykitxim | phone 978913851 -> (978)-913-851 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #2 - Changing name JbHjnaThps -> Jbhjnathps | phone 095108018 -> (095)-108-018 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #3 - Changing name FJTlXRtCdR -> Fjtlxrtcdr | phone 286847939 -> (286)-847-939 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #4 - Changing name mlmBABWzfL -> Mlmbabwzfl | phone 744478648 -> (744)-478-648 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #5 - Changing name jVlTYiBRMP -> Jvltyibrmp | phone 135063841 -> (135)-063-841 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #6 - Changing name DwEFbSjfQE -> Dwefbsjfqe | phone 404572175 -> (404)-572-175 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #7 - Changing name niDXWwGJuQ -> Nidxwwgjuq | phone 949448390 -> (949)-448-390 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #8 - Changing name VZBArfowSe -> Vzbarfowse | phone 902370961 -> (902)-370-961 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #9 - Changing name aSpyWCWwje -> Aspywcwwje | phone 246977695 -> (246)-977-695 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 1) Register #10 - Changing name TofTfbRBzI -> Toftfbrbzi | phone 868339088 -> (868)-339-088 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Preparing to persist 1 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 1) Persisting 1 contacts +INFO [org.jboss.as.quickstarts.batch.job.ReportBatchelet] (Batch Thread - 1) Imported 10 to Database +INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 1) Job import-file - Execution #1 finished. Status: COMPLETED +---- + +=== Usage 2: Import an error file and fix it + +Now you will simulate a file with duplicate records. This will raise an exception and stop the processing. After that, you will fix the file and continue the importing where it stopped. + +. Mark the *Generate a duplicate record* checkbox and click on *Generate a new file and start import job* button. If you click on *Update jobs list* button, you will see that the job failed with the following Exit Status: `Error : org.hibernate.exception.ConstraintViolationException: could not execute statement`. This was caused because the job tried to insert a duplicate record at the Database. You will also see `org.h2.jdbc.JdbcSQLException: Unique index or primary key violation` exception stacktraces in the server log. + +. Next, you will fix the file and restart that job execution. Uncheck the *Generate a duplicate record* checkbox and click on *Generate a new file* button. This will generate the file without errors. + +. Click on *Restart* button in the last column for that job instance in the *List of Jobs* table. If you click on *Update jobs list* button, you will see that the job was completed. + +. Review the server logs and verify that the job started from the last checkpoint. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.quickstarts.batch.job.RecordsReader] (Batch Thread - 3) Skipping to line 3 as marked by previous checkpoint +---- + +. Investigate the console output. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 3) Job import-file - Execution #3 starting. +INFO [org.jboss.as.quickstarts.batch.job.RecordsReader] (Batch Thread - 3) Skipping to line 3 as marked by previous checkpoint +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #4 - Changing name HdeqwzEjbA -> Hdeqwzejba | phone 686417040 -> (686)-417-040 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #5 - Changing name veEEbtpYTJ -> Veeebtpytj | phone 367981821 -> (367)-981-821 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #6 - Changing name bQIKTUyqMW -> Bqiktuyqmw | phone 103363182 -> (103)-363-182 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Preparing to persist 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Persisting 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #7 - Changing name KVLIGXhCry -> Kvligxhcry | phone 117327691 -> (117)-327-691 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #8 - Changing name PBAZgernHy -> Pbazgernhy | phone 066203468 -> (066)-203-468 +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #9 - Changing name DGtNZdteGB -> Dgtnzdtegb | phone 908779587 -> (908)-779-587 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Preparing to persist 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Persisting 3 contacts +INFO [org.jboss.as.quickstarts.batch.job.ContactsFormatter] (Batch Thread - 3) Register #10 - Changing name mhmIHhZMhv -> Mhmihhzmhv | phone 094518410 -> (094)-518-410 +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Preparing to persist 1 contacts +INFO [org.jboss.as.quickstarts.batch.job.listener.PersistListener] (Batch Thread - 3) Persisting 1 contacts +WARN [org.jberet] (Batch Thread - 3) JBERET000018: Could not find the original step execution to restart. Current step execution id: 0, step name: reportBatchelet +INFO [org.jboss.as.quickstarts.batch.job.ReportBatchelet] (Batch Thread - 3) Imported 10 to Database +INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - 3) Job import-file - Execution #3 finished. Status: COMPLETED +---- + +=== Usage 3: Import an error file and do not fix the errors + +. Check the *Generate a duplicate record* checkbox and click on *Generate a new file ans start import job* button. If you click on *Update jobs list* button, you will see that the job failed with the following Exit Status: `Error : org.hibernate.exception.ConstraintViolationException: could not execute statement`. This was caused because you tried to insert a duplicate record at the Database. + +. This time you will not fix the file. Just click on *Restart* button again. If you click on *Update jobs list* button, you will see that the job was marked as `ABANDONED` this time because it was restarted once. Notice that there is a new parameter: `restartedOnce=true`. This behavior was implemented in `JobListener` for demonstration purposes, to prevent a `FAILED` job from being restarted twice. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/batch-processing/README.adoc b/batch-processing/README.adoc index 4e85ba3bed..dcfb8b639a 100644 --- a/batch-processing/README.adoc +++ b/batch-processing/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: batch-processing +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = batch-processing: Chunk oriented Batch 1.0 processing :author: Rafael Benevides @@ -32,17 +229,322 @@ The job contains two tasks: The database schema defines that the column for name is unique. For that reason, any attempt to persist a duplicate value will throw an exception. On the second attempt to run the job, the `ChunkCheckpoint` provides information to skip the contacts that were already persisted. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -134,12 +636,625 @@ INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - . This time you will not fix the file. Just click on *Restart* button again. If you click on *Update jobs list* button, you will see that the job was marked as `ABANDONED` this time because it was restarted once. Notice that there is a new parameter: `restartedOnce=true`. This behavior was implemented in `JobListener` for demonstration purposes, to prevent a `FAILED` job from being restarted twice. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file + +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: batch-processing +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/batch-processing/charts/helm.yaml b/batch-processing/charts/helm.yaml index 76725f9799..b1d0f8e8b6 100644 --- a/batch-processing/charts/helm.yaml +++ b/batch-processing/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: batch-processing deploy: replicas: 1 \ No newline at end of file diff --git a/batch-processing/pom.xml b/batch-processing/pom.xml index acd9e4e1e3..63271b7a13 100644 --- a/batch-processing/pom.xml +++ b/batch-processing/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 batch-processing - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: batch-processing Shows how to use a Chunk oriented batch processing @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/bmt/README-source.adoc b/bmt/README-source.adoc new file mode 100644 index 0000000000..71312609a5 --- /dev/null +++ b/bmt/README-source.adoc @@ -0,0 +1,95 @@ +include::../shared-doc/attributes.adoc[] + += bmt: Bean Managed Transactions with JPA and JTA +:author: Mike Musgrove +:level: Intermediate +:technologies: EJB, BMT +:openshift: true + +[abstract] +The `bmt` quickstart demonstrates Bean-Managed Transactions (BMT), showing how to manually manage transaction demarcation while accessing JPA entities. + +:standalone-server-type: default +:archiveType: war +:uses-h2: +:uses-ds-xml: +:performance-scalability: + +== What is it? + +The `bmt` quickstart demonstrates how to manually manage transaction demarcation while accessing JPA entities in {productNameFull}. + +On occasion, the application developer requires finer grained control over the lifecycle of JTA transactions and JPA Entity Managers than the defaults provided by the Jakarta EE container. This example shows how the developer can override these defaults and take control of aspects of the lifecycle of JPA and transactions. + +When you run this example, you are presented with a *Use bean managed Entity Managers* checkbox. + +* If you check the checkbox, it shows the developer responsibilities when injecting an Entity Manager into a managed (stateless) bean. +* If you uncheck the checkbox, shows the developer responsibilities when using JPA and transactions with an unmanaged component. + +This example shows how to transactionally insert key value pairs into the database and demonstrates the requirements on the developer with respect to the JPA Entity Manager. + +ifndef::EAPCDRelease[] + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +You are presented with a simple form for adding key/value pairs, and a checkbox to indicate whether the updates should be executed using an unmanaged component. Effectively this will run the transaction and JPA updates in the servlet, not session beans. If the box is checked then the updates are executed within a session bean method. + +. To list all pairs leave the *Key* input field empty. +. To add or update the value of a key, fill in the *Key* and *Value* input fields. +. Click the *Submit* button to see the results. + +== Server Log: Expected Warnings and Errors + +You will see the following warnings in the server log. You can ignore these warnings. + +[source,options="nowrap"] +---- +WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. + +HHH000431: Unable to determine H2 database version, certain features may not work +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +endif::[] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Getting Started with OpenShift +include::../shared-doc/openshift-getting-started.adoc[leveloffset=+1] +//Prepare OpenShift for Quickstart Deployment +include::../shared-doc/openshift-create-project.adoc[leveloffset=+1] +// Import the Latest {xpaasproduct-shortname} Image Streams and Templates +include::../shared-doc/openshift-import-imagestreams-templates.adoc[leveloffset=+1] +// Deploy the {ProductShortName} Source-to-Image (S2I) Quickstart to OpenShift +include::../shared-doc/openshift-deploy-project.adoc[leveloffset=+1] +// Openshift post deployment tasks +include::../shared-doc/openshift-post-deployment-tasks.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/bmt/README.adoc b/bmt/README.adoc index 35bbe7198f..fe6d962643 100644 --- a/bmt/README.adoc +++ b/bmt/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: bmt +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = bmt: Bean Managed Transactions with JPA and JTA :author: Mike Musgrove @@ -32,17 +229,322 @@ This example shows how to transactionally insert key value pairs into the databa ifndef::EAPCDRelease[] // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -66,15 +568,628 @@ HHH000431: Unable to determine H2 database version, certain features may not wor ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: bmt +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[] + + +[[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 + +// 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 + +:leveloffset!: endif::[] //************************************************* @@ -93,4 +1208,4 @@ include::../shared-doc/openshift-deploy-project.adoc[leveloffset=+1] // Openshift post deployment tasks include::../shared-doc/openshift-post-deployment-tasks.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/bmt/charts/helm.yaml b/bmt/charts/helm.yaml index de7dd19e21..a8d5feda57 100644 --- a/bmt/charts/helm.yaml +++ b/bmt/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: bmt deploy: replicas: 1 \ No newline at end of file diff --git a/bmt/pom.xml b/bmt/pom.xml index 122472b7e1..7f121c8338 100644 --- a/bmt/pom.xml +++ b/bmt/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 bmt - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: bmt This project demonstrates how to use Bean Managed Transactions @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/cmt/README-source.adoc b/cmt/README-source.adoc new file mode 100644 index 0000000000..508f2c51d2 --- /dev/null +++ b/cmt/README-source.adoc @@ -0,0 +1,89 @@ +include::../shared-doc/attributes.adoc[] + += cmt: Container Managed Transactions (CMT) +:author: Tom Jenkinson +:level: Intermediate +:technologies: EJB, CMT, JMS +:openshift: true + +[abstract] +The `cmt` quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container. + +:standalone-server-type: full +:archiveType: war +:uses-h2: + +== What is it? + +The `cmt` quickstart demonstrates how to use container-managed transactions (CMT), which are transactions managed by the container in {productNameFull}. It is a fairly typical scenario of updating a database and sending a JMS message in the same transaction. A simple MDB is provided that prints out the message sent but this is not a transactional MDB and is purely provided for debugging purposes. + +Aspects touched upon in the code: + +* XA transaction control using the container managed transaction annotations +* XA access to the standard default datasource using the JPA API +* XA access to a JMS queue + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +=== What are Container Managed Transactions? + +Prior to EJB, getting the right incantation to ensure sound transactional operation of the business logic was a highly specialized skill. Although this still holds true to a great extent, EJB has provided a series of improvements to allow simplified transaction demarcation notation that is therefore easier to read and test. + +With CMT, the EJB container sets the boundaries of a transaction. This differs from BMT (bean-managed transactions), where the developer is responsible for initiating and completing a transaction using the `begin`, `commit`, and `rollback` methods on a `jakarta.transaction.UserTransaction`. + +=== What Makes This an Example of Container Managed Transactions? + +Take a look at `org.jboss.as.quickstarts.cmt.ejb.CustomerManagerEJB`. You can see that this stateless session bean has been marked up with the `@jakarta.ejb.TransactionAttribute` annotation. + +The following options are available for this annotation. + +Required:: As demonstrated in the quickstart. If a transaction does not already exist, this will initiate a transaction and complete it for you, otherwise the business logic will be integrated into the existing transaction. +RequiresNew:: If there is already a transaction running, it will be suspended, the work performed within a new transaction which is completed at exit of the method and then the original transaction resumed. +Mandatory:: If there is no transaction running, calling a business method with this annotation will result in an error. +NotSupported:: If there is a transaction running, it will be suspended and no transaction will be initiated for this business method. +Supports:: This will run the method within a transaction if a transaction exists, alternatively, if there is no transaction running, the method will not be executed within the scope of a transaction. +Never:: If the client has a transaction running and does not suspend it but calls a method annotated with Never then an EJB exception will be raised. + +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/ + +You are presented with a simple form for adding customers to a database. + +After a customer is successfully added to the database, a message is produced containing the details of the customer. An example MDB dequeues this message and print the following contents. + +[source,options="nowrap"] +---- +Received Message: Created invoice for customer named: Jack +---- + +If an existing customer name is provided, no JMS message is sent. Instead of the above message, a duplicate warning is displayed. + +The customer name should match: letter & '-', otherwise an error is given. This is to show that a `LogMessage` entity is still stored in the database. That is because the `logCreateCustomer` method in the `LogMessageManagerEJB` EJB is decorated with the `@TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)` annotation. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cmt/README.adoc b/cmt/README.adoc index 06c954fe75..dcbf295564 100644 --- a/cmt/README.adoc +++ b/cmt/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: cmt +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = cmt: Container Managed Transactions (CMT) :author: Tom Jenkinson @@ -25,7 +222,13 @@ Aspects touched upon in the code: * XA access to a JMS queue // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: === What are Container Managed Transactions? @@ -47,19 +250,318 @@ Supports:: This will run the method within a transaction if a transaction exists Never:: If the client has a transaction running and does not suspend it but calls a method annotated with Never then an EJB exception will be raised. // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -79,12 +581,625 @@ If an existing customer name is provided, no JMS message is sent. Instead of the The customer name should match: letter & '-', otherwise an error is given. This is to show that a `LogMessage` entity is still stored in the database. That is because the `logCreateCustomer` method in the `LogMessageManagerEJB` EJB is decorated with the `@TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)` annotation. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: cmt +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/cmt/charts/helm.yaml b/cmt/charts/helm.yaml index 672ba19145..6cd6118254 100644 --- a/cmt/charts/helm.yaml +++ b/cmt/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: cmt deploy: replicas: 1 \ No newline at end of file diff --git a/cmt/pom.xml b/cmt/pom.xml index 5beaf47c04..05951d66bf 100644 --- a/cmt/pom.xml +++ b/cmt/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 cmt - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: cmt This project demonstrates how to use transactions managed by the container @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/contacts-jquerymobile/README-source.adoc b/contacts-jquerymobile/README-source.adoc new file mode 100644 index 0000000000..6c7b3ada5c --- /dev/null +++ b/contacts-jquerymobile/README-source.adoc @@ -0,0 +1,177 @@ +include::../shared-doc/attributes.adoc[] + += contacts-jquerymobile: CRUD Example Using HTML5, jQuery Mobile and JAX-RS +:author: Joshua Wilson +:level: Beginner +:technologies: jQuery Mobile, jQuery, JavaScript, HTML5, REST +:openshift: true + +[abstract] +The `contacts-jquerymobile` quickstart demonstrates a {javaVersion} mobile database application using HTML5, jQuery Mobile, JAX-RS, JPA, and REST. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `contact-jquerymobile` quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing HTML5 based mobile web applications with {javaVersion} in {productNameFull}. This project is setup to allow you to create a basic {javaVersion} application using HTML5, jQuery Mobile, JAX-RS, CDI, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to help you get your feet wet with database access in enterprise Java. + +This application is built using a HTML5 + REST approach. This uses a pure HTML client that interacts with with the application server via restful end-points (JAX-RS). This application also uses some of the latest HTML5 features and advanced JAX-RS. And since testing is just as important with client side as it is server side, this application uses QUnit to show you how to unit test your JavaScript. + +This application focuses on *CRUD* in a strictly mobile app using only *jQuery Mobile*(no other frameworks). The user will have the ability to: + +* *Create* a new contact. + +* *Read* a list of contacts. + +* *Update* an existing contact. + +* *Delete* a contact. + +Validation is an important part of an application. Typically in an HTML5 app you can let the built-in HTML5 form validation do the work for you. However, mobile browsers do not support this feature at this time. In order to validate the forms, the `jquery.validate` plugin was added, which provides both client-side and server-side validation. Over AJAX, if there is an error, the error is returned and displayed in the form. You can see an example of this in the *Edit* form if you enter an email that is already in use. The application will attempt to insert the error message into a field if that field exists. If the field does not exist then it display it at the top. In addition, there are xref:run_the_qunit_tests[QUnit Tests] for every form of validation. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* + +ifndef::EAPCDRelease[] + +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Additional system requirements for this quickstart: +An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. Note that some behaviors, such as validation, will vary slightly based on browser support, especially IE 9. + +Mobile web support is limited to Android and iOS devices. It should run on HP, and Black Berry devices as well. Windows Phone, and others will be supported as jQuery Mobile announces support. + +With the prerequisites out of the way, you are ready to build and deploy. + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +:mobileApp: +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +Access the running client application in a browser at the following URL: http://localhost:8080/{artifactId}/. + +The application is made up of the following pages: + +*Main page* + +* Displays a list of contacts. +* Search bar for the list. +* Details button changes to the Detailed list. +* Clicking on a contact brings up an Edit form. +* Menu button (in upper left) opens menu. + +*Menu pullout* + +* Add a new contact. +* List/Detail view switcher, depending on what is currently displayed. +* About information. +* Theming - apply various themes (only on the List view). + +*Details page* + +* Same as Main page except all information is displayed with each contact. + +*Add form* + +* *First name*, *Last name*, *Phone*, *Email*, and *BirthDate* fields. +* *Save* submits the form. +* *Clear* resets the form but stays on the form. +* *Cancel* resets the form and goes the Main page. + +*Edit form* + +* Same as *Add form*. +* *Delete* button will delete the contact currently viewed and return you to the Main page. + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + + +== Minification + +By default, the project uses the http://code.google.com/p/wro4j/[wro4j] plugin, which provides the ability to concatenate, validate and minify JavaScript and CSS files. These minified files, as well as their unmodified versions are deployed with the project. + +With just a few quick changes to the project, you can link to the minified versions of your JavaScript and CSS files. + +First, in the `{artifactId}/src/main/webapp/index.html` file, search for references to minification and comment or uncomment the appropriate lines. + +Finally, wro4j runs in the compile phase, so any standard build command like `package` or `install`, will trigger it. The plugin is in a profile with an ID of `minify` so you must specify that profile in your Maven build. + +By default, tests are disabled, so you must use the Arquillian test profile to run tests when minifying. + +* For example, to deploy with no tests: ++ +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy -Pminify +---- + +* To deploy with tests: ++ +[source,options="nowrap"] +---- +$ mvn clean verify wildfly:deploy -Pminify,arq-remote +---- + +// Run the Arquillian Tests +include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] + + +[[run_the_qunit_tests]] +== Run the QUnit Tests + +QUnit is a JavaScript unit testing framework used and built by jQuery. Because JavaScript code is the core of this HTML5 application, this quickstart provides a set of QUnit tests that automate testing of this code in various browsers. Executing QUnit test cases are quite easy. + +Simply load the `__QUICKSTART_HOME__/contacts-jquerymobile/src/test/qunit/index.html` file in the browser you want to test. + +NOTE: If you use *Chrome*, some date tests fail. These are false failures and are known issues with Chrome. FireFox, Safari, and IE run the tests correctly. You can also display the tests using the Eclipse built-in browser. + +For more information on QUnit tests, see http://qunitjs.com/. + +// Run the Arquillian Functional Tests +include::../shared-doc/run-arquillian-functional-tests.adoc[leveloffset=+1] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +== Debug the Application + +If you want to be able to debug into the source code or look at the Javadocs of any library in the project, you can run +either of the following two commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- + +endif::[] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Getting Started with OpenShift +include::../shared-doc/openshift-getting-started.adoc[leveloffset=+1] +//Prepare OpenShift for Quickstart Deployment +include::../shared-doc/openshift-create-project.adoc[leveloffset=+1] +// Import the Latest {xpaasproduct-shortname} Image Streams and Templates +include::../shared-doc/openshift-import-imagestreams-templates.adoc[leveloffset=+1] +// Deploy the {ProductShortName} Source-to-Image (S2I) Quickstart to OpenShift +include::../shared-doc/openshift-deploy-project.adoc[leveloffset=+1] +// Openshift post deployment tasks +include::../shared-doc/openshift-post-deployment-tasks.adoc[leveloffset=+1] + + +endif::[] \ No newline at end of file diff --git a/contacts-jquerymobile/README.adoc b/contacts-jquerymobile/README.adoc index 6c7b3ada5c..d18413f5af 100644 --- a/contacts-jquerymobile/README.adoc +++ b/contacts-jquerymobile/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: contacts-jquerymobile +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = contacts-jquerymobile: CRUD Example Using HTML5, jQuery Mobile and JAX-RS :author: Joshua Wilson @@ -31,7 +228,13 @@ This application focuses on *CRUD* in a strictly mobile app using only *jQuery M Validation is an important part of an application. Typically in an HTML5 app you can let the built-in HTML5 form validation do the work for you. However, mobile browsers do not support this feature at this time. In order to validate the forms, the `jquery.validate` plugin was added, which provides both client-side and server-side validation. Over AJAX, if there is an error, the error is returned and displayed in the form. You can see an example of this in the *Edit* form if you enter an email that is already in use. The application will attempt to insert the error message into a field if that field exists. If the field does not exist then it display it at the top. In addition, there are xref:run_the_qunit_tests[QUnit Tests] for every form of validation. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: //************************************************* // Product Release content only @@ -40,7 +243,23 @@ include::../shared-doc/view-the-source.adoc[leveloffset=+1] ifndef::EAPCDRelease[] // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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!: // Additional system requirements for this quickstart: An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. Note that some behaviors, such as validation, will vary slightly based on browser support, especially IE 9. @@ -50,12 +269,266 @@ Mobile web support is limited to Android and iOS devices. It should run on HP, a With the prerequisites out of the way, you are ready to build and deploy. // Use of {jbossHomeName} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server :mobileApp: -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -95,7 +568,26 @@ The application is made up of the following pages: * *Delete* button will delete the contact currently viewed and return you to the Main page. // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: == Minification @@ -125,7 +617,58 @@ $ mvn clean verify wildfly:deploy -Pminify,arq-remote ---- // Run the Arquillian Tests -include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_arquillian_tests]] += Run the Arquillian Tests +//****************************************************************************** +// Include this template if your quickstart provides standard Arquillian tests. +//****************************************************************************** + +This quickstart provides Arquillian tests. By default, these tests are configured to be skipped since Arquillian tests require the use of a container. + +NOTE: The Arquillian tests deploy the application, so make sure you undeploy the quickstart before you begin. + +ifdef::arq-prerequisities[] +== Arquillian Tests prerequisities + +{arq-prerequisities} +endif::[] + +Follow these steps to run the tests. + +ifdef::standalone-server-type[] +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +endif::[] + +ifdef::managed-domain-type[] +. xref:start_the_eap_managed_domain[Start the {productName} server] as described above. +endif::[] + +. Open a terminal and navigate to the root directory of this quickstart. +. Type the following command to run the `verify` goal with the `arq-remote` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn clean verify -Parq-remote +---- +ifdef::arquillianTestResults[] +You should see the following results: ++ +[source,subs=attributes+,options="nowrap"] +---- +Results : + +{arquillianTestResults} +---- +endif::[] + +[NOTE] +==== +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile, meaning the tests will start the server for you. This profile requires that you provide Arquillian with the location of the {productName} server, either by setting the `JBOSS_HOME` environment variable, or by setting the `jbossHome` property in the `arquillian.xml` file. For more information, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. +==== + +:leveloffset!: [[run_the_qunit_tests]] @@ -140,9 +683,74 @@ NOTE: If you use *Chrome*, some date tests fail. These are false failures and ar For more information on QUnit tests, see http://qunitjs.com/. // Run the Arquillian Functional Tests -include::../shared-doc/run-arquillian-functional-tests.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_arquillian_functional_tests]] += Run the Arquillian Functional Tests +//****************************************************************************** +// Include this template if your quickstart provides standard Arquillian +// functional tests. +//****************************************************************************** + +This quickstart provides Arquillian functional tests. They are located under the `functional-tests/` directory. Functional tests verify that your application behaves correctly from the user's point of view and simulate clicking around the web page as a normal user would do. + +NOTE: The Arquillian functional tests deploy the application, so make sure you undeploy the quickstart before you begin. + +Follow these steps to run the functional tests. + +ifdef::standalone-server-type[] +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +endif::[] + +ifdef::managed-domain-type[] +. xref:start_the_eap_managed_domain[Start the {productName} server] as described above. +endif::[] + +. Build the quickstart archive. +.. Open a terminal and navigate to the root directory of this quickstart. +.. Build the quickstart archive using the following command: ++ +[source,options="nowrap"] +---- +$ mvn clean package +---- +. Navigate to the `functional-tests/` directory in this quickstart. + +. Type the following command to run the `verify` goal with the `arq-remote` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn clean verify -Parq-remote +---- + +[NOTE] +==== +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile, meaning the tests will start the server for you. This profile requires that you provide Arquillian with the location of the {productName} server, either by setting the `JBOSS_HOME` environment variable, or by setting the `jbossHome` property in the `arquillian.xml` file. For more information, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. +==== + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: == Debug the Application @@ -174,4 +782,4 @@ include::../shared-doc/openshift-deploy-project.adoc[leveloffset=+1] include::../shared-doc/openshift-post-deployment-tasks.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/contacts-jquerymobile/functional-tests/pom.xml b/contacts-jquerymobile/functional-tests/pom.xml index 25e389e703..4441a8ffbd 100644 --- a/contacts-jquerymobile/functional-tests/pom.xml +++ b/contacts-jquerymobile/functional-tests/pom.xml @@ -24,11 +24,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 contacts-jquerymobile-test-webdriver - 31.0.0.Final-SNAPSHOT + 31.0.0.Final Quickstart: Contacts JQueryMobile test via WebDriver with Arquillian This project tests a Contacts JQueryMobile for use on JBoss EAP by WebDriver @@ -36,7 +36,7 @@ false - 20150729 + 20231013.0.0.redhat-00001 31.0.0.Beta1 diff --git a/contacts-jquerymobile/pom.xml b/contacts-jquerymobile/pom.xml index 8c8e56d787..b3887f8dc0 100644 --- a/contacts-jquerymobile/pom.xml +++ b/contacts-jquerymobile/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 contacts-jquerymobile - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: contacts-jquerymobile A Jakarta EE HTML5 mobile web application for use with JBoss EAP diff --git a/dist/pom.xml b/dist/pom.xml index daf7b11ab7..29f7354a38 100644 --- a/dist/pom.xml +++ b/dist/pom.xml @@ -25,7 +25,7 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 31.0.0.Final-SNAPSHOT + 31.0.0.Final quickstarts-dist diff --git a/ee-security/README-source.adoc b/ee-security/README-source.adoc new file mode 100644 index 0000000000..ecd5544742 --- /dev/null +++ b/ee-security/README-source.adoc @@ -0,0 +1,133 @@ +include::../shared-doc/attributes.adoc[] + += ee-security: Using Jakarta EE Security +:author: Darran Lofthouse +:level: Intermediate +:technologies: EE Security, Servlet, CDI +:openshift: true + +[abstract] +The `ee-security` quickstart demonstrates Jakarta EE security. + +:standalone-server-type: default +:archiveType: war +:restoreScriptName: restore-configuration.cli + +== What is it? + +The `ee-security` quickstart is an example project showing the use of Jakarta EE security in {productNameFull}. + +The deployment in this quickstart contains a simple HTTP servlet, which is secured using a custom `HttpAuthenticationMechanism`. The authentication mechanism in turn makes use of a custom `IdentityStore`. + +This quickstart is hard coded to work with a user `quickstartUser` with password `quickstartPwd1!`. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] + +[[configure_the_server]] +=== Configure the Server + +You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. You'll need to reload the configuration after that: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --commands=reload +---- + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/secured + +NOTE: If you attempt to access that URL, you will see "Unauthorized". + +To see and manipulate the HTTP headers within the HTTP requests, it is recommended to use a client like `curl` to invoke the servlet. + +[source,options="nowrap"] +---- +$ curl -v http://localhost:8080/ee-security/secured +... +< HTTP/1.1 401 Unauthorized +< Connection: keep-alive +< X-MESSAGE: Please resubmit the request with a username specified using the X-USERNAME and a password specified using the X-PASSWORD header. +---- + +This first request shows the client is being prompted to authenticate. The `X-MESSAGE` header is providing additional information as to how the client can achieve this. + +The request can now be submitted with the previously added user. + +[source,options="nowrap"] +---- +$ curl -v http://localhost:8080/ee-security/secured -H 'X-Username:quickstartUser' -H 'X-Password:quickstartPwd1!' +... +> GET /ee-security/secured HTTP/1.1 +> Host: localhost:8080 +> X-Username:quickstartUser +> X-Password:quickstartPwd1! +> +< HTTP/1.1 200 OK +< Connection: keep-alive +< Content-Length: 125 +< +SecuredServlet - doGet() +Identity as available from SecurityContext 'quickstartUser' +Identity as available from injection 'quickstartUser' +---- + +The resulting output shows authentication was successful and the correct identity has been established. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + diff --git a/ee-security/README.adoc b/ee-security/README.adoc index a81eb62ab3..ae0592a38b 100644 --- a/ee-security/README.adoc +++ b/ee-security/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ee-security +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ee-security: Using Jakarta EE Security :author: Darran Lofthouse @@ -23,19 +220,268 @@ The deployment in this quickstart contains a simple HTTP servlet, which is secur This quickstart is hard coded to work with a user `quickstartUser` with password `quickstartPwd1!`. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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!: [[configure_the_server]] === Configure the Server @@ -74,7 +520,114 @@ $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --commands=reload ---- // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -118,17 +671,739 @@ Identity as available from injection 'quickstartUser' The resulting output shows authentication was successful and the correct identity has been established. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] +:leveloffset: +3 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: ee-security +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[] + + +[[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 + +// 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 +:leveloffset!: diff --git a/ee-security/charts/helm.yaml b/ee-security/charts/helm.yaml index 4c393c54d9..d989be2242 100644 --- a/ee-security/charts/helm.yaml +++ b/ee-security/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: ee-security deploy: replicas: 1 \ No newline at end of file diff --git a/ee-security/pom.xml b/ee-security/pom.xml index d49b1346d5..b971a8034c 100644 --- a/ee-security/pom.xml +++ b/ee-security/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ee-security - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ee-security This project demonstrates using EE security @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-multi-server/README-source.adoc b/ejb-multi-server/README-source.adoc new file mode 100644 index 0000000000..102d189cd0 --- /dev/null +++ b/ejb-multi-server/README-source.adoc @@ -0,0 +1,262 @@ +include::../shared-doc/attributes.adoc[] + += ejb-multi-server: EJB Communication Across Servers +:author: Wolf-Dieter Fink +:level: Advanced +:technologies: EJB, EAR + +[abstract] +The `ejb-multi-server` quickstart shows how to communicate between multiple applications deployed to different servers using an EJB to log the invocation. + +:managed-domain-type: default +:archiveType: ear +:jbds-not-supported: + +== What is it? + +The `ejb-multi-server` quickstart demonstrates communication between applications deployed to different {productNameFull} servers. Each application is deployed as an EAR and contains a simple EJB bean. The only function of each bean is to log the invocation. + +This example consists of the following Maven projects, each with a shared parent: + +[cols="40%,60%",options="headers"] +|=== +|Project |Description + +|`app-main` +|An application that can be called by the client. It can also call the different sub-applications. + +a|`app-one` + +`app-two` +|These simple applications contain an EJB subproject that builds the `ejb.jar` file and an EAR subproject that builds the `app.ear` file. Each application contains only one EJB that logs a statement on a method call and returns the `jboss.node.name` and credentials. + +|`app-web` +|A simple WAR application. It consists of one servlet that demonstrates how to invoke EJBs on a different server. + +|`client` +|This project builds the standalone client and executes it. +|=== + +The root `pom.xml` builds each of the subprojects in an appropriate order. + +The server configuration is done using CLI batch scripts located in the root of the quickstart folder. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +[[start_with_a_clean_server_install]] +== Start with a Clean Server Install + +It is important to start with a clean version of {productName} before testing this quickstart. Make sure you unzip or install a fresh {productName} instance. + +[[add_the_application_users]] +== Add the Application Users + +The following users must be added to the `ApplicationRealm` to run this quickstart. Make sure you use the names and passwords specified in the table as they are required to run this example. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickuser |ApplicationRealm |quick-123 | +|quickuser1 |ApplicationRealm |quick123+ | +|quickuser2 |ApplicationRealm |quick+123 | +|=== + +To add the users, open a terminal and type the following commands. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser -p quick-123 +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser1 -p quick123+ +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser2 -p quick+123 +---- + +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +If you prefer, you can use the `add-user` utility interactively. For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. + +// Back Up the {productName} Managed Domain Configuration +include::../shared-doc/back-up-managed-domain-configuration.adoc[leveloffset=+1] +// Start the {productName} Managed Domain +include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the domain server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `install-domain.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:start_with_a_clean_server_install[Start with clean {productName} installation]. +* xref:back_up_managed_domain_configuration[Back up the {productName} managed domain configuration]. +* xref:add_the_application_users[Add the application users]. +* xref:start_eap_managed_domain[Start the {productName} managed domain]. + +. Review the `install-domain.cli` file in the root of this quickstart directory. This script configures and starts multiple servers needed to run this quickstart. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh -c --file=install-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ +You should see a result of `"outcome" => "success"` for every step in the execution. ++ +IMPORTANT: Depending on your machine configuration, you might see "Exception in thread "main" java.lang.OutOfMemoryError: unable to create new native thread" exceptions in the server log when you run this script. If you do, you must increase the ulimit open files and max user processes settings. Instructions to do this are located here: http://ithubinfo.blogspot.com/2013/07/how-to-increase-ulimit-open-file-and.html. After you update the ulimit settings, you must reboot and start with a fresh instance of the server. + +[[review_the_modified_server_configuration]] +== Review the Modified Server Configuration + +There are too many additions to the configuration files to list here. Feel free to compare the `domain.xml` and `host.xml` to the backup copies to see the changes made to configure the server to run this quickstart. + + + + +[[build_and_deploy_the_quickstart]] +== Build and Deploy the Quickstart + +. Make sure you have xref:install_the_quickstart_parent_artifact_in_maven[installed the quickstart parent artifact] in your Maven repository. +. Make sure you have started and configured the {productName} server successfully as described above. +. Open a terminal and navigate to the root directory of this quickstart. +. Type this command to build the artifacts. ++ +[source,options="nowrap"] +---- +$ mvn clean install +---- ++ +You should see `BUILD SUCCESS` at the end of the build `SUCCESS` messages for each component. + +. In the same terminal, deploy the applications using the provided CLI batch script by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh -c --file=deploy-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +This deploys the `app-*.ear` files to different server groups of the running domain. You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. You might see the following warnings in the server log. You can ignore these warnings. ++ +[source,options="nowrap"] +---- +[Server:app-oneB] 13:00:13,346 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +[Server:app-oneB] 13:00:13,346 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, 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) +[Server:app-oneB] 13:00:13,347 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +[Server:app-oneB] 13:00:13,347 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 13) 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) +[Server:app-oneA] 13:00:13,407 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +[Server:app-oneA] 13:00:13,408 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, 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) +[Server:app-oneA] 13:00:13,408 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +[Server:app-oneA] 13:00:13,408 WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 11) 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) +---- + +IMPORTANT: If errors appear in the `server.log` when installing or deploying the quickstart, stop the domain and restart it. This should ensure further steps run correctly. + +[[access_the_remote_client_application]] +== Access the Remote Client Application + +This example shows how to invoke an EJB from a remote standalone application. + +. Make sure that the deployments are successful as described above. +. Navigate to the quickstart `client/` subdirectory. +. Type this command to run the application: ++ +[source,options="nowrap"] +---- +$ mvn exec:java +---- ++ +The client will output the following information provided by the applications: ++ +[source,options="nowrap"] +---- +InvokeAll succeed: MainApp[quickuser]@primary:app-main > [ app1[quickuser1]@primary:app-oneA > app2[quickuser2]@primary:app-twoA ; app2[quickuser2]@primary:app-twoA +---- ++ +This output shows that the `MainApp` is called with the user `quickuser` at node `primary:app-main` and the sub-call is proceeded by the `primary:app-oneA` node as `quickuser1` and `primary:app-twoA` node as `quickuser2`. + +. Review the server log files to see the bean invocations on the servers. + +. If it is necessary to invoke the client with a different {productName} version the main class can be invoked by using the following command from the root directory of this quickstart. Replace __{jbossHomeName}__ with your current installation path. The output should be similar to the previous mvn executions. ++ +[subs=normal] +---- +java -cp $__{jbossHomeName}__/bin/client/jboss-client.jar:app-main/ejb/target/ejb-multi-server-app-main-ejb-client.jar:app-two/ejb/target/ejb-multi-server-app-two-ejb-client.jar:client/target/ejb-multi-server-client.jar org.jboss.as.quickstarts.ejb.multi.server.Client +---- + +[IMPORTANT] +==== +* If `exec` is called multiple times, the invocation for `app1` might use `app-oneA` and `app-oneB` node due to cluster loadbalancing. +* A {productName} will deny the invocation of unsecured methods of `appOne`/`appTwo` since security is enabled but the method does not include `@Roles`. You need to set `default-missing-method-permissions-deny-access = false` for the `ejb3` subsystem within the domain profile `ha` and `default` to allow the method invocation. See the `install-domain.cli` script. +==== + +[[access_the_jsf_application_inside_the_main_application]] +== Access the JSF Application Inside the Main Application + +The JSF example shows different annotations to inject the EJB. Also how to handle the annotation if different beans implement the same interface and therefore the container is not able to decide which bean needs to be injected without additional informations. + +. Make sure that the deployments are successful as described above. +. Use a browser to access the JSF application at the following URL: http://localhost:8080/ejb-multi-server-app-main-web/ +. Insert a message in the Text input and invoke the different methods. The result is shown in the browser. +. See server logfiles and find your given message logged as INFO. + +[[access_the_servlet_application_deployed_as_a_war_inside_a_minimal_server]] +== Access the Servlet Application Deployed as a WAR Inside a Minimal Server + +An example how to access EJBs from a separate instance which only contains a web application. + +. Make sure that the deployments are successful as described above. +. Use a browser to access the Servlet at the following URL: http://localhost:8380/ejb-multi-server-app-web/ +. The Servlet will invoke the remote EJBs directly and show the results, compare that the invocation is successful + +[[undeploy_the_quickstart]] +== Undeploy the Quickstart + +. xref:start_eap_managed_domain[Start the {productName} managed domain] as described above. +. Open a terminal and navigate to the root directory of this quickstart. +. When you are finished testing, type this command to undeploy the archive: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=undeploy-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat`. + + +// Restore the {productName} Managed Domain Configuration Manually +include::../shared-doc/restore-managed-domain-configuration-manual.adoc[leveloffset=+1] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +EJB Client (ejb-client) currently has limited support in the Eclipse Web Tools Platform (WTP). + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/ejb-multi-server/README.adoc b/ejb-multi-server/README.adoc index 102d189cd0..96d518d27a 100644 --- a/ejb-multi-server/README.adoc +++ b/ejb-multi-server/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-multi-server +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-multi-server: EJB Communication Across Servers :author: Wolf-Dieter Fink @@ -42,11 +239,66 @@ The root `pom.xml` builds each of the subprojects in an appropriate order. The server configuration is done using CLI batch scripts located in the root of the quickstart folder. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: [[start_with_a_clean_server_install]] == Start with a Clean Server Install @@ -81,9 +333,58 @@ NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. If you prefer, you can use the `add-user` utility interactively. For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. // Back Up the {productName} Managed Domain Configuration -include::../shared-doc/back-up-managed-domain-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_managed_domain_configuration]] += Back Up the {productName} Managed Domain Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a managed domain and +// needs to back up the server configuration files before running +// a CLI script to modify the server. +//****************************************************************************** + +Before you begin, back up your server configuration files. + +. If it is running, stop the {productName} server. +. Back up the following files: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}__/domain/configuration/domain.xml +__{jbossHomeName}__/domain/configuration/host.xml +---- + +After you have completed testing this quickstart, you can replace these file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Managed Domain -include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+1] +:leveloffset: +1 + +[[start_the_eap_managed_domain]] += Start the {productName} Managed Domain +//****************************************************************************** +// Include this template if your quickstart requires a normal start of a +// managed domain. +// +// This template does not currently support passing arguments for starting +// the domain, but it could be added. +// +// * Define the managed domain profile type. Supported values are: +// :managed-domain-type: default +// +//****************************************************************************** + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} managed domain by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/domain.sh +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\domain.bat` script. + +:leveloffset!: [[configure_the_server]] == Configure the Server @@ -241,15 +542,81 @@ NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat`. // Restore the {productName} Managed Domain Configuration Manually -include::../shared-doc/restore-managed-domain-configuration-manual.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_managed_domain_configuration_manually]] += Restore the {productName} Managed Domain Configuration Manually +//****************************************************************************** +// Include this template to restore the server configuration if your +// quickstart modified the managed domain configuration files. +//****************************************************************************** + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copies the configuration files. + +* If it is running, stop the {productName} server. +* Replace the following files with the backup copies of the files. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}__/domain/configuration/domain.xml +__{jbossHomeName}__/domain/configuration/host.xml +---- + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions EJB Client (ejb-client) currently has limited support in the Eclipse Web Tools Platform (WTP). // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -259,4 +626,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/ejb-multi-server/app-main/ear/pom.xml b/ejb-multi-server/app-main/ear/pom.xml index 83d161a7ab..008aceffac 100644 --- a/ejb-multi-server/app-main/ear/pom.xml +++ b/ejb-multi-server/app-main/ear/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-main - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-main-ear ear @@ -75,7 +75,7 @@ Application Main A simple quickstart application to demonstrate the server-server communication - 7 + 8 true true diff --git a/ejb-multi-server/app-main/ejb/pom.xml b/ejb-multi-server/app-main/ejb/pom.xml index 32f817e2dc..9f59cad47c 100644 --- a/ejb-multi-server/app-main/ejb/pom.xml +++ b/ejb-multi-server/app-main/ejb/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-main - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-main-ejb ejb diff --git a/ejb-multi-server/app-main/pom.xml b/ejb-multi-server/app-main/pom.xml index 522bc0a1e0..246b8b3b88 100644 --- a/ejb-multi-server/app-main/pom.xml +++ b/ejb-multi-server/app-main/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ../pom.xml ejb-multi-server-app-main diff --git a/ejb-multi-server/app-main/web/pom.xml b/ejb-multi-server/app-main/web/pom.xml index 75a98c5e35..9695290138 100644 --- a/ejb-multi-server/app-main/web/pom.xml +++ b/ejb-multi-server/app-main/web/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-main - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-main-web war diff --git a/ejb-multi-server/app-one/ear/pom.xml b/ejb-multi-server/app-one/ear/pom.xml index f61f54ec53..22dd1a6b19 100644 --- a/ejb-multi-server/app-one/ear/pom.xml +++ b/ejb-multi-server/app-one/ear/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-one - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-one-ear ear @@ -54,7 +54,7 @@ Application One A simple quickstart application to demonstrate the server-server communication - 7 + 8 true diff --git a/ejb-multi-server/app-one/ejb/pom.xml b/ejb-multi-server/app-one/ejb/pom.xml index 1fba6b18ff..c54aca3fbd 100644 --- a/ejb-multi-server/app-one/ejb/pom.xml +++ b/ejb-multi-server/app-one/ejb/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-one - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-one-ejb ejb diff --git a/ejb-multi-server/app-one/pom.xml b/ejb-multi-server/app-one/pom.xml index 99af052052..3dce7a37af 100644 --- a/ejb-multi-server/app-one/pom.xml +++ b/ejb-multi-server/app-one/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-one pom diff --git a/ejb-multi-server/app-two/ear/pom.xml b/ejb-multi-server/app-two/ear/pom.xml index 1ae905e226..2b65f1908a 100644 --- a/ejb-multi-server/app-two/ear/pom.xml +++ b/ejb-multi-server/app-two/ear/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-two - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-two-ear ear @@ -55,7 +55,7 @@ Application Two A simple quickstart application to demonstrate the server-server communication - 7 + 8 true diff --git a/ejb-multi-server/app-two/ejb/pom.xml b/ejb-multi-server/app-two/ejb/pom.xml index a5ce957a20..5b54f6d6ac 100644 --- a/ejb-multi-server/app-two/ejb/pom.xml +++ b/ejb-multi-server/app-two/ejb/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server-app-two - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-two-ejb ejb diff --git a/ejb-multi-server/app-two/pom.xml b/ejb-multi-server/app-two/pom.xml index 992921ac67..a73141feba 100644 --- a/ejb-multi-server/app-two/pom.xml +++ b/ejb-multi-server/app-two/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-two pom diff --git a/ejb-multi-server/app-web/pom.xml b/ejb-multi-server/app-web/pom.xml index b95d103422..8a17105d82 100644 --- a/ejb-multi-server/app-web/pom.xml +++ b/ejb-multi-server/app-web/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-app-web war diff --git a/ejb-multi-server/client/pom.xml b/ejb-multi-server/client/pom.xml index 0afb653a32..9487d80f57 100644 --- a/ejb-multi-server/client/pom.xml +++ b/ejb-multi-server/client/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-multi-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-multi-server-client jar diff --git a/ejb-multi-server/pom.xml b/ejb-multi-server/pom.xml index 7b5c7e9b20..26008c4390 100644 --- a/ejb-multi-server/pom.xml +++ b/ejb-multi-server/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-multi-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom Quickstart: ejb-multi-server A project that demonstrates multiple applications deployed on different servers. @@ -47,7 +47,7 @@ - 31.0.0.Beta1 + 31.0.0.Final diff --git a/ejb-remote/README-source.adoc b/ejb-remote/README-source.adoc new file mode 100644 index 0000000000..88050aa579 --- /dev/null +++ b/ejb-remote/README-source.adoc @@ -0,0 +1,105 @@ +include::../shared-doc/attributes.adoc[] + += ejb-remote: Remote EJB Client Example +:author: Jaikiran Pai, Mike Musgrove +:level: Intermediate +:technologies: EJB, JNDI +:openshift: true + +[abstract] +The `ejb-remote` quickstart uses EJB and JNDI to demonstrate how to access an EJB, deployed to {productName}, from a remote Java client application. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `ejb-remote` quickstart shows how to access an EJB from a remote Java client application. It demonstrates the use of EJB and JNDI in {productNameFull}. + +There are two components to this example: + +. A server side component: ++ +The server component is comprised of a stateful EJB and a stateless EJB. It provides both an EJB JAR that is deployed to the server and a JAR file containing the remote business interfaces required by the remote client application. + +. A remote client application that accesses the server component. ++ +The remote client application depends on the remote business interfaces from the server component. This application looks up the stateless and stateful beans via JNDI and invokes a number of methods on them. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 + +// Add the Authorized Application User +include::../shared-doc/add-application-user.adoc[leveloffset=+2] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +=== Investigate the Console Output + +When the client application is run by the EJBRemoteIT tests, it performs the following steps: + +. Obtains a stateless session bean instance. +. Sends method invocations to the stateless bean to add two numbers, and then displays the result. +. Sends a second invocation to the stateless bean subtract two numbers, and then displays the result. +. Obtains a stateful session bean instance. +. Sends several method invocations to the stateful bean to increment a field in the bean, displaying the result each time. +. Sends several method invocations to the stateful bean to decrement a field in the bean, displaying the result each time. + +The following output is displayed in the terminal window: + +[source,options="nowrap"] +---- +Obtained a remote stateless calculator for invocation +Adding 204 and 340 via the remote stateless calculator deployed on the server +Remote calculator returned sum = 544 +Subtracting 2332 from 3434 via the remote stateless calculator deployed on the server +Remote calculator returned difference = 1102 +Obtained a remote stateful counter for invocation +Counter will now be incremented 5 times +Incrementing counter +Count after increment is 1 +Incrementing counter +Count after increment is 2 +Incrementing counter +Count after increment is 3 +Incrementing counter +Count after increment is 4 +Incrementing counter +Count after increment is 5 +Counter will now be decremented 5 times +Decrementing counter +Count after decrement is 4 +Decrementing counter +Count after decrement is 3 +Decrementing counter +Count after decrement is 2 +Decrementing counter +Count after decrement is 1 +Decrementing counter +Count after decrement is 0 +---- + +Logging statements have been removed from this output here to make it clearer. + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/ejb-remote/README.adoc b/ejb-remote/README.adoc index 40c45d529b..c782f96b93 100644 --- a/ejb-remote/README.adoc +++ b/ejb-remote/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-remote +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-remote: Remote EJB Client Example :author: Jaikiran Pai, Mike Musgrove @@ -28,26 +225,366 @@ The server component is comprised of a stateful EJB and a stateless EJB. It prov The remote client application depends on the remote business interfaces from the server component. This application looks up the stateless and stateful beans via JNDI and invokes a number of methods on them. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 // Add the Authorized Application User -include::../shared-doc/add-application-user.adoc[leveloffset=+2] +:leveloffset: +2 + +[[add_the_application_user]] += Add the Authorized Application User + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true + +This quickstart uses secured application interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: === Investigate the Console Output @@ -97,10 +634,599 @@ Count after decrement is 0 Logging statements have been removed from this output here to make it clearer. // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: ejb-remote +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/ejb-remote/charts/helm.yaml b/ejb-remote/charts/helm.yaml index d0e5fcb7e9..7cc94e5957 100644 --- a/ejb-remote/charts/helm.yaml +++ b/ejb-remote/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: ejb-remote deploy: replicas: 1 \ No newline at end of file diff --git a/ejb-remote/pom.xml b/ejb-remote/pom.xml index 6d58f83e37..a995bf2bea 100644 --- a/ejb-remote/pom.xml +++ b/ejb-remote/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-remote - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ejb-remote This project demonstrates how to access an EJB from a remote client @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-security-context-propagation/README-source.adoc b/ejb-security-context-propagation/README-source.adoc new file mode 100644 index 0000000000..edc9e6430a --- /dev/null +++ b/ejb-security-context-propagation/README-source.adoc @@ -0,0 +1,310 @@ +include::../shared-doc/attributes.adoc[] + += ejb-security-context-propagation: Demonstrate security context propagation in EJB to remote EJB calls +:author: Stefan Guilhen +:level: Advanced +:technologies: EJB, Security + +[abstract] +The `ejb-security-context-propagation` quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration + +:standalone-server-type: default +:archiveType: jar +:restoreScriptName: restore-configuration.cli +:app-user-groups: guest,user +:admin-user-groups: guest,user,admin + +== What is it? + +The `ejb-security-context-propagation` quickstart demonstrates how the security context of an EJB can be propagated to a +remote EJB in {productNameFull}. + +The quickstart makes use of two EJBs, xref:secured_ejb[`SecuredEJB`] and xref:intermediate_ejb[`IntermediateEJB`], to verify that the security context propagation is correct, and a xref:remote_client[`RemoteClient`] standalone client. + +[[secured_ejb]] +SecuredEJB:: + +The `SecuredEJB` has four methods. ++ +[source,java,options="nowrap"] +---- +String getSecurityInformation(); +String guestMethod(); +String userMethod(); +String adminMethod(); +---- ++ +The `getSecurityInformation()` method can be called by all users that are created in this quickstart. +The purpose of this method is to return a `String` containing the name of the `Principal` that called the EJB, along with the user's authorized role information, for example: ++ +[source,options="nowrap"] +---- +[Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false] +---- ++ +The `guestMethod()`, `userMethod()`, and `adminMethod()`` methods are annotated to require that the calling user is authorized for roles `guest`, `user` and `admin` respectively. + +[[intermediate_ejb]] +IntermediateEJB:: + +The `IntermediateEJB` contains a single method. +Its purpose is to make use of a remote connection and invoke each of the methods on the `SecuredEJB`. +A summary is then returned with the outcome of the calls. + +[[remote_client]] +RemoteClient:: + +Finally there is the `RemoteClient` stand-alone client. The client makes calls using the identity of the established connection. ++ +In the real world, remote calls between servers in the servers-to-server scenario would truly be remote and separate. +For the purpose of this quickstart, we make use of a loopback connection to the same server so we do not need two servers just to run the test. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Prerequisites + +This quickstart uses the default standalone configuration plus the modifications described here. + +It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment. + +// Add the Authorized Application and Management Users +include::../shared-doc/add-application-and-management-users.adoc[leveloffset=+1] +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables security for the quickstart deployment. Comments in the script describe the purpose of each block of commands. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +. Because this example quickstart demonstrates security, system exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing `__{jbossHomeName}__` with the path to your server: +[[suppress_system_exceptions]] ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-system-exception.cli +---- ++ +NOTE: For Windows,use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following `application-security-domain` was added to the `ejb3` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +The `application-security-domain` enables security for the quickstart EJBs. It maps the `quickstart-domain` security domain that is set in the EJBs using the Java annotation `@SecurityDomain("quickstart-domain")` to the Elytron `ApplicationDomain` that is responsible for authenticating and authorizing access to the EJBs. + +. The following `ejb-outbound-configuration` authentication configuration and `ejb-outbound-context` authentication context were added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + + +---- ++ +The `ejb-outbound-configuration` contains the authentication configuration that will be used when invoking a method on a remote EJB, for example when `IntermediateEJB` calls the methods on the `SecuredEJB`. The above configuration specifies that the identity that is currently authenticated to the `ApplicationDomain` will be used to establish the connection to the remote EJB. The `sasl-mechanism-selector` defines the SASL mechanisms that should be tried. In this quickstart the `PLAIN` mechanism has been chosen because other challenge-response mechanisms such as `DIGEST-MD5` can't provide the original credential to establish the connection to the remote EJB. ++ +The `ejb-outbound-context` is the authentication context that is used by the remote outbound connection and it automatically selects the `ejb-outbound-configuration`. + +. The following `ejb-outbound` outbound-socket-binding connection was created within the `standard-sockets` socket-binding-group: ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +For the purpose of the quickstart we just need an outbound connection that loops back to the same server. This will be sufficient to demonstrate the server-to-server capabilities. + +. The following `ejb-outbound-connection` remote-outbound-connection was added to the outbound-connections within the `remoting` subsytem: ++ +[source,xml,options="nowrap"] +---- + + + +---- + +. Finally, the `application-sasl-authentication` factory was updated in the `elytron` subsystem to include the `PLAIN` mechanism: ++ +[source,xml,options="nowrap"] +---- + + + + + + + + + +---- + ++ +Note that the `http-connector` in the `remoting` subsystem uses this `application-sasl-authentication` authentication factory. It allows for the identity that was established in the connection authentication to be propagated to the components. + +. If you xref:suppress_system_exceptions[ran the script to suppress system exceptions], you should see the following configuration in the `ejb3` subsystem. ++ +[source,xml,options="nowrap"] +---- + +---- + +// Build and Deploy the Quickstart JAR +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +== Investigate the Console Output + +When you run the integration tests, you see the following output. Note there may be other log messages interspersed between these. + +[source,options="nowrap"] +---- +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +* * IntermediateEJB - Begin Testing with principal quickstartUser * * + +Remote Security Information: [Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false] +Can invoke guestMethod? true +Can invoke userMethod? true +Can invoke adminMethod? false + +* * IntermediateEJB - End Testing * * +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +* * IntermediateEJB - Begin Testing with principal quickstartAdmin * * + +Remote Security Information: [Principal=[quickstartAdmin], In role [guest]=true, In role [user]=true, In role [admin]=true] +Can invoke guestMethod? true +Can invoke userMethod? true +Can invoke adminMethod? true + +* * IntermediateEJB - End Testing * * +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +---- + +As can be seen from the output the identities authenticated to the intermediate EJB were propagated all the way to the remote +secured EJB and their roles have been correctly evaluated. + +== Investigate the Server Console Output + +If you did not xref:suppress_system_exceptions[run the script to suppress system exceptions], you should see the following exceptions in the {productName} +server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not +authorized. + +[source,options="nowrap"] +---- +ERROR [org.jboss.as.ejb3.invocation] (default task-57) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod(): jakarta.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod() of bean: SecuredEJB is not allowed + at org.jboss.as.ejb3.security.RolesAllowedInterceptor.processInvocation(RolesAllowedInterceptor.java:67) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ejb3.security.SecurityDomainInterceptor.processInvocation(SecurityDomainInterceptor.java:44) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ejb3.deployment.processors.StartupAwaitInterceptor.processInvocation(StartupAwaitInterceptor.java:22) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ejb3.component.interceptors.ShutDownInterceptorFactory$1.processInvocation(ShutDownInterceptorFactory.java:64) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ejb3.deployment.processors.EjbSuspendInterceptor.processInvocation(EjbSuspendInterceptor.java:57) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ejb3.component.interceptors.LoggingInterceptor.processInvocation(LoggingInterceptor.java:67) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ee.component.NamespaceContextInterceptor.processInvocation(NamespaceContextInterceptor.java:50) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.as.ejb3.component.interceptors.AdditionalSetupInterceptor.processInvocation(AdditionalSetupInterceptor.java:54) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.invocation.ContextClassLoaderInterceptor.processInvocation(ContextClassLoaderInterceptor.java:60) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.invocation.InterceptorContext.run(InterceptorContext.java:438) + at org.wildfly.security.manager.WildFlySecurityManager.doChecked(WildFlySecurityManager.java:609) + at org.jboss.invocation.AccessCheckingInterceptor.processInvocation(AccessCheckingInterceptor.java:57) + at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422) + at org.jboss.invocation.ChainedInterceptor.processInvocation(ChainedInterceptor.java:53) + at org.jboss.as.ee.component.ViewService$View.invoke(ViewService.java:198) + at org.wildfly.security.auth.server.SecurityIdentity.runAsFunctionEx(SecurityIdentity.java:380) + at org.jboss.as.ejb3.remote.AssociationImpl.invokeWithIdentity(AssociationImpl.java:492) + at org.jboss.as.ejb3.remote.AssociationImpl.invokeMethod(AssociationImpl.java:487) + at org.jboss.as.ejb3.remote.AssociationImpl.lambda$receiveInvocationRequest$0(AssociationImpl.java:188) + at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142) + at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) + at java.lang.Thread.run(Thread.java:745) +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script reverts the changes made to the `ejb3`, `elytron` and `remoting` subsystems. You should see the following result when you run the script. + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +[NOTE] +==== +If you xref:suppress_system_exceptions[ran the script to suppress system exceptions], you need to restore the logging of system exceptions. Run the above command, passing `restore-system-exception.cli` instead of `restore-configuration.cli` for the file name. You should see the following result when you run the script. + +[source,options="nowrap"] +---- +The batch executed successfully +---- +==== + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file diff --git a/ejb-security-context-propagation/README.adoc b/ejb-security-context-propagation/README.adoc index 5c3f2376b0..8962a62a78 100644 --- a/ejb-security-context-propagation/README.adoc +++ b/ejb-security-context-propagation/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-security-context-propagation +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-security-context-propagation: Demonstrate security context propagation in EJB to remote EJB calls :author: Stefan Guilhen @@ -61,11 +258,66 @@ In the real world, remote calls between servers in the servers-to-server scenari For the purpose of this quickstart, we make use of a loopback connection to the same server so we do not need two servers just to run the test. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Prerequisites @@ -74,11 +326,259 @@ This quickstart uses the default standalone configuration plus the modifications It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment. // Add the Authorized Application and Management Users -include::../shared-doc/add-application-and-management-users.adoc[leveloffset=+1] +:leveloffset: +1 + +[[add_the_application_management_users]] += Add the Authorized Application and Management Users + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users +// :admin-user-groups: admin, superusers + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +ifdef::admin-user-groups[] +:admin-group-list: {admin-user-groups} +:admin-group-command: -g '{admin-user-groups}' +endif::admin-user-groups[] + +ifndef::admin-user-groups[] +:admin-group-list: +:admin-group-command: +endif::admin-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true +:addQuickstartAdmin: true + +This quickstart uses secured management interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|quickstartAdmin | ManagementRealm | adminPwd1! | {admin-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' {admin-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -196,10 +696,141 @@ Note that the `http-connector` in the `remoting` subsystem uses this `applicatio ---- // Build and Deploy the Quickstart JAR -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: == Investigate the Console Output @@ -275,11 +906,87 @@ ERROR [org.jboss.as.ejb3.invocation] (default task-57) WFLYEJB0034: EJB Invocati ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script reverts the changes made to the `ejb3`, `elytron` and `remoting` subsystems. You should see the following result when you run the script. @@ -301,11 +1008,354 @@ The batch executed successfully ==== // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] // Quickstart not compatible with OpenShift -include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file +:leveloffset: +1 + +[[openshift_incompatibility]] += {xpaasproduct-shortname} Incompatibility + +This quickstart is not compatible with {xpaasproduct-shortname} or {xpaasproductOpenShiftOnline-shortname} templates. + +:leveloffset!: diff --git a/ejb-security-context-propagation/pom.xml b/ejb-security-context-propagation/pom.xml index b439f27d1b..ed5007a02b 100644 --- a/ejb-security-context-propagation/pom.xml +++ b/ejb-security-context-propagation/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-security-context-propagation - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ejb-security-context-propagation This project demonstrates the security context propagation between remote EJBs @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-security-programmatic-auth/README-source.adoc b/ejb-security-programmatic-auth/README-source.adoc new file mode 100644 index 0000000000..2a7adda5b5 --- /dev/null +++ b/ejb-security-programmatic-auth/README-source.adoc @@ -0,0 +1,186 @@ +include::../shared-doc/attributes.adoc[] + += ejb-security-programmatic-auth: Using the programmatic API to invoke a remote EJB using different identities +:author: Stefan Guilhen +:level: Intermediate +:technologies: EJB, Security + +[abstract] +The `ejb-security-programmatic-auth` quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB. + +:standalone-server-type: default +:archiveType: jar +:restoreScriptName: restore-configuration.cli +:app-user-groups: guest +:admin-user-groups: guest,admin + +== What is it? + +The `ejb-security-programmatic-auth` quickstart demonstrates how to invoke a remote secured EJB using the `Elytron` client API to establish different identities. The quickstart client application accomplishes that by looking up and invoking the secured EJB under different `AuthenticationContext`s. Each context is setup to use a different identities and credentials. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Add the Authorized Application and Management Users +include::../shared-doc/add-application-and-management-users.adoc[leveloffset=+1] +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables security for the quickstart components. Comments in the script describe the purpose of each block of commands. +. 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. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following `application-security-domain` mapping was added to the `ejb3` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +The `application-security-domain` essentially enables security for the quickstart EJBs. It maps the `quickstart-domain` that was set in the EJBs via annotation to the Elytron `ApplicationDomain` that will be responsible for authenticating and authorizing access to the EJBs. + +. Take a look at the existing `http-connector` configuration in the `remoting` subsystem. Notice that it uses the `application-sasl-authentication` authentication factory, +which references the `ApplicationDomain` security domain mentioned above: ++ +[source,xml,options="nowrap"] +---- + +---- ++ +This allows for the identity that was established in the connection authentication to be propagated to the components. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your terminal is still in the same folder. + +Type the following command to execute the client. + +[source,options="nowrap"] +---- +$ mvn exec:exec +---- + +== Investigate the Console Output + +When you run the `mvn exec:exec` command, you see the following output. Note there may be other log messages interspersed between these. + +[source,options="nowrap"] +---- +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Called secured bean, caller principal quickstartUser + +Principal has admin permission: false +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Called secured bean, caller principal quickstartAdmin + +Principal has admin permission: true +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +---- + +As expected, the `quickstart` user is able to call the methods available for `guest`, but does not have the `admin` permission to call administrative methods on the remote EJB. The `quickstartAdmin` on the other hand has permissions to call both methods. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script reverts the changes made to the `ejb3` and `remoting` subsystems. You should see the following result when you run the script. + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +* Make sure you xref:add_the_application_management_users[add the authorized application and management users] as described above. +* Make sure you configure the server by running the JBoss CLI script as described above under xref:configure_the_server[Configure the Server]. +* Right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. +Enter `clean package wildfly:deploy` for the *Goals* and click *Run*. This deploys the `{artifactId}` JAR to the {productName} server. +* Right-click on the *{artifactId}* project and choose *Run As* -> *Run Configurations...*. +* Enter `exec:exec` for the *Goals* and click *Run*. +* Review the output in the console window. You should see the following output. ++ +[source,options="nowrap"] +---- +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Called secured bean, caller principal quickstartUser +Principal has admin permission: false +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Called secured bean, caller principal quickstartAdmin +Principal has admin permission: true +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +---- + +* To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. + +* Make sure you xref:restore_the_server_configuration[restore the {productName} standalone server configuration] when you have completed testing this quickstart. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/ejb-security-programmatic-auth/README.adoc b/ejb-security-programmatic-auth/README.adoc index f85ce9729a..f105052093 100644 --- a/ejb-security-programmatic-auth/README.adoc +++ b/ejb-security-programmatic-auth/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-security-programmatic-auth +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-security-programmatic-auth: Using the programmatic API to invoke a remote EJB using different identities :author: Stefan Guilhen @@ -20,17 +217,320 @@ The `ejb-security-programmatic-auth` quickstart demonstrates how to programmatic The `ejb-security-programmatic-auth` quickstart demonstrates how to invoke a remote secured EJB using the `Elytron` client API to establish different identities. The quickstart client application accomplishes that by looking up and invoking the secured EJB under different `AuthenticationContext`s. Each context is setup to use a different identities and credentials. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Add the Authorized Application and Management Users -include::../shared-doc/add-application-and-management-users.adoc[leveloffset=+1] +:leveloffset: +1 + +[[add_the_application_management_users]] += Add the Authorized Application and Management Users + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users +// :admin-user-groups: admin, superusers + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +ifdef::admin-user-groups[] +:admin-group-list: {admin-user-groups} +:admin-group-command: -g '{admin-user-groups}' +endif::admin-user-groups[] + +ifndef::admin-user-groups[] +:admin-group-list: +:admin-group-command: +endif::admin-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true +:addQuickstartAdmin: true + +This quickstart uses secured management interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|quickstartAdmin | ManagementRealm | adminPwd1! | {admin-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' {admin-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -89,7 +589,114 @@ which references the `ApplicationDomain` security domain mentioned above: This allows for the identity that was established in the connection authentication to be propagated to the components. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -124,11 +731,87 @@ Principal has admin permission: true As expected, the `quickstart` user is able to call the methods available for `guest`, but does not have the `admin` permission to call administrative methods on the remote EJB. The `quickstartAdmin` on the other hand has permissions to call both methods. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script reverts the changes made to the `ejb3` and `remoting` subsystems. You should see the following result when you run the script. @@ -140,9 +823,106 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions * Make sure you xref:add_the_application_management_users[add the authorized application and management users] as described above. @@ -170,10 +950,295 @@ Principal has admin permission: true * Make sure you xref:restore_the_server_configuration[restore the {productName} standalone server configuration] when you have completed testing this quickstart. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] //************************************************* @@ -184,4 +1249,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/ejb-security-programmatic-auth/pom.xml b/ejb-security-programmatic-auth/pom.xml index c659805430..c61a4898aa 100644 --- a/ejb-security-programmatic-auth/pom.xml +++ b/ejb-security-programmatic-auth/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-security-programmatic-auth - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ejb-security-programmatic-auth This project demonstrates how to authenticate remote clients using the programmatic API @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-throws-exception/README-source.adoc b/ejb-throws-exception/README-source.adoc new file mode 100644 index 0000000000..8843eae81c --- /dev/null +++ b/ejb-throws-exception/README-source.adoc @@ -0,0 +1,94 @@ +include::../shared-doc/attributes.adoc[] + += ejb-throws-exception: Handle Exceptions across JARs in an EAR +:author: Brad Maxwell +:level: Intermediate +:technologies: EJB, EAR +:deploymentDir: ear + +[abstract] +The `ejb-throws-exception` quickstart demonstrates how to throw and handle exceptions across JARs in an EAR. + +:standalone-server-type: default +:archiveType: ear + +== What is it? + +The `ejb-throws-exception` quickstart demonstrates how to handle exceptions across JARs in an EAR deployed to {productNameFull}. In this quickstart, an EJB in the EJB JAR throws a custom exception. The web application in the client JAR catches the exception and displays it in a nicely formatted message. The EAR contains: _JSF WAR_, an _EJB_ JAR and a client library JAR containg classes that both the WAR and EJB JAR use. + +This example consists of the following Maven projects, each with a shared parent. + +[cols="30%,70%",options="headers"] +|=== +|Project |Description + +| `ejb` +a| This project contains the EJB code and can be built independently to produce the JAR archive. + +* The EJB has a single method `sayHello` which will take in a String `name`. +* If the `name` is not null or an empty String, it returns `Hello `. +* If the `name` is null or an empty String, it throws a custom `GreeterException` exception back to the client. + +| `web` +a| This project contains the JSF pages and the CDI managed bean. + +* The CDI Managed Bean, `GreeterBean`, is bound to the JSF page, `index.xhtml`. +* It invokes the `GreeterEJB` and displays the response back from the EJB. +* The `GreeterBean` catches the custom `GreeterException` exception thrown by `GreeterEJB` and displays the exception message in the response text on the JSF page. + +| `ear` +| This project builds the EAR artifact and pulls in the ejb, web, and client artifacts. + +| `ejb-api` +a| This project builds the ejb-api library artifact which is used by the ejb, web, as well as remote client artifacts. + +* This directory contains the EJB interfaces, custom exceptions the EJB throws and any other transfer objects which the EJB may receive or send back to the client. +* The EJB interfaces, custom exceptions, and other transfer objects are split into a separate JAR, which is packaged in the ear/lib. This allows all sub deployments of the EAR to see the classes of the ejb-api JAR in the classpath. This is also useful for remote clients. +* The ejb-api JAR can be distributed to a remote client and give the remote clients the classes that are needed to interact with the EJB. +|=== + +The root `pom.xml` builds each of the subprojects in the above order and deploys the EAR archive to the server. + +The example follows the common "Hello World" pattern, using the following workflow. + +. A JSF page asks for a user name. +. On clicking *Say Hello*, the value of the *Name* input text is sent to a managed bean named `GreeterBean`. +. On setting the name, the `Greeter` invokes the `GreeterEJB`, which was injected to the managed bean. Notice that the field is annotated with `@EJB`. +. The EJB responds with *Hello * or throws an exception if the name is empty or null. +. The response or exception's message from invoking the `GreeterEJB` is stored in a field (response) of the managed bean. +. The managed bean is annotated as `@RequestScoped`, so the same managed bean instance is used only for the request/response. + + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL http://localhost:8080/{artifactId}-web. + +Enter a name in the input field *Name* and click the *Say Hello* button to see the response. + +The *Response* output text will display the response from the EJB. +If the *Name* input text box is not empty, then the *Response* output text will display *Hello * +If the *Name* input text box is empty, then the *Response* output text will display the message of the exception throw back from the EJB. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file diff --git a/ejb-throws-exception/README.adoc b/ejb-throws-exception/README.adoc index bd6a60b36c..e26643a964 100644 --- a/ejb-throws-exception/README.adoc +++ b/ejb-throws-exception/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-throws-exception +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-throws-exception: Handle Exceptions across JARs in an EAR :author: Brad Maxwell @@ -61,15 +258,291 @@ The example follows the common "Hello World" pattern, using the following workfl // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -82,14 +555,323 @@ If the *Name* input text box is not empty, then the *Response* output text will If the *Name* input text box is empty, then the *Response* output text will display the message of the exception throw back from the EJB. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] // Quickstart not compatible with OpenShift -include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file +:leveloffset: +1 + +[[openshift_incompatibility]] += {xpaasproduct-shortname} Incompatibility + +This quickstart is not compatible with {xpaasproduct-shortname} or {xpaasproductOpenShiftOnline-shortname} templates. + +:leveloffset!: diff --git a/ejb-throws-exception/ear/pom.xml b/ejb-throws-exception/ear/pom.xml index f77e82e180..6b3b32551f 100644 --- a/ejb-throws-exception/ear/pom.xml +++ b/ejb-throws-exception/ear/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-throws-exception - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-throws-exception-ear ear @@ -63,7 +63,7 @@ maven-ear-plugin - 7 + 8 diff --git a/ejb-throws-exception/ejb-api/pom.xml b/ejb-throws-exception/ejb-api/pom.xml index bc99175a2b..3e0b050b8d 100644 --- a/ejb-throws-exception/ejb-api/pom.xml +++ b/ejb-throws-exception/ejb-api/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-throws-exception - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-throws-exception-ejb-api jar diff --git a/ejb-throws-exception/ejb/pom.xml b/ejb-throws-exception/ejb/pom.xml index 0222158ddf..67fb9c19d2 100644 --- a/ejb-throws-exception/ejb/pom.xml +++ b/ejb-throws-exception/ejb/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-throws-exception - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-throws-exception-ejb ejb diff --git a/ejb-throws-exception/pom.xml b/ejb-throws-exception/pom.xml index 9ae2165c03..9f37c4e2c0 100644 --- a/ejb-throws-exception/pom.xml +++ b/ejb-throws-exception/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-throws-exception - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom Quickstart: ejb-throws-exception This project demonstrates how to throw an exception in an EJB and catch it in the web layer @@ -51,7 +51,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-throws-exception/web/pom.xml b/ejb-throws-exception/web/pom.xml index ddaf2e9714..d36ef5f97b 100644 --- a/ejb-throws-exception/web/pom.xml +++ b/ejb-throws-exception/web/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts ejb-throws-exception - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb-throws-exception-web war diff --git a/ejb-timer/README-source.adoc b/ejb-timer/README-source.adoc new file mode 100644 index 0000000000..58783bdbc7 --- /dev/null +++ b/ejb-timer/README-source.adoc @@ -0,0 +1,170 @@ +include::../shared-doc/attributes.adoc[] + += ejb-timer: Example of Jakarta Enterprise Bean Timer Service - @Schedule and @Timeout +:author: Ondrej Zizka +:level: Beginner +:technologies: EJB Timer +:openshift: true + +[abstract] +The `ejb-timer` quickstart demonstrates how to use the Jakarta Enterprise Bean timer service `@Schedule` and `@Timeout` annotations with {productName}. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `ejb-timer` quickstart demonstrates how to use the Jakarta Enterprise Bean timer service in {productNameFull}. This example creates a timer service that uses the `@Schedule` and `@Timeout` annotations. + +The following Jakarta Enterprise Bean Timer services are demonstrated: + +* `@Schedule`: Uses this annotation to mark a method to be executed according to the calendar schedule specified in the attributes of the annotation. This example schedules a message to be printed to the server console every 6 seconds. +* `@Timeout`: Uses this annotation to mark a method to execute when a programmatic timer goes off. This example sets the timer to go off every 3 seconds, at which point the method prints a message to the server console. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +This application only prints messages to stdout. +Each timeout callback logs the class name of the @Singleton bean that created the timer, an identifier of the timer, and the timestamp of the callback. +In our example application, the ScheduleExample bean creates a persistent timer, while the TimeoutExample creates a non-persistent (i.e. transient) timer. +To see it working, check the server log. You should see similar output: + +[source,options="nowrap"] +---- +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:04:24.896811Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:27.002334Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:30.004340Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:04:30.014526Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:33.001997Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:36.001444Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:04:36.004266Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:39.001746Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:42.002048Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:04:42.010535Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:45.000920Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:48.001840Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:04:48.010532Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:51.002591Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-331711014] at 2022-05-04T21:04:54.001734Z +---- + +Existing threads in the thread pool handle the invocations. They are rotated and the name of the thread that handles the invocation is printed within the parenthesis `(EJB Default - #)`. + +To demonstrate the behavioral difference between persistent and non-persistent timers, stop the server via "CRTL-C" and restart it. +Upon restart, you will see similar periodic timeout events, but while the persistent timer identifier remains the same, since persistent timers were restore upon restart; the non-persistent timer now has a different identifier, since the transient timers are lost when the server shutdown, and was recreated on startup. + +[source,options="nowrap"] +---- +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:18:36.013024Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:39.001383Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:42.002232Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:18:42.011380Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:45.001951Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:48.002369Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:18:48.008104Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:51.002364Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:54.002230Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:18:54.009333Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:18:57.001874Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:19:00.002287Z +INFO [stdout] (EJB default - 1) Timeout received for ScheduleExample[-2138907176] at 2022-05-04T21:19:00.010617Z +INFO [stdout] (EJB default - 1) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:19:03.002128Z +INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-1065503193] at 2022-05-04T21:19:06.002358Z +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +=== Using Timer Service within a cluster + +To demonstrate distributed TimerService behavior, a cluster of at least two application server instances must be started. +Begin by making a copy of the entire {productName} directory to be used as second cluster member. +Note that the example can be run on a single node as well, but without observation of the singleton properties. + +The default configuration of the HA profiles is pre-configured for a fully distributed persistent timers, as well as passivation support for non-persistent timers. + +Start the two {productName} servers with the same HA profile using the following commands. +Note that a socket binding port offset and a unique node name must be passed to the second server if the servers are binding to the same host. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. + +This example is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one. + +Next, use the following commands to deploy the already built demo application archive to each server. +Note that since the default socket binding port is `9990` and the second server has ports offset by `100`, the sum, `10090` must be passed as an argument to the deploy maven goal. + +[source,options="nowrap"] +---- +mvn wildfly:deploy +mvn wildfly:deploy -Dwildfly.port=10090 +---- + +Once deployed, you should begin to see log messages for our timer events. +However, while timeout events for the non-persistent timer created by the TimoutExample bean are triggered on both nodes, timeout events for the persistent timer created by the ScheduleExample bean are only triggered on one node. + +node1: + +[source,options="nowrap"] +---- +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:36.003154Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:39.003098Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:42.002884Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:45.003209Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:48.001284Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:51.001656Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:54.001396Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:57:57.001848Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:58:00.001673Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[390846799] at 2022-05-05T20:58:03.001794Z +---- + +node2: + +[source,options="nowrap"] +---- +INFO [stdout] (TimerScheduler - 1) Timeout received for ScheduleExample[-392733837] at 2022-05-05T20:57:36.003800Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:36.003799Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:39.003279Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:42.003483Z +INFO [stdout] (TimerScheduler - 1) Timeout received for ScheduleExample[-392733837] at 2022-05-05T20:57:42.003699Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:45.003339Z +INFO [stdout] (TimerScheduler - 1) Timeout received for ScheduleExample[-392733837] at 2022-05-05T20:57:48.001545Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:48.001544Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:51.001657Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:54.001710Z +INFO [stdout] (TimerScheduler - 1) Timeout received for ScheduleExample[-392733837] at 2022-05-05T20:57:54.001710Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:57:57.001717Z +INFO [stdout] (TimerScheduler - 1) Timeout received for ScheduleExample[-392733837] at 2022-05-05T20:58:00.001091Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:58:00.001547Z +INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[1048239741] at 2022-05-05T20:58:03.001514Z +---- + +If you then shutdown the node on which the ScheduleExample timeouts appear (in our case, node2), the other node (in our case, node1) will promptly begin receiving timeouts for that same persistent timer (as indicated by the same identifier). + +Restarting the node that we previously shutdown (in our case, node2), using the same command as listed above), you should observe that timeouts for the ScheduleExample timer will resume on the original node (in our case, node2), and now the other node (in our case, node1) no longer receives those timeout events. +In fact, if you collate the timestamps for the ScheduleExample bean across each server log carefully, you should find that no events were skipped, and no duplicate events were received. \ No newline at end of file diff --git a/ejb-timer/README.adoc b/ejb-timer/README.adoc index 14946c6e32..df40dc41f8 100644 --- a/ejb-timer/README.adoc +++ b/ejb-timer/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-timer +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-timer: Example of Jakarta Enterprise Bean Timer Service - @Schedule and @Timeout :author: Ondrej Zizka @@ -23,15 +220,291 @@ The following Jakarta Enterprise Bean Timer services are demonstrated: * `@Timeout`: Uses this annotation to mark a method to execute when a programmatic timer goes off. This example sets the timer to go off every 3 seconds, at which point the method prints a message to the server console. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -84,16 +557,629 @@ INFO [stdout] (EJB default - 2) Timeout received for TimeoutExample[-1065503193 ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: ejb-timer +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[] + + +[[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 + +// 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 + +:leveloffset!: === Using Timer Service within a cluster @@ -168,4 +1254,4 @@ INFO [stdout] (TimerScheduler - 1) Timeout received for TimeoutExample[10482397 If you then shutdown the node on which the ScheduleExample timeouts appear (in our case, node2), the other node (in our case, node1) will promptly begin receiving timeouts for that same persistent timer (as indicated by the same identifier). Restarting the node that we previously shutdown (in our case, node2), using the same command as listed above), you should observe that timeouts for the ScheduleExample timer will resume on the original node (in our case, node2), and now the other node (in our case, node1) no longer receives those timeout events. -In fact, if you collate the timestamps for the ScheduleExample bean across each server log carefully, you should find that no events were skipped, and no duplicate events were received. \ No newline at end of file +In fact, if you collate the timestamps for the ScheduleExample bean across each server log carefully, you should find that no events were skipped, and no duplicate events were received. diff --git a/ejb-timer/charts/helm.yaml b/ejb-timer/charts/helm.yaml index 48509a377b..3c5bd7f057 100644 --- a/ejb-timer/charts/helm.yaml +++ b/ejb-timer/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: ejb-timer deploy: replicas: 1 \ No newline at end of file diff --git a/ejb-timer/pom.xml b/ejb-timer/pom.xml index d241f4d508..83aa888910 100644 --- a/ejb-timer/pom.xml +++ b/ejb-timer/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-timer - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ejb-timer A sample Jakarta EE project demonstrating how to use EJB timer (@Schedule and @Timeout). @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-txn-remote-call/README-source.adoc b/ejb-txn-remote-call/README-source.adoc new file mode 100644 index 0000000000..289c17ac0b --- /dev/null +++ b/ejb-txn-remote-call/README-source.adoc @@ -0,0 +1,872 @@ +include::../shared-doc/attributes.adoc[] + += ejb-txn-remote-call: Demonstrates remote EJB calls and transaction propagation +:author: Ondra Chaloupka +:level: Intermediate +:technologies: EJB, JTA, Clustering +:openshift: true + +[abstract] +The `ejb-txn-remote-call` quickstart demonstrates remote transactional EJB calls over two application servers of {productName}. + +:standalone-server-type: ha +:archiveType: war +:requires-multiple-servers: +:jbds-not-supported: + +== What is it? + +The `ejb-txn-remote-call` quickstart demonstrates the remote transactional EJB calls over two {productNameFull}s. The remote side forms a HA cluster. + +== Description + +This quickstart demonstrates how EJB remote calls propagate JTA transaction across {productNameFull}s. Further, this quickstart demonstrates the transaction recovery, which is run for both servers when a failure occurs. + +This quickstart contains two Maven projects. +The first maven project represents the sender side, and is intended to be deployed on the first {productName} (`server1`). +The second project represents the receiver side. This project is intended to be deployed +to the other two {productName} (`server2` and `server3`). The two projects must not be deployed to the same server. + +.Maven projects in this quickstart +[cols="40%,60%",options="headers"] +|=== +|Project |Description + +|`client` +|The application deployed to the first {productName} server. +Users can interact with this application through some REST endpoints, which start remote EJB calls toward the `server` application +deployed on the other two {productName}s. +In more details, the transaction initiated at the client side enlists two participants: a database, and the EJB remote server. +The transaction manager then uses the two-phase commit to commit the transactions over the two servers. +Moreover, this quickstart shows how transactional failures how dealt with. + +|`server` +|The application deployed to the second and third {productName} servers. +This application receives the remote EJB calls from the `client` application and, +depending on the scenario, process the propagated transaction. +In more details, the transaction initiated at the server side enlists two participants: a database, and a mock XAResource. +|=== + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +== Running the Quickstart + +This quickstart demonstrates its functionalities on <<_running_in_a_bare_metal_environment, bare metal>>, using {productName} Maven plugin, and on OpenShift. + +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName}_1 and {jbossHomeName}_2 +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== The Goal + +The EJB remote call propagates transaction from `client` application +to `server` application. The remote call hits one of the two servers where the `server` application is deployed. + +== Running in a bare metal environment + +First of all, three {productName} servers needs to be configured. Then, the `client` application gets deployed to the first server (`server1`), +while the `server` application gets deployed to the other two {productName} servers (`server2`, and `server3`, which are configured as a cluster). + +[[_setup_productname_servers]] +=== Setup {productName} servers + +The easiest way to start multiple instances of {productName} on a local computer is to copy the {productName} installation directory +to three separate directories. + +The installation directories are named: + +* `__{jbossHomeName}_1__` for `server1` +* `__{jbossHomeName}_2__` for `server2` +* `__{jbossHomeName}_3__` for `server3` + +Given that the installation directory of the {productName} is identified with ${jbossHomeName}: +[source,sh,subs="+quotes,attributes+"] +---- +cp -r ${jbossHomeName} server1; \ +{jbossHomeName}_1="$PWD/server1" +---- +[source,sh,subs="+quotes,attributes+"] +---- +cp -r ${jbossHomeName} server2; \ +{jbossHomeName}_2="$PWD/server2" +---- +[source,sh,subs="+quotes,attributes+"] +---- +cp -r ${jbossHomeName} server3; \ +{jbossHomeName}_3="$PWD/server3" +---- + +=== Creating a user for `server2` and `server3` + +To successfully process EJB remote calls from `server1` to either `server2` +or to `server3` a user to authenticate the EJB remote calls must be created on the receiving servers. + +Run the following procedure in the directories `__{jbossHomeName}_2__` and `__{jbossHomeName}_3__` to create the user for `server2` and `server3`. + +[#add_application_user] +// Add the Authorized Application User +include::../shared-doc/add-application-user.adoc[leveloffset=+3] + +[NOTE] +==== +For the `add-user.sh` (or `.bat`) command you, can add the parameter `-ds`. +When you include this parameter, after the user is added, the system outputs a secret value that you can use to set up the remote output connection on `server1`. + +The output of command when `-ds` parameter is used: + +[code,sh] +---- +To represent the user add the following to the server-identities definition +---- +==== + +=== Configure datasources + +As this quickstart performs transactional work against a database, it is needed to create a new database. +For the purpose of this quickstart, a simple PostgreSQL container will be used: + +[source,sh] +---- +podman run -p 5432:5432 --rm -ePOSTGRES_DB=test -ePOSTGRES_USER=test -ePOSTGRES_PASSWORD=test postgres:9.4 -c max-prepared-transactions=110 -c log-statement=all +---- + +The {productName} servers need to be configured to be able to connect to the database. +First of all, a JDBC driver needs to be installed as https://docs.wildfly.org/30/Developer_Guide.html#Class_Loading_in_WildFly[jboss module]. + +The following command (along packaging the `client` and the `server` applications) downloads the PostgreSQL driver automatically through Maven: +[source,sh,subs="+quotes,attributes+"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call; +mvn clean package +---- +Then, the PostgreSQL driver needs to be loaded as jboss module in all {productName} servers: + +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_1; \ +./bin/jboss-cli.sh "embed-server,\ + module add --name=org.postgresql.jdbc \ + --resources=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/target/postgresql/postgresql.jar" +---- +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_2; \ +./bin/jboss-cli.sh "embed-server,\ + module add --name=org.postgresql.jdbc \ + --resources=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/target/postgresql/postgresql.jar" +---- +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_3; \ +./bin/jboss-cli.sh "embed-server,\ + module add --name=org.postgresql.jdbc \ + --resources=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/target/postgresql/postgresql.jar" +---- + +Moreover, the PostgreSQL driver needs to be installed on all {productName} servers. +For `server1`, the configuration file `standalone.xml` will be used. +For `server2` and `server3` the configuration file `standalone-ha.xml` will be used. + +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_1; \ +./bin/jboss-cli.sh "embed-server --server-config=standalone.xml,\ + /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql.jdbc,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)" +---- +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_2; \ +./bin/jboss-cli.sh "embed-server --server-config=standalone-ha.xml,\ + /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql.jdbc,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)" +---- +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_3; \ +./bin/jboss-cli.sh "embed-server --server-config=standalone-ha.xml,\ + /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql.jdbc,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)" +---- + +Finally, it is time to run the scripts for adding the PostgreSQL datasource to the {productName} servers: + +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_1; \ +./bin/jboss-cli.sh -DpostgresqlUsername="test" -DpostgresqlPassword="test" \ + --file=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/scripts/postgresql-datasource.cli \ + --properties=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/scripts/cli.local.properties +---- +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_2; \ +./bin/jboss-cli.sh -DpostgresqlUsername="test" -DpostgresqlPassword="test" \ + --file=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server/scripts/postgresql-datasource.cli \ + --properties=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server/scripts/cli.local.properties +---- +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_3; \ +./bin/jboss-cli.sh -DpostgresqlUsername="test" -DpostgresqlPassword="test" \ + --file=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server/scripts/postgresql-datasource.cli \ + --properties=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server/scripts/cli.local.properties +---- + +=== Configuring EJB remoting on `server1` + +EJB remote calls from `server1` to either `server2` or `server3` need to be authenticated. To achieve +this configuration, the script `${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/scripts/remoting-configuration.cli` +will be executed on `server1`. + +[NOTE] +==== +`remoting-configuration.cli` is configured with properties in `cli.local.properties` and runs against `standalone.xml` +==== + +[[remote_configuration_cli]] +[source,sh,subs="+quotes,attributes+"] +---- +cd ${jbossHomeName}_1; \ +./bin/jboss-cli.sh -DremoteServerUsername="quickstartUser" -DremoteServerPassword="quickstartPwd1!" \ + --file=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/scripts/remoting-configuration.cli \ + --properties=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/scripts/cli.local.properties +---- + +NOTE: For Windows, use the `bin\jboss-cli.bat` script. + +Running `remoting-configuration.cli` results in the creation of: + +* A `remote outbound socket` that points to the port on `server2`/`server3` where EJB remoting endpoints can be reached +* A https://docs.wildfly.org/22/wildscribe/subsystem/remoting/remote-outbound-connection/index.html[`remote outbound connection`] that can be referenced in the war deployment with `jboss-ejb-client.xml` descriptor +(see `${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/src/main/webapp/WEB-INF/jboss-ejb-client.xml`). +* An authentication context `auth_context` that is used by the new created remoting connection `remote-ejb-connection`; the authentication context uses the same username and password created for `server2` and `server3` + +[#_start_productname_servers] +=== Start {productName} servers + +At this point, the configuration of the {productName} servers is completed. +`server1` must be started with the `standalone.xml` configuration, +while `server2` and `server3` must be started with the `standalone-ha.xml` configuration to create a cluster. +As all {productName} servers will be run in the same bare metal environment, +a port offset will be applied to `server2` and `server3`. Moreover, +each server has to define a unique transaction node identifier and jboss node name. + +Start each server in a separate terminal. + +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${jbossHomeName}_1; \ +./bin/standalone.sh -c standalone.xml -Djboss.tx.node.id=server1 -Djboss.node.name=server1 -Dwildfly.config.url=${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client/configuration/custom-config.xml +---- +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${jbossHomeName}_2; \ +./bin/standalone.sh -c standalone-ha.xml -Djboss.tx.node.id=server2 -Djboss.node.name=server2 -Djboss.socket.binding.port-offset=100 +---- +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${jbossHomeName}_3; \ +./bin/standalone.sh -c standalone-ha.xml -Djboss.tx.node.id=server3 -Djboss.node.name=server3 -Djboss.socket.binding.port-offset=200 +---- + +NOTE: To enable the recovery of remote transaction failures, the configuration file `custom-config.xml` +should be loaded into `server1`; this operation will authenticate `server1` against `server2`/`server3`. + +NOTE: For Windows, use the `bin\standalone.bat` script. + +=== Deploying the Quickstart applications + +. With all {productName} servers <<_setup_productname_servers, configured>> and <<_start_productname_servers, running>>, +the `client` and `server` application can be deployed + +. The whole project can be built using the following commands: ++ +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/ +mvn clean package +---- ++ +. Then, the `client` application can be deployed using the following commands: ++ +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client +mvn wildfly:deploy +---- ++ +. Lastly, the `server` application can be deployed using the following commands: ++ +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server +mvn wildfly:deploy -Dwildfly.port=10090 +mvn wildfly:deploy -Dwildfly.port=10190 +---- + +The commands just run employed the WildFly Maven plugin to connect to the running instances of {productName} +and deploy the `war` archives to the servers. + +==== Checkpoints + +. If errors occur, verify that the {productName} servers are running and that they are configured properly +. Verify that all deployments are published into all three servers +.. On `server1` check the log to confirm that the `client/target/client.war` archive is deployed ++ +[source,options="nowrap"] +---- +... +INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 76) WFLYUT0021: Registered web context: '/client' for server 'default-server' +INFO [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "client.war" (runtime-name : "client.war") +---- ++ +.. On `server2` and `server3`, check the log to confirm that the `server/target/server.war` archive is deployed. ++ +[source,options="nowrap"] +---- +... +INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 86) WFLYUT0021: Registered web context: '/server' for server 'default-server' +INFO [org.jboss.as.server] (management-handler-thread - 1) WFLYSRV0010: Deployed "server.war" (runtime-name : "server.war") +---- + +. Verify that `server2` and `server3` formed a HA cluster. +.. Check the server log of either `server2` and `server3`, or both. ++ +[source,options="nowrap"] +---- +[org.infinispan.CLUSTER] () ISPN000094: Received new cluster view for channel ejb: [server2|1] (2) [server2, server3] +[org.infinispan.CLUSTER] () ISPN100000: Node server3 joined the cluster +... +INFO [org.infinispan.CLUSTER] () [Context=server.war/infinispan] ISPN100010: Finished rebalance with members [server2, server3], topology id 5 +---- + +[#_examining_the_quickstart] +=== Examining the Quickstart + +Once the {productName} servers are configured and started, and the quickstart artifacts are deployed, it is possible to +invoke the endpoints of `server1`, which generate EJB remote invocations against the HA cluster formed by `server2` and `server3`. + +The following table defines the available endpoints, and their expected behaviour. + +[NOTE] +==== +The endpoints return data in JSON format. You can use `curl` for the invocation +and `jq` for formatting the results. For example: + +`curl -s http://localhost:8080/client/remote-outbound-stateless | jq .` +==== + +[NOTE] +==== +On Windows, `curl` and `jq` might not be available. +If so, enter the endpoints directly to a browser of your choice. +The behaviour and the obtained JSON will be the same as for the `curl` command. +==== + +The HTTP invocations return the hostnames of the contacted servers. + +[[rest-endpoints]] +[options="headers"] +.HTTP endpoints of the test invocation +|=== +|URL |Behaviour |Expectation + +|__http://localhost:8080/client/remote-outbound-stateless__ +|Two invocations under the transaction context started on `server1` (`client` application). +The EJB remote call is configured from the `remote-outbound-connection`. +Both calls are directed to the same remote server instance (`server` application) +due to transaction affinity. +|The two returned hostnames must be the same. + +|__http://localhost:8080/client/remote-outbound-notx-stateless__ +|Several remote invocations to stateless EJB without a transaction context. +The EJB remote call is configured from the `remote-outbound-connection`. +The EJB client is expected to load balance the calls on various servers. +|The list of the returned hostnames should contain occurrences of both + `server2` and `server3`. + +|__http://localhost:8080/client/direct-stateless__ +|Two invocations under the transaction context started on `server1` (`client` application). The stateless bean is invoked on the remote side. +The EJB remote call is configured from data in the `client` application source code. +The remote invocation is run via the EJB remoting protocol. +|The returned hostnames must be the same. + +|__http://localhost:8080/client/direct-stateless-http__ +|Two invocations under the transaction context started on `server1` (`client` application). The stateless bean is invoked on the remote side. +The EJB remote call is configured from data in the `client` application source code. +The remote invocation is run, unlike the other calls of this quickstarts, via https://docs.wildfly.org/22/Developer_Guide.html#EJB_over_HTTP[EJB over HTTP]. +|The returned hostnames must be the same. + +|__http://localhost:8080/client/remote-outbound-notx-stateful__ +|Two invocations under the transaction context started on `server1` (`client` application). +The EJB remote call is configured from the `remote-outbound-connection`. +Both calls are directed to the same stateful bean on the remote server because +the stateful bean invocations are sticky ensuring affinity to the same server instance. +|The returned hostnames must be the same. + +|__http://localhost:8080/client/remote-outbound-fail-stateless__ +|An invocation under the transaction context started on `server1` (`client` application). +The call goes to one of the remote servers, where errors occur during transaction processing. +The failure is simulated at time of two-phase commit. +This HTTP call finishes with success. Only the server log shows some warnings. +This is an expected behaviour. An intermittent failure during commit phase +of two-phase protocol makes the transaction manager obliged to finish the work +eventually. The finalization of work is done in the background +(by Narayana recovery manager, see details <<_details_on_recovery, below>>), and the HTTP call may inform the client back with success. +|When the recovery manager finishes the work all the transaction resources are committed. + +|=== + +[[_details_on_recovery]] +==== Observing the recovery processing after __client/remote-outbound-fail-stateless__ call + +The EJB call to the endpoint `client/remote-outbound-fail-stateless` simulates the presence +of an intermittent network error happening at the commit phase of the two-phase commit protocol (2PC). + +The http://jbossts.blogspot.com/2018/01/narayana-periodic-recovery-of-xa.html[transaction recovery manager] +periodically tries to recover the unfinished work and only when this attempt is successful, +the transaction is completed (which makes the update in the database visible). It is possible to confirm the completion of +the transaction by invoking the REST endpoint `server/commits` at both servers `server2` and `server3`. + + +[source] +---- +curl -s http://localhost:8180/server/commits +---- + +[source] +---- +curl -s http://localhost:8280/server/commits +---- + +The response of `server/commits` is a tuple composed by the host's info and the number of commits. +For example the output could be `["host: mydev.narayana.io/192.168.0.1, jboss node name: server2","3"]` +and it says that the hostname is `mydev.narayana.io`, the jboss node name is `server2`, +and the number of commits is `3`. + +The Transaction recovery manager runs periodically (by default, it runs every 2 minutes) on all servers. +Nevertheless, as the transaction is initiated on `server1`, the recovery manager on this server will be +responsible to initiate the recovery process. + +[NOTE] +==== +The recovery process can be started manually. Using `telnet` and connecting to `localhost:4712` +(i.e. the port where https://docs.wildfly.org/22/wildscribe/subsystem/transactions/index.html#attr-recovery-listener[the recovery process is listening to]), +it is possible to send the `SCAN` command to force a recovery cycle + +[source] +---- +telnet localhost 4712 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +SCAN +DONE +Connection closed by foreign host. +---- +==== + +[[_steps_to_observe_recovery_processing]] +===== Steps to observe that the recovery processing was done + +. Before invoking the __remote-outbound-fail-stateless__ endpoint, double check + the number of `commits` on `server2` and `server3` by invoking the `server/commits` + endpoints. ++ +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +curl http://localhost:8180/server/commits; echo +# output example: +# ["host: mydev.narayana.io/192.168.0.1, jboss node name: server2","1"] +curl http://localhost:8280/server/commits; echo +# output example: +# ["host: mydev.narayana.io/192.168.0.1, jboss node name: server3","2"] +---- ++ +. Invoke the REST endpoint `client/remote-outbound-fail-stateless` ++ +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +curl http://localhost:8080/client/remote-outbound-fail-stateless | jq . +---- ++ +The JSON output from the previous command reports the name of server the request was sent to. ++ + +. At the server reported by the previous command, verify the number of `commits` by invoking the `server/commits` endpoint. + +. Check the log of `server1` for the following warning message ++ +[source,options="nowrap"] +---- +ARJUNA016036: commit on < formatId=131077, gtrid_length=35, bqual_length=36, tx_uid=..., node_name=server1, branch_uid=..., subordinatenodename=null, eis_name=unknown eis name > (Subordinate XAResource at remote+http://localhost:8180) failed with exception $XAException.XA_RETRY: javax.transaction.xa.XAException: WFTXN0029: The peer threw an XA exception +---- ++ +This message means that the transaction manager was not able to commit the transaction as +an error occurred while committing the transaction on the remote server. +The `XAException.XA_RETRY` exception, meaning an intermittent failure, was reported in the logs. +. The logs on `server2` or `server3` contain a warning about the `XAResource` failure as well. ++ +[source,options="nowrap"] +---- +ARJUNA016036: commit on < formatId=131077, gtrid_length=35, bqual_length=43, tx_uid=..., node_name=server1, branch_uid=..., subordinatenodename=server2, eis_name=unknown eis name > (org.jboss.as.quickstarts.ejb.mock.MockXAResource@731ae22) failed with exception $XAException.XAER_RMFAIL: javax.transaction.xa.XAException +---- ++ +. Wait for the recovery process at `server1` to recover the unfinished transaction (or force a recovery cycle manually) + +. The number of commits on the targeted server should be incremented by one. + +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +Repeat the last step for `server2` and `server3`: + +[source,sh,options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +mvn wildfly:undeploy -Dwildfly.port=10090; +mvn wildfly:undeploy -Dwildfly.port=10190 +---- + +=== Server Log: Expected Warnings and Errors + +This quickstart is not production grade. The server logs include the following +warnings during the startup. It is safe to ignore these warnings. + +[source,options="nowrap"] +---- +WFLYDM0111: Keystore standalone/configuration/application.keystore not found, it will be auto generated on first use with a self signed certificate for host localhost + +WFLYELY01084: KeyStore .../standalone/configuration/application.keystore not found, it will be auto generated on first use with a self-signed certificate for host localhost + +WFLYSRV0018: Deployment "deployment.server.war" is using a private module ("org.jboss.jts") which may be changed or removed in future versions without notice. +---- + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] + +[[build_and_run_the_quickstart_with_provisioned_server]] +== Building and running the quickstart application with provisioned {productName} server + +Instead of using a standard {productName} server distribution, the three {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"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client; +mvn clean package -Pprovisioned-server \ + -DremoteServerUsername="quickstartUser" -DremoteServerPassword="quickstartPwd1!" \ + -DpostgresqlUsername="test" -DpostgresqlPassword="test" +---- +[source,sh,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +mvn clean package -Pprovisioned-server \ + -Dwildfly.provisioning.dir=server2 -Djboss-as.home=target/server2 \ + -DpostgresqlUsername="test" -DpostgresqlPassword="test"; +mvn package -Pprovisioned-server \ + -Dwildfly.provisioning.dir=server3 -Djboss-as.home=target/server3 \ + -DpostgresqlUsername="test" -DpostgresqlPassword="test" +---- + +The provisioned {productName} servers, with the quickstart deployed, can then be found in the `target/server` 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. + +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. + +The quickstart user should be added before running the provisioned server: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +./target/server2/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!'; +./target/server3/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' +---- +[NOTE] +==== +For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. +==== + +=== Run the Integration Tests with a provisioned server + +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. + +. As this quickstart performs transactional work against a database, it is needed to create a new database. For the purpose of this quickstart, a simple PostgreSQL container will be used: ++ +[source,sh] +---- +podman run -p 5432:5432 --rm -ePOSTGRES_DB=test -ePOSTGRES_USER=test -ePOSTGRES_PASSWORD=test postgres:9.4 -c max-prepared-transactions=110 -c log-statement=all +---- + +. Make sure the servers are provisioned by running the commands reported in <> + +. Add the quickstart user to the provisioned `server2` and `server3` 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"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client; +mvn wildfly:start -Djboss-as.home=target/server \ + -Dwildfly.javaOpts="-Djboss.tx.node.id=server1 -Djboss.node.name=server1" +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +mvn wildfly:start -Djboss-as.home=target/server2 \ + -Dwildfly.port=10090 \ + -Dwildfly.serverConfig=standalone-ha.xml \ + -Dwildfly.javaOpts="-Djboss.socket.binding.port-offset=100 -Djboss.tx.node.id=server2 -Djboss.node.name=server2" +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +mvn wildfly:start -Djboss-as.home=target/server3 \ + -Dwildfly.port=10190 \ + -Dwildfly.serverConfig=standalone-ha.xml \ + -Dwildfly.javaOpts="-Djboss.socket.binding.port-offset=200 -Djboss.tx.node.id=server3 -Djboss.node.name=server3" +---- + +. 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"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/client; +mvn verify -Pintegration-testing +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +mvn verify -Pintegration-testing -Dserver.host="http://localhost:8180/server" +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call/server; +mvn verify -Pintegration-testing -Dserver.host="http://localhost:8280/server" +---- + +. 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 +---- ++ +[source,subs="attributes+",options="nowrap"] +---- +mvn wildfly:shutdown -Dwildfly.port=10190 +---- + +endif::[] + +== Running on OpenShift + +The ephemeral nature of OpenShift does not work smoothly with {productName}'s ability to handle transactions. +In fact, {productName}'s transaction management saves logs to keep record of transactions' history in case of +extreme scenarios, like crashes or network issues. Moreover, EJB remoting requires a stable remote endpoint +to guarantee: + +* The transaction affinity of `stateful beans` and +* The recovery of transactions. + +To fulfil the aforementioned requirements, applications that requires ACID transactions _**must be**_ deployed +to {productName} using the {productName}'s Operator, which can employ OpenShift's _StatefulSet_. Failing to do so +might result in no-ACID transactions. + +=== Prerequisites + +include::../shared-doc/cd-create-project.adoc[leveloffset=+3] + +[#_install_operator] +==== Install {productName}'s Operator + +To install {productName}'s Operator, follow the https://github.com/wildfly/wildfly-operator[official documentation] +(which instructions are also reported here for convenience) + +ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[] +[source,sh,options="nowrap",subs="+quotes,attributes+"] +---- +cd /tmp +git clone https://github.com/wildfly/wildfly-operator.git + +cd wildfly-operator + +oc adm policy add-cluster-role-to-user cluster-admin developer +make install +make deploy +---- +endif::[] + +To verify that the {productName} Operator is running, execute the following command: + +ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[] +[source,sh,options="nowrap",subs="+quotes,attributes+"] +---- +oc get po -n $(oc project -q) + +NAME READY STATUS RESTARTS AGE +wildfly-operator-5d4b7cc868-zfxcv 1/1 Running 1 22h +---- +endif::[] + +[#_start_postgresql_database] +==== Start a PostgreSQL database + +This quickstart requires a PostgreSQL database to run correctly. In the scope of this quickstart, +a PostgreSQL database will be deployed on the OpenShift instance using the Helm chart provided by +https://github.com/bitnami/charts/tree/main/bitnami/postgresql[bitnami]: + +[source,sh,options="nowrap",subs="+quotes,attributes+"] +---- +helm repo add bitnami https://charts.bitnami.com/bitnami +helm install postgresql bitnami/postgresql -f charts/postgresql.yaml --wait --timeout="5m" +---- + +[#_build_the_application] +=== Build the applications + +To build the `client` and the `server` applications, this quickstart employs +{productName}'s https://github.com/wildfly/wildfly-charts/tree/main[Helm charts]. +For more information about {productName}'s Helm chart, please refer to the official +https://github.com/wildfly/wildfly-charts/blob/main/charts/wildfly/README.md[documentation]. + +ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[] +[source,sh,options="nowrap",subs="+quotes,attributes+"] +---- +helm repo add wildfly https://docs.wildfly.org/wildfly-charts/ + +helm install client -f charts/client.yaml wildfly/wildfly +helm install server -f charts/server.yaml wildfly/wildfly +---- +endif::[] + +Wait for the builds to finish. Their status can be verified by executing the `oc get pod` command. + +[#_deploy_the_quickstart] +=== Deploy the Quickstart + +To deploy the `client` and the `server` applications, this quickstart uses the `WildFlyServer` custom resource, +thanks to which the {productName} Operator is able to create a {productName} pod and +deploy an application. + +NOTE: Make sure that `view` permissions are granted to the default system account. +The `KUBE_PING` protocol, which is used for forming the HA {productName} cluster +on OpenShift, requires `view` permissions to read the labels of the pods: +`oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)` + +[source,sh,options="nowrap"] +---- +cd ${PATH_TO_QUICKSTART_DIR}/ejb-txn-remote-call; +oc create -f client/client-cr.yaml; +oc create -f server/server-cr.yaml +---- + +If the above commands are successful, the `oc get pod` command shows +all the pods required for the quickstart, i.e. the `client` pod and two +`server` pods (and the PostgreSQL database). + +[source,sh,options="nowrap"] +---- +NAME READY STATUS RESTARTS AGE +client-0 1/1 Running 0 29m +postgresql-f9f475f87-l944r 1/1 Running 1 22h +server-0 1/1 Running 0 11m +server-1 1/1 Running 0 11m +---- + +[#_verify_the_quickstarts] +==== Verify the Quickstarts + +The {productName} Operator creates routes that make the `client` and the `server` applications accessible +outside the OpenShift environment. The `oc get route` command shows the addresses of the HTTP endpoints. +An example of the output is: + +[source,sh,options="nowrap"] +---- +oc get route + +NAME HOST/PORT PATH SERVICES PORT +client-route client-route-ejb-txn-remote-call-client-artifacts.apps-crc.testing client-loadbalancer http +server-route server-route-ejb-txn-remote-call-client-artifacts.apps-crc.testing server-loadbalancer http +---- + +With the following commands, it is possible to verify the some functionalities of this quickstart: + +[source,sh,options="nowrap"] +---- +curl -s $(oc get route client-route --template='{{ .spec.host }}')/client/remote-outbound-stateless | jq . +curl -s $(oc get route client-route --template='{{ .spec.host }}')/client/remote-outbound-stateless | jq . +curl -s $(oc get route client-route --template='{{ .spec.host }}')/client/remote-outbound-notx-stateless | jq . +curl -s $(oc get route client-route --template='{{ .spec.host }}')/client/direct-stateless | jq . +curl -s $(oc get route client-route --template='{{ .spec.host }}')/client/remote-outbound-notx-stateful | jq . +---- + +For other HTTP endpoints, refer to <>. + +If you like to <<_steps_to_observe_recovery_processing,observe the recovery process>> +then you can follow these shell commands. + +[source,sh,options="nowrap"] +---- +# To check failure resolution +# verify the number of commits that come from the first and second node of the `server` deployments. +# Two calls are needed, as each reports the commit count of different node. +# Remember the reported number of commits to be compared with the results after crash later. +curl -s $(oc get route server-route --template='{{ .spec.host }}')/server/commits +curl -s $(oc get route server-route --template='{{ .spec.host }}')/server/commits + +# Run the remote call that causes the JVM of the server to crash. +curl -s $(oc get route client-route --template='{{ .spec.host }}')/client/remote-outbound-fail-stateless +# The platforms restarts the server back to life. +# The following commands then make us waiting while printing the number of commits happened at the servers. +while true; do + curl -s $(oc get route server-route --template='{{ .spec.host }}')/server/commits + curl -s $(oc get route server-route --template='{{ .spec.host }}')/server/commits + I=$((I+1)) + echo " <<< Round: $I >>>" + sleep 2 +done +---- + +// TODO: Read the following document to see what can be integrated +//include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +==== Running on OpenShift: Quickstart application removal + +To delete the `client` and the `server` applications, the `WildFlyServer` definitions needs to be deleted. +This is achievable running: + +[source,sh,options="nowrap"] +---- +oc delete WildFlyServer client; +oc delete WildFlyServer server +---- + +The `client` and the `server` applications will be stopped, and the two pods will be removed. + +To remove the Helm charts installed previously: + +[source,sh,options="nowrap"] +---- +helm uninstall client; +helm uninstall server; +helm uninstall postgresql +---- + +Finally, to undeploy and uninstall the {productName}'s operator: + +[source,sh,options="nowrap"] +---- +cd /tmp/wildfly-operator; +make undeploy; +make uninstall +---- + +The above commands completely clean the OpenShift namespace \ No newline at end of file diff --git a/ejb-txn-remote-call/README.adoc b/ejb-txn-remote-call/README.adoc index 697e21288b..f332a6d581 100644 --- a/ejb-txn-remote-call/README.adoc +++ b/ejb-txn-remote-call/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ejb-txn-remote-call +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ejb-txn-remote-call: Demonstrates remote EJB calls and transaction propagation :author: Ondra Chaloupka @@ -49,16 +246,71 @@ In more details, the transaction initiated at the server side enlists two partic |=== // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: == Running the Quickstart This quickstart demonstrates its functionalities on <<_running_in_a_bare_metal_environment, bare metal>>, using {productName} Maven plugin, and on OpenShift. // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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}_1 and {jbossHomeName}_2 -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == The Goal @@ -108,7 +360,47 @@ Run the following procedure in the directories `__{jbossHomeName}_2__` and `__{j [#add_application_user] // Add the Authorized Application User -include::../shared-doc/add-application-user.adoc[leveloffset=+3] +:leveloffset: +3 + +[[add_the_application_user]] += Add the Authorized Application User + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true + +This quickstart uses secured application interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: [NOTE] ==== @@ -517,7 +809,26 @@ ARJUNA016036: commit on < formatId=131077, gtrid_length=35, bqual_length=43, tx_ . The number of commits on the targeted server should be incremented by one. -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: Repeat the last step for `server2` and `server3`: @@ -683,7 +994,44 @@ might result in no-ACID transactions. === Prerequisites -include::../shared-doc/cd-create-project.adoc[leveloffset=+3] +:leveloffset: +3 + + +[[prepare_openshift_for_quickstart_deployment]] += Prepare OpenShift for Quickstart Deployment + +. Log in to your OpenShift instance using the `oc login` command. +. Create a new project for the quickstart in OpenShift. You can create a project in OpenShift using the following command. ++ +[options="nowrap",subs="attributes"] +---- +$ oc new-project {artifactId}-project +---- +//// +. Create a keystore. ++ +{xpaasproduct-shortname} requires a keystore to be imported to properly install and configure the image on your OpenShift instance. ++ +[WARNING] +==== +The following commands generate a self-signed certificate, but for production environments Red Hat recommends that you use your own SSL certificate purchased from a verified Certificate Authority (CA) for SSL-encrypted connections (HTTPS). +==== ++ +You can use the Java `keytool` command to generate a keystore using the following command. ++ +[options="nowrap",subs="attributes"] +---- +$ keytool -genkey -keyalg RSA -alias {artifactId}-project-selfsigned -keystore keystore.jks -validity 360 -keysize 2048 +---- +. Create a secret from the previously created keystore using the following command. ++ +[options="nowrap",subs="attributes"] +---- +$ oc secrets new eap7-app-secret keystore.jks +---- +//// + +:leveloffset!: [#_install_operator] ==== Install {productName}'s Operator @@ -870,4 +1218,4 @@ make undeploy; make uninstall ---- -The above commands completely clean the OpenShift namespace \ No newline at end of file +The above commands completely clean the OpenShift namespace diff --git a/ejb-txn-remote-call/charts/client.yaml b/ejb-txn-remote-call/charts/client.yaml index 7d2a2ddeae..1c807ebf3a 100644 --- a/ejb-txn-remote-call/charts/client.yaml +++ b/ejb-txn-remote-call/charts/client.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: ejb-txn-remote-call/client env: - name: MAVEN_ARGS_APPEND diff --git a/ejb-txn-remote-call/charts/server.yaml b/ejb-txn-remote-call/charts/server.yaml index 3873e45900..ff3a696f78 100644 --- a/ejb-txn-remote-call/charts/server.yaml +++ b/ejb-txn-remote-call/charts/server.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: ejb-txn-remote-call/server deploy: enabled: false diff --git a/ejb-txn-remote-call/client/pom.xml b/ejb-txn-remote-call/client/pom.xml index 7a09a7bf22..040bf11efa 100644 --- a/ejb-txn-remote-call/client/pom.xml +++ b/ejb-txn-remote-call/client/pom.xml @@ -25,20 +25,20 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-txn-remote-call-client - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ejb-txn-remote-call-client The project is the application to be deployed on the client server to call the second server - 30.0.0.Final + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/ejb-txn-remote-call/pom.xml b/ejb-txn-remote-call/pom.xml index 99a320be84..c3c219a9ce 100644 --- a/ejb-txn-remote-call/pom.xml +++ b/ejb-txn-remote-call/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-txn-remote-call - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom Quickstart: ejb-txn-remote-call The project demonstrates how to make EJB remote calls from server to server with transaction propagation. diff --git a/ejb-txn-remote-call/server/pom.xml b/ejb-txn-remote-call/server/pom.xml index a753a7503e..59589aca30 100644 --- a/ejb-txn-remote-call/server/pom.xml +++ b/ejb-txn-remote-call/server/pom.xml @@ -25,20 +25,20 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ejb-txn-remote-call-server - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: ejb-txn-remote-call-server The project is the application to be deployed on the second server to receive the call - 30.0.0.Final + 31.0.0.Final ${version.server} 7.0.0.Final diff --git a/ha-singleton-deployment/README-source.adoc b/ha-singleton-deployment/README-source.adoc new file mode 100644 index 0000000000..2457d0a022 --- /dev/null +++ b/ha-singleton-deployment/README-source.adoc @@ -0,0 +1,272 @@ +include::../shared-doc/attributes.adoc[] + += ha-singleton-deployment: Deploying Cluster-wide Singleton Services Using Singleton Deployments +:author: Radoslav Husar +:level: Advanced +:technologies: EJB, Singleton Deployments, Clustering + +[abstract] +The `ha-singleton-deployment` quickstart demonstrates the recommended way to deploy any service packaged in an application archive as a cluster-wide singleton. + +:standalone-server-type: ha +:archiveType: jar +:requires-multiple-servers: +:jbds-not-supported: + +== What is it? + +The `ha-singleton-deployment` quickstart demonstrates the deployment of a service packaged in an application as a cluster-wide singleton using singleton deployments. +In this example, the service is a timer that is initialized by a `@Startup @Singleton` bean. +The example is built and packaged as a single EJB archive. + +For more information about singleton deployments, see _HA Singleton Deployments_ in the {LinkDevelopmentGuide}[__{DevelopmentBookName}__] for {DocInfoProductName} located on the Red Hat Customer Portal. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName}_1 and {jbossHomeName}_2 +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Setting Up the Test Environment + +To demonstrate the singleton behavior, at least two application server instances must be started. +Begin by making a copy of the entire {productName} directory to be used as second cluster member. +Note that the example can be run on a single node as well, but without observation of the singleton properties. + +Start the two {productName} servers with the same HA profile using the following commands. +Note that a socket binding port offset and a unique node name must be passed to the second server if the servers are binding to the same host. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. + +This example is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one. + +== Running the Quickstart + +. Start the {productName} servers as described in the above section. +. Navigate to the root directory of this quickstart in the terminal. +. Use the following command to clean up previously built artifacts, and build and deploy the EJB archive: ++ +[source,options="nowrap"] +---- +$ mvn clean install wildfly:deploy +---- + +. Ensure the `target/{artifactId}.jar` archive is deployed to `node1` (the one without port offset) by observing the log. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar") +... +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node1 elected as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service +INFO [org.jboss.as.server] (management-handler-thread - 4) WFLYSRV0010: Deployed "ha-singleton-deployment.jar" (runtime-name : "ha-singleton-deployment.jar") +... +WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 68) SingletonTimer is initializing. +INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World! +---- ++ +The following warnings might appear in the server output after the applications are deployed. These warnings can be safely ignored in a development environment. ++ +[source,options="nowrap"] +---- +WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) +WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) +---- + +. Use the following command to deploy the already built archive to the second server. Note that since the default socket binding port is `9990` and the second server has ports offsetted by `100`, the sum, `10090` must be passed as an argument to the deploy maven goal. ++ +[source,options="nowrap"] +---- +mvn wildfly:deploy -Dwildfly.port=10090 +---- + +. Ensure the `service/target/{artifactId}.jar` archive is deployed to `node2` by observing the log. Note that even though the logs indicate "Deployed", the deployment does not actually deploy completely and the timer is not operating on this node. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.server.deployment] (MSC service thread 1-6) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar") +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000078: Starting JGroups channel server +... +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2] +... +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000079: Channel server local address is node2, physical addresses are [127.0.0.1:55300] +INFO [org.infinispan.factories.GlobalComponentRegistry] (MSC service thread 1-6) ISPN000128: Infinispan version: Infinispan 'Chakra' 8.2.7.Final +INFO [org.jboss.as.clustering.infinispan] (ServerService Thread Pool -- 68) WFLYCLINF0002: Started default cache from server container +INFO [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "ha-singleton-deployment.jar" (runtime-name : "ha-singleton-deployment.jar") +---- + +. Verify the timer is running only on one instance by observing the logs. The node running the timer will output the following every 5 seconds: ++ +[source,options="nowrap"] +---- +INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World! +---- ++ +While the instance not running, the timer will display the following as the last log line: ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deployed "ha-singleton-deployment.jar" (runtime-name : "ha-singleton-deployment.jar") +---- + +. Verify failover of the singleton deployment. Shutdown the server operating as the primary provider of the singleton, for instance by using the `Ctrl` + `C` key combination in the terminal. Observe the following messages on the node being shutdown: ++ +[source,options="nowrap"] +---- +INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 3) SingletonTimer: Hello World! +INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 4) SingletonTimer: Hello World! +INFO [org.jboss.as.server] (Thread-2) WFLYSRV0220: Server shutdown has been requested via an OS signal +WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 31) SingletonTimer is stopping: the server is either being shutdown or another node has become elected to be the primary provider of the singleton. +... +INFO [org.jboss.as] (MSC service thread 1-6) WFLYSRV0050: WildFly Core 3.0.0.Final stopped in 88ms +---- ++ +Now observe the log messages on the second server. The node will now be elected as the primary provider of the singleton, deployment will complete, and the timer will start operating: ++ +[source,options="nowrap"] +---- +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the jboss.deployment.unit."ha-singleton-deployment.jar".FIRST_MODULE_USE service +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-4) ISPN000094: Received new cluster view for channel server: [node2|2] (1) [node2] +... +WARNING [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (ServerService Thread Pool -- 68) SingletonTimer is initializing. +INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World! +INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 2) SingletonTimer: Hello World! +---- + +[[determining_the_primary_provider_using_cli]] +== Determining the primary provider of Singleton deployment using CLI + +The JBoss CLI tool can be used to determine the primary provider and the complete list of providers of any singleton service. This is generally useful for operations team or tooling. + +Once the server is running and the application is deployed, the server exposes runtime resources corresponding to the deployment. +Note the `include-runtime` flag on the `read-resource` operation. + +[source,options="nowrap"] +---- +[standalone@localhost:9990 /] /subsystem=singleton/singleton-policy=default/deployment=ha-singleton-deployment.jar:read-resource(include-runtime=true) +{ + "outcome" => "success", + "result" => { + "is-primary" => true, + "primary-provider" => "node1", + "providers" => [ + "node1", + "node2" + ] + } +} +---- + +The typical use case for scripting to determine the primary provider of a service and potentially act upon it, is to run the `jboss-cli` with a given operation and receive a JSON formatted output as shown here: + +[source,options="nowrap"] +---- +[rhusar@ribera bin]$ ./jboss-cli.sh --output-json --connect "/subsystem=singleton/singleton-policy=default/deployment=ha-singleton-deployment.jar:read-attribute(name=primary-provider)" +{ + "outcome" : "success", + "result" : "node1" +} +---- + +Note that the `include-runtime` flag is not required when a specific attribute is queried. Please refer to the documentation for more information on using the CLI. + +== Troubleshooting + +Should the singleton be running on multiple nodes, the most common causes are accidentally starting with the `standalone.xml` or `standalone-full.xml` profile instead of with the `standalone-ha.xml` or `standalone-full-ha.xml` profile. +Make sure to start the server with an HA profile using `-c standalone-ha.xml`. + +Another common cause is that the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that multicast is enabled or change the `jgroups` subsystem configuration to use a different discovery mechanism. +Observe the following log line to ensure that the discovery was successful: + +[source,options="nowrap"] +---- +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2] +---- + +== Making Existing Deployments Singleton + +In this quickstart, the deployment is made singleton by a configuration file bundled in the archive. +Inspect the content in `src/main/resources/META-INF/singleton-deployment.xml`. +Any existing deployment can be made singleton by using _deployment overlays_ mechanism. +To demonstrate how to use deployment overlays, follow these steps: + +. Move the `src/main/resources/META-INF/singleton-deployment.xml` file into root directory of this quickstart. +. Rebuild the project. Ensure that the servers are started, and redeploy the application, which will no longer be configured by singleton deployment by the archive: ++ +[source,options="nowrap"] +---- +$ mvn clean install +$ mvn wildfly:deploy +$ mvn wildfly:deploy -Dwildfly.port=10090 +---- + +. Start the management CLI and set up a deployment overlay on both servers. Make sure you use the port offset for the second server. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect +deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml +deployment-overlay redeploy-affected --name=singleton-deployment +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml deployment-overlay redeploy-affected --name=singleton-deployment +---- ++ +NOTE: For Windows, use the ` __{jbossHomeName}_1__\bin\jboss-cli.bat` and ` __{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. + +. Review the deployment overlay changes in the `standalone-ha.xml` server profile: ++ +[source,xml,options="nowrap"] +---- + + + + + + +---- + +. Observe the server output. The deployments are now set up as singleton deployments. + +. To remove the deployment overlay run the following CLI command: ++ +[source,options="nowrap"] +---- +deployment-overlay remove --name=singleton-deployment +deployment-overlay redeploy-affected --name=singleton-deployment +---- + +For convenience, the management CLI scripts to add the deployment overlay, `singleton-deployment-overlay-add.cli`, and to remove the deployment overlay, `singleton-deployment-overlay-remove.cli`, are located in the root directory of this quickstart. + +== Undeploy the Archives + +. Ensure all {productName} servers are started. +. Navigate to the root directory of this quickstart in the terminal. +. Use the following commands to undeploy the artifacts: ++ +[source,options="nowrap"] +---- +$ mvn wildfly:undeploy +$ mvn wildfly:undeploy -Dwildfly.port=10090 +---- + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/ha-singleton-deployment/README.adoc b/ha-singleton-deployment/README.adoc index 2457d0a022..b79b87b10a 100644 --- a/ha-singleton-deployment/README.adoc +++ b/ha-singleton-deployment/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ha-singleton-deployment +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ha-singleton-deployment: Deploying Cluster-wide Singleton Services Using Singleton Deployments :author: Radoslav Husar @@ -22,11 +219,66 @@ The example is built and packaged as a single EJB archive. For more information about singleton deployments, see _HA Singleton Deployments_ in the {LinkDevelopmentGuide}[__{DevelopmentBookName}__] for {DocInfoProductName} located on the Red Hat Customer Portal. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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}_1 and {jbossHomeName}_2 -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Setting Up the Test Environment @@ -257,9 +509,55 @@ $ mvn wildfly:undeploy -Dwildfly.port=10090 ---- // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -269,4 +567,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/ha-singleton-deployment/pom.xml b/ha-singleton-deployment/pom.xml index e0ffac0515..160cf1355d 100644 --- a/ha-singleton-deployment/pom.xml +++ b/ha-singleton-deployment/pom.xml @@ -31,12 +31,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ha-singleton-deployment - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ejb Quickstart: HA Singleton Deployment This quickstart demonstrates the recommended way to deploy any service as a cluster-wide singleton. diff --git a/ha-singleton-service/README-source.adoc b/ha-singleton-service/README-source.adoc new file mode 100644 index 0000000000..f93ba595de --- /dev/null +++ b/ha-singleton-service/README-source.adoc @@ -0,0 +1,490 @@ +include::../shared-doc/attributes.adoc[] + += ha-singleton-service: Deploying Cluster-wide Singleton MSC Services +:author: Radoslav Husar +:level: Advanced +:technologies: JBoss MSC, Singleton Service, Clustering + +[abstract] +The `ha-singleton-service` quickstart demonstrates how to deploy a cluster-wide singleton JBoss MSC service. + +:standalone-server-type: ha +:archiveType: jar +:requires-multiple-servers: +:jbds-not-supported: + +== What is it? + +The `ha-singleton-services` quickstart demonstrates pattern, or way, to deploy a cluster-wide singleton JBoss MSC service – a singleton service and a querying service deployed on all nodes which regularly queries for the value provided by the singleton service. + +Make sure you inspect the `activate()` method of the `SingletonServiceActivator` class of the example. Although the default election policy is used to build the singleton services for this example, scripts and instructions are provided later in this document to demonstrate how to xref:configuring_election_policies[configure other election policies]. + +This example is built and packaged as JAR archive. + +For more information about clustered singleton services, see _HA Singleton Service_ in the {LinkDevelopmentGuide}[__{DevelopmentBookName}__] for {DocInfoProductName} located on the Red Hat Customer Portal. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName}_1 and {jbossHomeName}_2 +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Clone the {productName} Directory + +While you can run this example starting only one instance of the server, if you want to see the singleton behavior, you must start at least two instances of the server. Copy the entire {productName} directory to a new location to use for the second cluster member. + +== Start the Servers with the HA Profile + +NOTE: You must start the server using the HA profile or the singleton service will not start correctly._ + +Start the two {productName} servers with the HA profile, passing a unique node ID. These logical node names are used in the log to identify which node is elected. If you are running the servers on the same host, you must also pass a socket binding port offset on the command line to start the second server. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. + + +This example is not limited to two servers. Additional servers can be started by specifying a unique node name and port offset for each one. + +== Run the Example + +This example demonstrates a singleton service and a querying service that regularly queries for the value that the singleton service provides. + +=== Build and Deploy to Server 1 + +. Start the {productName} servers as described in the above section. +. Open a terminal and navigate to the `ha-singleton-service/` directory located in the root directory of the quickstarts. +. Use the following command to clean up any previously built artifacts, and to build and deploy the JAR archive. ++ +[source,options="nowrap"] +---- +$ mvn clean install wildfly:deploy +---- + +. Investigate the Console Output for Server 1. Verify that the `target/ha-singleton-service.jar` archive is deployed to `node1`, which is the first server started without port offset, by checking the server log. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.server.deployment] (MSC service thread 1-7) WFLYSRV0027: Starting deployment of "ha-singleton-service.jar" (runtime-name: "ha-singleton-service.jar") +INFO [ServiceActivator] (MSC service thread 1-5) Singleton and querying services activated. +INFO [QueryingService] (MSC service thread 1-3) Querying service started. +... +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service service +INFO [org.jboss.as.quickstarts.ha.singleton.service.SingletonService] (MSC service thread 1-3) Singleton service started on node1. +... +INFO [org.jboss.as.quickstarts.ha.singleton.service.QueryingService] (pool-12-thread-1) Singleton service running on node1. +---- ++ +You might see the following warnings in the server log after the applications are deployed. These warnings can be ignored in a development environment. ++ +[source,options="nowrap"] +---- +WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) +WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) +---- + +=== Deploy the Archive to Server 2 + +. Use the following command to deploy the same archive to the second server. Because the default socket binding port for deployment is `9990` and the second server ports are offset by `100`, you must pass the sum, `10090`, for the socket binding port as the argument to the `deploy` Maven goal. ++ +[source,options="nowrap"] +---- +mvn wildfly:deploy -Dwildfly.port=10090 +---- + +. Investigate the console output for both servers. Verify that the `target/ha-singleton-service.jar` archive is deployed to `node2` by checking the server log. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.repository] (management-handler-thread - 4) WFLYDR0001: Content added at location /Users/rhusar/wildfly/build/target/y/standalone/data/content/18/6efcc6c07b471f641cfcc97f9120505726e6bd/content +INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-service.jar" (runtime-name: "ha-singleton-service.jar") +INFO [ServiceActivator] (MSC service thread 1-6) Singleton and querying services activated. +INFO [QueryingService] (MSC service thread 1-5) Querying service started. +... +INFO [org.jboss.as.server] (management-handler-thread - 4) WFLYSRV0010: Deployed "ha-singleton-service.jar" (runtime-name : "ha-singleton-service.jar") +... +INFO [org.jboss.as.quickstarts.ha.singleton.service.QueryingService] (pool-12-thread-1) Singleton service running on node1. +---- + +. Inspect the server log of the first node. Since the cluster membership has changed, the election policy determines which node will run the singleton. ++ +[source,options="nowrap"] +---- +INFO [org.infinispan.CLUSTER] (remote-thread--p7-t1) ISPN000336: Finished cluster-wide rebalance for cache default, topology id = 5 +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node1 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service service +---- + +. Verify that the querying service is running on all nodes and that all are querying the same singleton service instance by confirming that the same node name is printed in the log. Both nodes will output the following message every 5 seconds: ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.quickstarts.ha.singleton.service.QueryingService] (pool-12-thread-1) Singleton service running on node1. +---- + +=== Test Singleton Service Failover for the Example + +. To verify failover of the singleton service, shut down the server operating as the primary singleton provider by using the `Ctrl` + `C` key combination in the terminal. The following messages confirm that the node is shut down. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.quickstarts.ha.singleton.service.QueryingService] (pool-12-thread-1) Singleton service running on node1. +INFO [org.jboss.as.server] (Thread-2) WFLYSRV0220: Server shutdown has been requested via an OS signal +INFO [org.jboss.as.quickstarts.ha.singleton.service.SingletonService] (MSC service thread 1-6) Singleton service stopped on node1. +INFO [QueryingService] (MSC service thread 1-6) Querying service stopped. +... +INFO [org.jboss.as] (MSC service thread 1-6) WFLYSRV0050: JBoss EAP 7.1.0.Beta1 (WildFly Core 3.0.0.Beta26-redhat-1) stopped in 66ms +---- ++ +. Now observe the log messages on the second server. The second node is now elected as the primary singleton provider. ++ +[source,options="nowrap"] +---- +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service service +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service service +INFO [org.jboss.as.quickstarts.ha.singleton.service.SingletonService] (MSC service thread 1-3) Singleton service started on node2. +---- + +=== Undeploy the Example + +. Start the {productName} servers as described in the above section. +. Open a terminal and navigate to the `ha-singleton-service/` directory located in the root directory of the quickstarts. +. Use the following command to undeploy the JAR archive from Server 1. ++ +[source,options="nowrap"] +---- +$ mvn wildfly:undeploy +---- + +. Use the following command to undeploy the JAR archive from Server 2. ++ +[source,options="nowrap"] +---- +$ mvn wildfly:undeploy -Dwildfly.port=10090 +---- + +[[configuring_election_policies]] +== Configuring Election Policies + +As mentioned previously, the `activate()` method in the `ServiceActivator` class for each example in this quickstart uses the default election policy to build the singleton services. Once you have successfully deployed and verified the example, you might want to test different election policy configurations to see how they work. + +Election policies are configured using {productName} management CLI commands. Scripts are provided to configure a simple xref:configure_a_name_preference_election_policy[name preference election policy] and a xref:configure_a_random_election_policy[random election policy]. A script is also provided to configure a xref:configure_a_singleton_policy_that_defines_a_quorum[quorum for the singleton policy]. + +[[configure_a_name_preference_election_policy]] +=== Configure a Name Preference Election Policy + +This example configures the default election policy to be based on logical names. + +. If you have tested other election policies that configured the `singleton` subsystem, see xref:restoring_the_default_singleton_subsystem_configuration[Restoring the Default Singleton Subsystem Configuration] for instructions to restore the singleton election policy to the default configuration. +. Start the two servers with the HA profile as described above. +. Review the contents of the `name-preference-election-policy-add.cli` file located in the root of this quickstart directory. This script configures the default election policy to choose nodes in a preferred order of `node3`, `node2`, and `node1` using this command. ++ +[source,options="nowrap"] +---- +/subsystem=singleton/singleton-policy=default/election-policy=simple:write-attribute(name=name-preferences,value=[node3,node2,node1]) +---- + +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Make sure you replace __{jbossHomeName}_1__ with the path to the target Server 1. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=name-preference-election-policy-add.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +{ + "outcome" => "success", + "response-headers" => { + "operation-requires-reload" => true, + "process-state" => "reload-required" + } +} +---- ++ +Note that the `name-preference-election-policy-add.cli` script executes the `reload` command, so a reload is not required. + +. Stop the server and review the changes made to the `standalone-ha.xml` server configuration file by the management CLI commands. The `singleton` subsystem now contains a `name-preferences` element under the `simple-election-policy` that specifies the preferences `node3 node2 node1`. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + + + node3 node2 node1 + + + + +---- + +. Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_2__\bin\jboss-cli.bat` script. + +. Make sure both servers are started, deploy one the example to both servers, and verify that the election policy is now in effect. The server running the election policy should now log the following message. ++ +[source,options="nowrap"] +---- +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service service +---- ++ +The other nodes should log the following message. ++ +[source,options="nowrap"] +---- +INFO [org.jboss.as.quickstarts.ha.singleton.service.QueryingService] (pool-12-thread-1) Singleton service running on node2. +---- + +[[configure_a_random_election_policy]] +=== Configure a Random Election Policy + +This example configures an election policy that elects a random cluster member when the cluster membership changes. + +. If you have tested other election policies that configured the `singleton` subsystem, see xref:restoring_the_default_singleton_subsystem_configuration[Restoring the Default Singleton Subsystem Configuration] for instructions to restore the singleton election policy to the default configuration. +. Start the two servers with the HA profile as described above. +. Review the contents of the `random-election-policy-add.cli` file located in the root of this quickstart directory. This script removes the default simple election policy and configures the default election policy to elect a random cluster member using these commands. ++ +[source,options="nowrap"] +---- +/subsystem=singleton/singleton-policy=default/election-policy=simple:remove(){allow-resource-service-restart=true} +/subsystem=singleton/singleton-policy=default/election-policy=random:add() +---- + +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Make sure you replace `__{jbossHomeName}_1__` with the path to the target Server 1. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=random-election-policy-add.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- ++ +Note that the `random-election-policy-add.cli` script executes the `reload` command, so a reload is not required. + +. Stop the server and review the changes made to the `standalone-ha.xml` server configuration file by the management CLI commands. The `singleton` subsystem now contains a `random-election-policy` element under the `singleton-policy` that specifies the preferences `node3 node2 node1`. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + + + + + +---- + +. Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=random-election-policy-add.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_2__\bin\jboss-cli.bat` script. + +. Make sure both servers are started, then deploy the example to both servers, and verify that the election policy is now in effect. + +[[configure_a_singleton_policy_that_defines_a_quorum]] +=== Configure a Quorum for the Singleton Policy + +A quorum specifies the minimum number of cluster members that must be present for the election to even begin. This mechanism is used to mitigate a split brain problem by sacrificing the availability of the singleton service. If there are less members than the specified quorum, no election is performed and the singleton service is not run on any node. + +. Quorum can be configured for any singleton policy. Optionally, if you have reconfigured the `singleton` subsystem, see xref:restoring_the_default_singleton_subsystem_configuration[Restoring the Default Singleton Subsystem Configuration] for instructions to restore the singleton election policy to the default configuration. +. Start the two servers with the HA profile as described above. +. Review the contents of the `quorum-add.cli` file located in the root of this quickstart directory. This script specifies the minimum number of cluster members required for the singleton policy using this command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +/subsystem=singleton/singleton-policy=default:write-attribute(name=quorum,value=2) +---- + +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Make sure you replace `__{jbossHomeName}_1__` with the path to the target Server 1. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=quorum-add.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +{ + "outcome" => "success", + "response-headers" => { + "operation-requires-reload" => true, + "process-state" => "reload-required" + } +} +---- ++ +Note that the `quorum-add.cli` script executes the `reload` command, so a reload is not required. + +. Review the changes made to the `standalone-ha.xml` server configuration file by the management CLI commands. The `singleton` subsystem now contains a `quorum` attribute for the `singleton-policy` element that specifies the minimum number. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + + + + + +---- + +. Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=quorum-add.cli +---- ++ +NOTE: For Windows, use the __{jbossHomeName}_2__\bin\jboss-cli.bat` script. + +. Make sure both servers are started, deploy the example to both servers. While both servers are running, observe the server logs. The server running the election policy should now log the following message. ++ +[source,options="nowrap"] +---- +INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0007: Just reached required quorum of 2 for org.jboss.as.quickstarts.ha.singleton.service service. If this cluster loses another member, no node will be chosen to provide this service. +---- + +. Shut down one of the servers by using the `Ctrl` + `C` key combination in the terminal to verify that no singleton service will be running after the quorum is not reached. ++ +[source,options="nowrap"] +---- +WARN [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0006: Failed to reach quorum of 2 for org.jboss.as.quickstarts.ha.singleton.service service. No primary singleton provider will be elected. +INFO [org.wildfly.clustering.server] (thread-20) WFLYCLSV0002: This node will no longer operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service service +INFO [org.jboss.as.quickstarts.ha.singleton.service.SingletonService] (MSC service thread 1-1) Singleton service stopped on node2. +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2) ISPN000094: Received new cluster view for channel server: [node2|4] (1) [node2] +... +WARN [QueryingService] (pool-4-thread-1) Singleton service not running anywhere. +---- + +. A `quorum-remove.cli` script is provided in the root directory of this quickstart that removes the quorum from the `singleton` subsystem. + +[[determining_the_primary_provider_using_cli]] +== Determining the primary provider of Singleton Service using CLI + +The JBoss CLI tool can be used to determine the primary provider and the complete list of providers of any singleton service. This is generally useful for operations team or tooling. + +Once the server is running and the application is deployed, the server exposes runtime resources corresponding to the JBoss MSC service. +Note the `include-runtime` flag on the `read-resource` operation. + +[source,options="nowrap"] +---- +[standalone@localhost:9990 /] /subsystem=singleton/singleton-policy=default/service=org.jboss.as.quickstarts.ha.singleton.service:read-resource(include-runtime=true) +{ + "outcome" => "success", + "result" => { + "is-primary" => true, + "primary-provider" => "node1", + "providers" => [ + "node1", + "node2" + ] + } +} +---- + +The typical use case for scripting to determine the primary provider of a service and potentially act upon it, is to run the `jboss-cli` with a given operation and receive a JSON formatted output as shown here: + +[source,options="nowrap"] +---- +[rhusar@ribera bin]$ ./jboss-cli.sh --output-json --connect "/subsystem=singleton/singleton-policy=default/service=org.jboss.as.quickstarts.ha.singleton.service:read-attribute(name=primary-provider)" +{ + "outcome" : "success", + "result" : "node1" +} +---- + +Note that the `include-runtime` flag is not required when a specific attribute is queried. Please refer to the documentation for more information on using the CLI. + + +== Troubleshooting Runtime Problems + +If the singleton is running on multiple nodes, check for the following issues. + +* The most common cause of this problem is starting the servers with the `standalone.xml` or `standalone-full.xml` profile instead of with the `standalone-ha.xml` or `standalone-full-ha.xml` profile. Make sure to start the server with an HA profile using `-c standalone-ha.xml`. + +* Another common cause is because the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that `multicast` is enabled or change the `jgroups` subsystem configuration to use a different discovery mechanism. Confirm the following message in the server log to ensure that the discovery was successful. ++ +[source,options="nowrap"] +---- +INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2] +---- + +== Undeploy the Deployments + +If you have not yet done so, you can undeploy all of the deployed artifacts by following these steps. + +. Start the two servers with the HA profile as described above. +. Open a terminal and navigate to the root directory of this quickstart. +. Use the following commands to undeploy all of the artifacts. ++ +[source,options="nowrap"] +---- +$ mvn wildfly:undeploy +$ mvn wildfly:undeploy -Dwildfly.port=10090 +---- + +[[restoring_the_default_singleton_subsystem_configuration]] +== Restoring the Default Singleton Subsystem Configuration + +Some of these examples require that you modify the election policies for the `singleton` subsystem by running management CLI scripts. After you have completed testing each configuration, it is important to restore the `singleton` subsystem to its default configuration before you run any other examples. + +. Start both servers with the HA profile as described above. +. Open a terminal and navigate to the root directory of this quickstart. +. Restore your default server configurations by running these commands. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=restore-singleton-subsystem.cli +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/ha-singleton-service/README.adoc b/ha-singleton-service/README.adoc index f93ba595de..04d74f549a 100644 --- a/ha-singleton-service/README.adoc +++ b/ha-singleton-service/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: ha-singleton-service +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = ha-singleton-service: Deploying Cluster-wide Singleton MSC Services :author: Radoslav Husar @@ -24,11 +221,66 @@ This example is built and packaged as JAR archive. For more information about clustered singleton services, see _HA Singleton Service_ in the {LinkDevelopmentGuide}[__{DevelopmentBookName}__] for {DocInfoProductName} located on the Red Hat Customer Portal. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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}_1 and {jbossHomeName}_2 -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Clone the {productName} Directory @@ -475,9 +727,55 @@ $ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -487,4 +785,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/ha-singleton-service/pom.xml b/ha-singleton-service/pom.xml index 92232c7371..135fea4c78 100644 --- a/ha-singleton-service/pom.xml +++ b/ha-singleton-service/pom.xml @@ -26,12 +26,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 ha-singleton-service - 31.0.0.Final-SNAPSHOT + 31.0.0.Final jar Quickstart: HA Singleton Service This quickstart demonstrates a singleton MSC service packaged in a jar. diff --git a/helloworld-jms/README-source.adoc b/helloworld-jms/README-source.adoc new file mode 100644 index 0000000000..ba96f23360 --- /dev/null +++ b/helloworld-jms/README-source.adoc @@ -0,0 +1,157 @@ +include::../shared-doc/attributes.adoc[] + += helloworld-jms: Helloworld JMS Example +:author: Weston Price +:level: Intermediate +:technologies: JMS + +[abstract] +The `helloworld-jms` quickstart demonstrates the use of external JMS clients with {productName}. + +:standalone-server-type: full +:archiveType: jar +:restoreScriptName: remove-jms.cli +:app-user-groups: guest + +== What is it? + +The `helloworld-jms` quickstart demonstrates the use of external JMS clients with {productNameFull}. + +It contains the following: + +. A message producer that sends messages to a JMS destination deployed to a {productName} server. + +. A message consumer that receives message from a JMS destination deployed to a {productName} server. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Add the Authorized Application User +include::../shared-doc/add-application-user.adoc[leveloffset=+1] +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the JMS `test` queue by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-jms.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone full profile] as described above. + +. Review the `configure-jms.cli` file in the `src/main/scripts/` folder of this quickstart directory. This script adds the `test` queue to the `messaging` subsystem in the server configuration file. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-jms.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +. You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file and review the changes. + +The following `testQueue` jms-queue was configured in the default server configuration of the `messaging-activemq` subsystem. + +[source,xml,options="nowrap"] +---- + +---- + + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] + + +=== Investigate the Console Output + +If the Maven command is successful, with the default configuration you will see output similar to this: + +[source,options="nowrap"] +---- +timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main +INFO: Attempting to acquire connection factory "jms/RemoteConnectionFactory" +SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder". +SLF4J: Defaulting to no-operation (NOP) logger implementation +SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details. +timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main +INFO: Found connection factory "jms/RemoteConnectionFactory" in JNDI +timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main +INFO: Attempting to acquire destination "jms/queue/test" +timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main +INFO: Found destination "jms/queue/test" in JNDI +timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main +INFO: Sending 1 messages with content: Hello, World! +timestamp org.jboss.as.quickstarts.jms.HelloWorldJMSClient main +INFO: Received message with content Hello, World! +---- + +=== Optional Properties + +The example provides for a certain amount of customization for the integration test using the system properties. + +[cols="20%,30%,50%",options="headers"] +|=== +| Property +| Default value +| Description + +| username +| quickstartUser +| This `username` is used for both the JMS connection and the JNDI look up. Instructions to set up the quickstart application user can be found here: link:{addApplicationUserDocUrl}[Add an Application User]. + +| password +| quickstartPwd1! +| This `password` is used for both the JMS connection and the JNDI look up. Instructions to set up the quickstart application user can be found here: link:{addApplicationUserDocUrl}[Add an Application User] + +| connection.factory +| jms/RemoteConnectionFactory +| The name of the JMS `ConnectionFactory` you want to use. + +| destination +| jms/queue/test +| The name of the JMS `Destination` you want to use. + +| message.count +| 1 +| The number of JMS messages you want to produce and consume. + +| message.content +| "Hello, World!" +| The content of the JMS `TextMessage`. + +| java.naming.provider.url +| "http-remoting://127.0.0.1:8080" +| This property allows configuration of the JNDI directory used to look up the JMS destination. This is useful when the client resides on another host. +|=== + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script removes the `test` queue from the `messaging` subsystem in the server configuration. You should see the following result when you run the script. + +[source,options="nowrap"] +---- +The batch executed successfully +---- + +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file diff --git a/helloworld-jms/README.adoc b/helloworld-jms/README.adoc index 79dbfb37d9..5ba5feea0d 100644 --- a/helloworld-jms/README.adoc +++ b/helloworld-jms/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: helloworld-jms +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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-jms: Helloworld JMS Example :author: Weston Price @@ -25,17 +222,306 @@ It contains the following: . A message consumer that receives message from a JMS destination deployed to a {productName} server. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Add the Authorized Application User -include::../shared-doc/add-application-user.adoc[leveloffset=+1] +:leveloffset: +1 + +[[add_the_application_user]] += Add the Authorized Application User + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true + +This quickstart uses secured application interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -79,7 +565,31 @@ The following `testQueue` jms-queue was configured in the default server configu // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: === Investigate the Console Output @@ -145,7 +655,40 @@ The example provides for a certain amount of customization for the integration t |=== // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script removes the `test` queue from the `messaging` subsystem in the server configuration. You should see the following result when you run the script. @@ -155,4 +698,11 @@ This script removes the `test` queue from the `messaging` subsystem in the serve The batch executed successfully ---- -include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file +:leveloffset: +1 + +[[openshift_incompatibility]] += {xpaasproduct-shortname} Incompatibility + +This quickstart is not compatible with {xpaasproduct-shortname} or {xpaasproductOpenShiftOnline-shortname} templates. + +:leveloffset!: diff --git a/helloworld-jms/pom.xml b/helloworld-jms/pom.xml index 8d2c01cd0b..397ab86015 100644 --- a/helloworld-jms/pom.xml +++ b/helloworld-jms/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld-jms - 31.0.0.Final-SNAPSHOT + 31.0.0.Final jar Quickstart: helloworld-jms A Helloworld JMS external producer/consumer client @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/helloworld-mdb/README-source.adoc b/helloworld-mdb/README-source.adoc new file mode 100644 index 0000000000..32d9690b9c --- /dev/null +++ b/helloworld-mdb/README-source.adoc @@ -0,0 +1,404 @@ +include::../shared-doc/attributes.adoc[] + += helloworld-mdb: Helloworld Using an MDB (Message-Driven Bean) +:author: Serge Pagop, Andy Taylor, Jeff Mesnil +:level: Intermediate +:technologies: JMS, EJB, MDB +:openshift: true + +[abstract] +The `helloworld-mdb` quickstart uses JMS and EJB Message-Driven Bean (MDB) to create and deploy JMS topic and queue resources in {productName}. + +:standalone-server-type: full +:archiveType: war + +== What is it? + +The `helloworld-mdb` quickstart demonstrates the use of JMS and EJB Message-Driven Bean in {productNameFull}. + +This project creates two JMS resources: + +* A queue named `HELLOWORLDMDBQueue` bound in JNDI as `java:/queue/HELLOWORLDMDBQueue` +* A topic named `HELLOWORLDMDBTopic` bound in JNDI as `java:/topic/HELLOWORLDMDBTopic` + +//************************************************* +// Product Release content only +//************************************************* + + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +// Additional deployment information +Look at the {productName} console or server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: + +[source,options="nowrap"] +---- +INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "helloworld-mdb.war" (runtime-name: "helloworld-mdb.war") +... +INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-4) WFLYMSGAMQ0006: Unbound messaging object to jndi name java:/queue/HELLOWORLDMDBQueue +INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-4) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/queue/HELLOWORLDMDBQueue +INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-2) WFLYMSGAMQ0006: Unbound messaging object to jndi name java:/topic/HELLOWORLDMDBTopic +INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-3) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/topic/HELLOWORLDMDBTopic +INFO [org.jboss.as.ejb3] (MSC service thread 1-4) WFLYEJB0042: Started message driven bean 'HelloWorldQueueMDB' with 'activemq-ra.rar' resource adapter +INFO [org.jboss.as.ejb3] (MSC service thread 1-1) WFLYEJB0042: Started message driven bean 'HelloWorldQTopicMDB' with 'activemq-ra.rar' resource adapter +... +INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 87) WFLYUT0021: Registered web context: '/helloworld-mdb' for server 'default-server' +INFO [org.jboss.as.server] (management-handler-thread - 1) WFLYSRV0010: Deployed "helloworld-mdb.war" (runtime-name : "helloworld-mdb.war") +---- + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/ and 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 + +Look at the {productName} console or Server log and you should see log messages like the following: + +[source,options="nowrap"] +---- +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 4 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-5 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 2 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 3 +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +endif::[] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + + + +== Clustering + +You can choose to deploy and run this quickstart in a managed domain or on a standalone server. The sections below describe how to configure and start each type of server. + +Before you begin: + +. If it is running, stop the {productName} server. +. If you plan to test using a standalone server, back up the standalone server configuration file: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}__/standalone/configuration/standalone-full-ha.xml +---- + +. If you plan to test using a managed domain, back up the following files: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}__/domain/configuration/domain.xml +__{jbossHomeName}__/domain/configuration/host.xml +---- + +After you have completed testing this quickstart, you can replace these files to restore the server to its original configuration. + +=== Configure the Server and Deploy the Quickstart + +==== 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. + +// Start the {productName} Managed Domain +include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+3] + +===== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI + +. Review the `install-domain.cli` file 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: + +** Stops the servers +** Creates a server-group to test ActiveMQ Clustering +** Adds 2 servers to the server-group +** Configures ActiveMQ clustering in the full-ha profile +** Deploys the `helloworld-mdb.war` archive +** Restarts the servers. ++ + +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to run the script: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=install-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see `"outcome" => "success"` for all of the commands. + +. Restart the server in a managed domainas described above. + +==== Configure the Server and Deploy the Quickstart to a Standalone Server + +If you choose to run standalone servers instead of a managed domain, you will need two instances of the application server. +Application server 2 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. + +[[start_the_eap_standalone_server]] +===== Start the Standalone Server Using the Full HA Profile. + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} server with the standalone full HA profile, which supports messaging and high availability, by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full-ha.xml +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + +===== Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI + +. Review the `install-standalone.cli` file in the root of this quickstart directory. This script configures clustering for a standalone server. You will note it does the following: +** Enables console logging. By default, the full HA profile does not log to the console, so this script enables it. +** Enables clustering and sets a cluster password +** Enables clustering in the RemoteConnectionFactory +** Deploys the `helloworld-mdb.war` archive +** Reloads the server configuration ++ + +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to run the script: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=install-standalone.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1\bin\jboss-cli.bat__` script. + +You should see `"outcome" => "success"` for all of the commands. + +===== 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. + +. Stop the server. +. Make a copy of this {productName} directory structure to use for the second server. +. Remove the following directories from the cloned instance: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}_2__/standalone/data/activemq/bindings/ +__{jbossHomeName}_2__/standalone/data/activemq/journal/ +__{jbossHomeName}_2__/standalone/data/activemq/largemessages/ +---- + +[[start_the_eap_standalone_servers]] +===== Start the {productName} Standalone Servers with the Full HA Profile + +When you start the servers, you must pass the cluster password on the command line to avoid the warning `AMQ222186: unable to authorise cluster control`. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full-ha.xml +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. + +=== Access the Application + +==== Access the Application Running in a Managed Domain + +The application will be running at the following URL: http://localhost:9080/helloworld-mdb/HelloWorldMDBServletClient. + +It will send some messages to the queue. + +To send messages to the topic, use the following URL: http://localhost:9080/helloworld-mdb/HelloWorldMDBServletClient?topic + +==== Access the Application Running in a Standalone Server + +The application will be running at the following URL: http://localhost:8080/helloworld-mdb/HelloWorldMDBServletClient. + +It will send some messages to the queue. + +To send messages to the topic, use the following URL: http://localhost:8080/helloworld-mdb/HelloWorldMDBServletClient?topic + +=== Investigate the Server Console Output + +Look at the {productName} server console or log and you should see log messages like the following: + +[source,options="nowrap"] +---- +[Server:quickstart-messagingcluster-node1] INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-8 (ActiveMQ-client-global-threads-1067469862)) Received Message from queue: This is message 1 +[Server:quickstart-messagingcluster-node1] INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-8 (ActiveMQ-client-global-threads-1067469862)) Received Message from queue: This is message 3 +[Server:quickstart-messagingcluster-node1] INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1067469862)) Received Message from queue: This is message 5 +[Server:quickstart-messagingcluster-node2] INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-8 (ActiveMQ-client-global-threads-1771031398)) Received Message from queue: This is message 2 +[Server:quickstart-messagingcluster-node2] INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1771031398)) Received Message from queue: This is message 4 +---- + +Note that the logging indicates messages have arrived from both node 1, `quickstart-messagingcluster-node1`, as well as node 2, `quickstart-messagingcluster-node2`. + +=== 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. + +[source,options="nowrap"] +---- +WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket DatagramSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket DatagramSocket was set to 20MB, 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) +WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +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) +---- + +After the server has been running for a period of time, you might see the following warnings in the server log, which are followed by a stacktrace. You can ignore these warnings as this is is a known issue and is harmless. See https://issues.jboss.org/browse/JBEAP-794[JBEAP-794] for more information. + +[source,options="nowrap"] +---- +WARN [org.infinispan.topology.ClusterTopologyManagerImpl] (transport-thread--p15-t6) ISPN000197: Error updating cluster member list: org.infinispan.util.concurrent.TimeoutException: Replication timeout for +---- + +=== Undeploy the Archive + +When you are finished testing, use the following instructions to undeploy the quickstart. + +==== Undeploy the Quickstart from a Managed Domain + +. Make sure you have xref:start_eap_managed_domain[started the {productName} server] in a managed domain as described above. +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=undeploy-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +=== Undeploy the Quickstart from a Standalone Server + +. Make sure you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +=== Remove the Server Configuration + +==== Remove the Domain Server Configuration + +You can remove the domain configuration by manually restoring the back-up copies the configuration files or by running the JBoss CLI Script. + +[[remove_the_domain_server_configuration_manually]] +===== Remove the Domain Server Configuration Manually + +IMPORTANT: This method ensures the server is restored to its prior configuration. + +. If it is running, stop the {productName} server. +. 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. + +===== Remove the Domain Server Configuration by Running the JBoss 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:remove_the_domain_server_configuration_manually[manually restore the domain configuration] to its previous state. + +. Start the {productName} server by typing the following: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=install-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +. 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. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +This script removes the server configuration that was done by the `install-domain.cli` script. You should see the following result following the script commands. ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +[IMPORTANT] +==== +If the `:stop-server` command does not complete before the next commands are issued, you might see an error similar to the following: + +[source,options="nowrap"] +---- +{"JBAS014653: Composite operation failed and was rolled back. Steps that failed:" => {"Operation step-1" => "JBAS010977: Server (quickstart-messagingcluster-node1) still running"}} +---- + +Simply wait a few seconds and run the command a second time. +==== + +==== Remove the Standalone Server Configuration + +You can remove the domain configuration by manually restoring the back-up copies the configuration files or by running the JBoss CLI Script. + +[[remove_the_standalone_server_configuration_manually]] +===== Remove 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. + +===== Remove the Standalone Configuration by Running the JBoss 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:remove_the_standalone_server_configuration_manually[manually restore the standalone configuration] to its previous state. + +. Start the {productName} server by typing the following: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full-ha.xml +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` script. + +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}_1__` with the path to your server. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=remove-standalone.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +This script removes the server configuration that was done by the `install-standalone.cli` script. You should see the following result following the script commands: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +==== Delete the Cloned Standalone {productName} Directory + +. If it is running, stop the second instance of the {productName} server. +. Delete the cloned directory. diff --git a/helloworld-mdb/README.adoc b/helloworld-mdb/README.adoc index 64ea3624de..58b2919f20 100644 --- a/helloworld-mdb/README.adoc +++ b/helloworld-mdb/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: helloworld-mdb +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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-mdb: Helloworld Using an MDB (Message-Driven Bean) :author: Serge Pagop, Andy Taylor, Jeff Mesnil @@ -28,19 +225,295 @@ This project creates two JMS resources: // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Additional deployment information Look at the {productName} console or server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: @@ -80,16 +553,629 @@ INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveM ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: endif::[] // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +[[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: 31.x + contextDir: helloworld-mdb +deploy: + replicas: 2 +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: @@ -124,7 +1210,33 @@ After you have completed testing this quickstart, you can replace these files to You configure the server by running the `install-domain.cli` script provided in the root directory of this quickstart. // Start the {productName} Managed Domain -include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+3] +:leveloffset: +3 + +[[start_the_eap_managed_domain]] += Start the {productName} Managed Domain +//****************************************************************************** +// Include this template if your quickstart requires a normal start of a +// managed domain. +// +// This template does not currently support passing arguments for starting +// the domain, but it could be added. +// +// * Define the managed domain profile type. Supported values are: +// :managed-domain-type: default +// +//****************************************************************************** + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} managed domain by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/domain.sh +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\domain.bat` script. + +:leveloffset!: ===== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI diff --git a/helloworld-mdb/charts/helm.yaml b/helloworld-mdb/charts/helm.yaml index ac3cf2bd19..ebdb98a5a3 100644 --- a/helloworld-mdb/charts/helm.yaml +++ b/helloworld-mdb/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: helloworld-mdb deploy: replicas: 2 \ No newline at end of file diff --git a/helloworld-mdb/pom.xml b/helloworld-mdb/pom.xml index 7774ef9636..432085e9df 100644 --- a/helloworld-mdb/pom.xml +++ b/helloworld-mdb/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld-mdb - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: helloworld-mdb This project demonstrates a hello world Message-Driven Bean with Servlet 3.0 as client @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/helloworld-mutual-ssl-secured/README-source.adoc b/helloworld-mutual-ssl-secured/README-source.adoc new file mode 100644 index 0000000000..61fd319432 --- /dev/null +++ b/helloworld-mutual-ssl-secured/README-source.adoc @@ -0,0 +1,371 @@ +include::../shared-doc/attributes.adoc[] + += helloworld-mutual-ssl-secured: Securing a Web Application with Mutual (two-way) TLS Configuration and Role-based Access Control +:author: Giriraj Sharma, Stefan Guilhen +:level: Intermediate +:technologies: Mutual TLS, Security, Undertow + +[abstract] +The `helloworld-mutual-ssl-secured` quickstart demonstrates securing a Web application using client certificate authentication with authorization + +:standalone-server-type: default +:archiveType: war +:restoreScriptName: restore-configuration.cli +:app-user-groups: JBossAdmin + +== What is it? + +This example demonstrates the configuration of _mutual TLS authentication_ in {productNameFull} {productVersion} to secure a war application. + +Mutual TLS provides the same security as TLS, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server would request the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip time for client certificate exchange. In addition, the client must obtain and maintain a digital certificate. We can secure our war application deployed over {productName} with mutual(two-way) client certificate authentication and provide access permissions or privileges to legitimate users. + +The out of the box configuration for {productName} has one-way TLS enabled by default. This quickstart shows how to configure {productName} with mutual (two-way) TLS authentication in order to secure a WAR application with restricted access. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Add the Authorized Application User +include::../shared-doc/add-application-user.adoc[leveloffset=+1] + +IMPORTANT: For the purpose of this quickstart the password can contain any valid value because the `ApplicationRealm` will be used for authorization only, for example, to obtain the security roles. + +[[set_up_client_keystore_using_java_keytool]] +== Set Up the Client Keystore Using Java Keytool + +. Open a terminal and navigate to the {productName} server `configuration` directory: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ cd __{jbossHomeName}__/standalone/configuration/ +---- + +. Create the client certificate, which is used to authenticate against the server when accessing a resource through TLS. ++ +[source,options="nowrap"] +---- +$>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12 + +What is your first and last name? + [Unknown]: quickstartUser +What is the name of your organizational unit? + [Unknown]: Sales +What is the name of your organization? + [Unknown]: My Company +What is the name of your City or Locality? + [Unknown]: Sao Paulo +What is the name of your State or Province? + [Unknown]: Sao Paulo +What is the two-letter country code for this unit? + [Unknown]: BR +Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR correct? + [no]: yes +---- + ++ +Notice that it sets the `first and last name` to `quickstartUser` and that this matches the user that was added to the `ApplicationRealm`. When authorizing access to a resource, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by the `ApplicationRealm` to obtain the client's roles. + +. Export the client certificate and create a truststore by importing this certificate. ++ +[source,options="nowrap"] +---- +$>keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass secret -keypass secret -file client.crt +$>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret + +Owner: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR +Issuer: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR +Serial number: 7fd95ce4 +Valid from: Mon Jul 24 16:14:03 BRT 2017 until: Tue Jul 24 16:14:03 BRT 2018 +Certificate fingerprints: + MD5: 87:41:C5:CC:E6:79:91:F0:9D:90:AD:9E:DD:57:81:80 + SHA1: 55:35:CA:B0:DC:DD:4F:E6:B8:9F:45:4B:4B:98:93:B5:3B:7C:55:84 + SHA256: 0A:FC:93:B6:25:5A:74:42:B8:A1:C6:5F:69:88:72:7F:27:A9:81:B0:17:0C:F1:AF:3D:DE:B7:E5:F1:69:66:4B + Signature algorithm name: SHA256withRSA + Version: 3 + +Extensions: + +#1: ObjectId: 2.5.29.14 Criticality=false +SubjectKeyIdentifier [ +KeyIdentifier [ +0000: 95 84 BE C6 32 BB 2B 13 4C 7F 5D D4 C4 C8 22 12 ....2.+.L.]...". +0010: CB 09 39 09 ..9. +] +] + +Trust this certificate? [no]: yes +Certificate was added to keystore +---- ++ +It is worth noticing that the client certificate was imported under the `quickstartUser` alias. When authenticating a client in a `CLIENT_CERT` configuration, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by the `KeyStoreRealm` to match an alias in the trust store. If a trusted certificate is found under this alas, the client is considered authenticated. + +. Export client certificate to pkcs12 format. ++ +[source,options="nowrap"] +---- +$>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret +---- + +. The certificate and keystore are now properly configured. + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the SSL context and required security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-ssl.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-ssl.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following `key-store` was added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + + + +---- + +. The following `trust-manager` was added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + +---- + +. The default `ssl-context` was updated to reference the `trust-manager` to enable two-way TLS: ++ +[source,xml,options="nowrap"] +---- + + + +---- + ++ +Note that the `https-listener` in the `undertow` subsystem references the `applicationSSC` `server-ssl-context` by default. + +. The following realms were added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +The `aggregate-realm` defines different security realms for authentication and authorization. In this case, the `KeyStoreRealm` is responsible for authenticating the principal extracted from the client's certificate and the `ApplicationRealm` is responsible for obtaining the roles required to access the application. + +. The following `principal-decoder` and `security-domain` were added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + + + +---- ++ +The `x500-attribute-principal-decoder` creates a new `Principal` from the CN attribute of the `X500Principal` obtained from the client's certificate. This new principal is supplied to the security realms and is also the principal returned in methods like `getUserPrincipal` and `getCallerPrincipal`. + +. The following `http-authentication-factory` was added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + + + +---- ++ +It defines the security domain that will handle requests using the `CLIENT_CERT` HTTP mechanism. + +. The following `application-security-domain` was added to the `undertow` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +It maps the `client_cert_domain` from the quickstart application to the `http-authentication-factory` shown above, so requests made to the application go through the configured HTTP authentication factory. + +[[test_the_server_ssl_configuration]] +== Test the Server TLS Configuration + +To test the TLS configuration, access: https://localhost:8443 + +If it is configured correctly, you should be asked to trust the server certificate. + +[[import_the_client_certificate_into_your_browser]] +== Import the Certificate into Your Browser + +Before you access the application, you must import the _clientCert.p12_, which holds the client certificate, into your browser. + +[[import_the_client_certificate_into_google_chrome]] +=== Import the Certificate into Google Chrome + +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to `link:`chrome://settings/`. +. Click on *Privacy and security* and then on *Security*. +. Scroll down to the *Advanced* section and on the *Manage certificates* screen, select the *Your Certificates* tab and click on the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. +. The client certificate is now installed in the Google Chrome browser. + +[[import_the_client_certificate_into_mozilla_firefox]] +=== Import the Certificate into Mozilla Firefox + +. Click the *Edit* menu item on the browser menu and choose *Settings*. +. A new window will open. Click on *Privacy & Security* and scroll down to the *Certificates* section. +. Click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab and click the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. +. The certificate is now installed in the Mozilla Firefox browser. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +// Additional deployment information +If mutual TLS is configured properly and the WAR application is secured, you will be able to access the application only if the DN of client certificate, for example `clientCert.p12`, is same as the one defined in `app-roles.properties` file. Otherwise, it will result in an HTTP error status code of `403 Access Denied/Forbidden`. + +== Access the Application + +The application will be running at the following URL: https://localhost:8443/{artifactId} + +A page displaying the caller principal and the client certificate used for mutual TLS should be visible: + +[source,options="nowrap"] +---- +Hello World ! Mutual TLS client authentication is successful and your war app is secured.!! + +Caller Principal: quickstartUser + +Client Certificate Pem: MIIDhTCCAm2gAwIBAgIEf9lc5DANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJCUjESMBAGA1UECBMJU2FvIFBhdW +xvMRIwEAYDVQQHEwlTYW8gUGF1bG8xEzARBgNVBAoTCk15IENvbXBhbnkxDjAMBgNVBAsTBVNhbGVzMRcwFQYDVQQDEw5xdWlja3N0YXJ0VXNlcjAe +Fw0xNzA3MjQxOTE0MDNaFw0xODA3MjQxOTE0MDNaMHMxCzAJBgNVBAYTAkJSMRIwEAYDVQQIEwlTYW8gUGF1bG8xEjAQBgNVBAcTCVNhbyBQYXVsbz +ETMBEGA1UEChMKTXkgQ29tcGFueTEOMAwGA1UECxMFU2FsZXMxFzAVBgNVBAMTDnF1aWNrc3RhcnRVc2VyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A +MIIBCgKCAQEAnHwflE8K/ArTPbTeZZEFK+1jtpg9grPSD62GIz/awoIDr6Rf9vCBTpAg4lom62A0BNZDEJKdab/ExNOOBRY+/pOnYlXZTYlDpdQQap +0E7UP5EfHNZsafgpfILCop2LdTuUbcV7tLKBsthJLJ0ZCoG5QJFble+OPxEbissOvIqHfvUJZi34k9ULteLJc330g0uTuDrLgtoFQ0cbHa4FCQ86o8 +5EuRPpFeW6EBA3iYE/tKHSYsK7QSajefX6jZjXoZiUflw97SAGL43ZtvNbrKRywEfsVqDpDurjBg2HI+YahuDz5R1QWTSyTHWMZzcyJYqxjXiSf0oK +1cUahn6m5t1wIDAQABoyEwHzAdBgNVHQ4EFgQUlYS+xjK7KxNMf13UxMgiEssJOQkwDQYJKoZIhvcNAQELBQADggEBADkp+R6kSNXJNfihqbDRp3uF +tNMG6OgaYsfC7RtNLMdrhvoLlU7uWzxVCFuifvNlWVRiADBHDCRQU2uNRFW35GQSfHQyok4KoBuKlfBtQ+Xu7c8R0JzxN/rPJPXoCbShzDHo1uoz5/ +dzXZz0EjjWCPJk+LVEhEvH0GcWAp3x3irpNU4hRZLd0XomY0Z4NnUt7VMBNYDOxVxgT9qcLnEaEpIfYULubLLCFHwAga2YgsKzZYLuwMaEWK4zhPVF +ynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2Mk14gJGHUnA8= +---- + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script reverts the changes made to the `elytron` subsystem. You should see the following result when you run the script: + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] + +== Remove the keystores and certificates created for this quickstart + +. Open a terminal and navigate to the {productName} server `configuration` directory: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ cd __{jbossHomeName}__/standalone/configuration/ +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + +. Remove the `clientCert.p12`, `client.crt`, and `client.truststore` files that were generated for this quickstart. + +[[remove_the_client_certificate_from_your_browser]] +== Remove the Client Certificate from Your Browser + +After you are done with this quickstart, remember to remove the certificate that was imported into your browser. + +=== Remove the Client Certificate from Google Chrome + +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to chrome://settings/. +. Click on *Privacy and security* and then on *Security*. +. Scroll down to the *Advanced* section and on the *Manage certificates* screen, select the *Your Certificates* tab and then click on the arrow to the right of the certificate to be removed. +. The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select *Delete*. +. Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. + +=== Remove the Client Certificate from Mozilla Firefox + +. Click the *Edit* menu item on the browser menu and choose *Preferences*. +. A new window will open. Click on *Privacy & Security* and scroll down to the *Certificates* section. +. Click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab. +. Select the *quickstartUser* certificate and click the *Delete* button. +. The certificate has now been removed from the Mozilla Firefox browser. + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +* Make sure you configure the keystores and client certificates as described under xref:set_up_client_keystore_using_java_keytool[Set Up the Client Keystore Using Java Keytool]. +* Depending on the browser you choose, make sure you either xref:import_the_client_certificate_into_google_chrome[import the certificate into Google Chrome] or xref:import_the_client_certificate_into_mozilla_firefox[import the certificate into Mozilla Firefox]. +* Make sure you configure the server by running the JBoss CLI commands as described above under xref:configure_the_server[Configure the Server]. Stop the server at the end of that step. +* In {JBDSProductName}, choose *Window* –> *Web Browser*, then select the browser you chose to import the certificate. +* To deploy the application, right-click on the *{artifactId}* project and choose *Run As* –> *Run on Server*. +* Make sure you xref:restore_the_server_configuration[restore the {productName} server configuration] when you have completed testing this quickstart. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] diff --git a/helloworld-mutual-ssl-secured/README.adoc b/helloworld-mutual-ssl-secured/README.adoc index 61fd319432..748656751e 100644 --- a/helloworld-mutual-ssl-secured/README.adoc +++ b/helloworld-mutual-ssl-secured/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: helloworld-mutual-ssl-secured +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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-mutual-ssl-secured: Securing a Web Application with Mutual (two-way) TLS Configuration and Role-based Access Control :author: Giriraj Sharma, Stefan Guilhen @@ -22,13 +219,108 @@ Mutual TLS provides the same security as TLS, with the addition of authenticatio The out of the box configuration for {productName} has one-way TLS enabled by default. This quickstart shows how to configure {productName} with mutual (two-way) TLS authentication in order to secure a WAR application with restricted access. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Add the Authorized Application User -include::../shared-doc/add-application-user.adoc[leveloffset=+1] +:leveloffset: +1 + +[[add_the_application_user]] += Add the Authorized Application User + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true + +This quickstart uses secured application interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: IMPORTANT: For the purpose of this quickstart the password can contain any valid value because the `ApplicationRealm` will be used for authorization only, for example, to obtain the security roles. @@ -111,9 +403,203 @@ $>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -des . The certificate and keystore are now properly configured. // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -262,7 +748,114 @@ Before you access the application, you must import the _clientCert.p12_, which h . The certificate is now installed in the Mozilla Firefox browser. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Additional deployment information If mutual TLS is configured properly and the WAR application is secured, you will be able to access the application only if the DN of client certificate, for example `clientCert.p12`, is same as the one defined in `app-roles.properties` file. Otherwise, it will result in an HTTP error status code of `403 Access Denied/Forbidden`. @@ -293,11 +886,63 @@ ynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2M ---- // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script reverts the changes made to the `elytron` subsystem. You should see the following result when you run the script: @@ -309,7 +954,84 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: == Remove the keystores and certificates created for this quickstart @@ -347,7 +1069,27 @@ After you are done with this quickstart, remember to remove the certificate that . The certificate has now been removed from the Mozilla Firefox browser. // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions * Make sure you configure the keystores and client certificates as described under xref:set_up_client_keystore_using_java_keytool[Set Up the Client Keystore Using Java Keytool]. @@ -358,7 +1100,33 @@ include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[levelof * Make sure you xref:restore_the_server_configuration[restore the {productName} server configuration] when you have completed testing this quickstart. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only diff --git a/helloworld-mutual-ssl-secured/pom.xml b/helloworld-mutual-ssl-secured/pom.xml index a4080ff4c4..39a5435a9b 100644 --- a/helloworld-mutual-ssl-secured/pom.xml +++ b/helloworld-mutual-ssl-secured/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld-mutual-ssl-secured - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: helloworld-mutual-ssl-secured Securing helloworld Web app with mutual client ssl authentication and role-based access control diff --git a/helloworld-mutual-ssl/README-source.adoc b/helloworld-mutual-ssl/README-source.adoc new file mode 100644 index 0000000000..751614a594 --- /dev/null +++ b/helloworld-mutual-ssl/README-source.adoc @@ -0,0 +1,317 @@ +include::../shared-doc/attributes.adoc[] + += helloworld-mutual-ssl: {productName} Mutual TLS(two-way) Configuration Example +:author: Giriraj Sharma, Stefan Guilhen +:level: Intermediate +:technologies: Mutual TLS, Undertow + +[abstract] +The `helloworld-mutual-ssl` quickstart is a basic example that demonstrates mutual TLS configuration in {productName} + +:standalone-server-type: default +:archiveType: war +:restoreScriptName: restore-configuration.cli + +== What is it? + +Mutual TLS provides the same security as TLS, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used, the server requests the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip each time for client certificate exchange. In addition, the client must obtain and maintain a digital certificate. + +The out of the box configuration for {productName} has one-way TLS enabled by default. This quickstart shows how to configure {productName} with mutual (two-way) TLS authentication. + +Before you run this example, you must create the client certificate and configure the server to use two-way TLS. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +[[set_up_client_keystore_using_java_keytool]] +== Set Up the Client Keystore Using Java Keytool + +. Open a terminal and navigate to the {productName} server `configuration` directory: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ cd __{jbossHomeName}__/standalone/configuration/ +---- + +. Create the client certificate, which is used to authenticate against the server when accessing a resource through TLS. ++ +[source,options="nowrap"] +---- +$>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12 + +What is your first and last name? + [Unknown]: quickstartUser +What is the name of your organizational unit? + [Unknown]: Sales +What is the name of your organization? + [Unknown]: My Company +What is the name of your City or Locality? + [Unknown]: Sao Paulo +What is the name of your State or Province? + [Unknown]: Sao Paulo +What is the two-letter country code for this unit? + [Unknown]: BR +Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR correct? + [no]: yes +---- + +. Export the client certificate and create a truststore by importing this certificate: ++ +[source,options="nowrap"] +---- +$>keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass secret -keypass secret -file client.crt +$>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret + +Owner: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR +Issuer: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR +Serial number: 7fd95ce4 +Valid from: Mon Jul 24 16:14:03 BRT 2017 until: Tue Jul 24 16:14:03 BRT 2018 +Certificate fingerprints: + MD5: 87:41:C5:CC:E6:79:91:F0:9D:90:AD:9E:DD:57:81:80 + SHA1: 55:35:CA:B0:DC:DD:4F:E6:B8:9F:45:4B:4B:98:93:B5:3B:7C:55:84 + SHA256: 0A:FC:93:B6:25:5A:74:42:B8:A1:C6:5F:69:88:72:7F:27:A9:81:B0:17:0C:F1:AF:3D:DE:B7:E5:F1:69:66:4B + Signature algorithm name: SHA256withRSA + Version: 3 + +Extensions: + +#1: ObjectId: 2.5.29.14 Criticality=false +SubjectKeyIdentifier [ +KeyIdentifier [ +0000: 95 84 BE C6 32 BB 2B 13 4C 7F 5D D4 C4 C8 22 12 ....2.+.L.]...". +0010: CB 09 39 09 ..9. +] +] + +Trust this certificate? [no]: yes +Certificate was added to keystore +---- + +. Export client certificate to pkcs12 format ++ +[source,options="nowrap"] +---- +$>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret +---- + +. The certificate and keystore are now properly configured. + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + + +[[configure_the_server]] +== Configure the Server + +You configure the SSL context by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-ssl.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-ssl.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following `keystore` element was added to the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + + + +---- + +. The following `trust-manager` was added to the `elytron` subsystem: + ++ +[source,xml,options="nowrap"] +---- + + + +---- + +. The default `ssl-context` was updated to reference the `trust-manager` to enable two-way TLS: + ++ +[source,xml,options="nowrap"] +---- + + + +---- + ++ +Note that the `https-listener` in the `undertow` subsystem references the `applicationSSC` `server-ssl-context` by default. + +[[test_the_server_ssl_configuration]] +== Test the Server TLS Configuration + +To test the TLS configuration, access: https://localhost:8443 + +If it is configured correctly, you should be asked to trust the server certificate. + +[[import_the_client_certificate_into_your_browser]] +== Import the Client Certificate into Your Browser + +Before you access the application, you must import the _clientCert.p12_, which holds the client certificate, into your browser. + +[[import_the_client_certificate_into_google_chrome]] +=== Import the Client Certificate into Google Chrome + +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to `link:`chrome://settings/`. +. Click on *Privacy and security* and then on *Security*. +. Scroll down to the *Advanced* section and on the *Manage certificates* screen, select the *Your Certificates* tab and click on the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. +. The client certificate is now installed in the Google Chrome browser. + +[[import_the_client_certificate_into_mozilla_firefox]] +=== Import the Client Certificate into Mozilla Firefox + +. Click the *Edit* menu item on the browser menu and choose *Settings*. +. A new window will open. Click on *Privacy & Security* and scroll down to the *Certificates* section. +. Click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab and click the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. +. The certificate is now installed in the Mozilla Firefox browser. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL: https://localhost:8443/{artifactId}/HelloWorld. + +A page displaying the client certificate should be visible: + +[source,options="nowrap"] +---- +Hello World ! WildFly mutual TLS is configured and client certificate is verified !! + +Client Certificate Pem: MIIDhTCCAm2gAwIBAgIEf9lc5DANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJCUjESMBAGA1UECBMJU2FvIFBhd +WxvMRIwEAYDVQQHEwlTYW8gUGF1bG8xEzARBgNVBAoTCk15IENvbXBhbnkxDjAMBgNVBAsTBVNhbGVzMRcwFQYDVQQDEw5xdWlja3N0YXJ0VXNlcj +AeFw0xNzA3MjQxOTE0MDNaFw0xODA3MjQxOTE0MDNaMHMxCzAJBgNVBAYTAkJSMRIwEAYDVQQIEwlTYW8gUGF1bG8xEjAQBgNVBAcTCVNhbyBQYXV +sbzETMBEGA1UEChMKTXkgQ29tcGFueTEOMAwGA1UECxMFU2FsZXMxFzAVBgNVBAMTDnF1aWNrc3RhcnRVc2VyMIIBIjANBgkqhkiG9w0BAQEFAAOC +AQ8AMIIBCgKCAQEAnHwflE8K/ArTPbTeZZEFK+1jtpg9grPSD62GIz/awoIDr6Rf9vCBTpAg4lom62A0BNZDEJKdab/ExNOOBRY+/pOnYlXZTYlDp +dQQap0E7UP5EfHNZsafgpfILCop2LdTuUbcV7tLKBsthJLJ0ZCoG5QJFble+OPxEbissOvIqHfvUJZi34k9ULteLJc330g0uTuDrLgtoFQ0cbHa4F +CQ86o85EuRPpFeW6EBA3iYE/tKHSYsK7QSajefX6jZjXoZiUflw97SAGL43ZtvNbrKRywEfsVqDpDurjBg2HI+YahuDz5R1QWTSyTHWMZzcyJYqxj +XiSf0oK1cUahn6m5t1wIDAQABoyEwHzAdBgNVHQ4EFgQUlYS+xjK7KxNMf13UxMgiEssJOQkwDQYJKoZIhvcNAQELBQADggEBADkp+R6kSNXJNfih +qbDRp3uFtNMG6OgaYsfC7RtNLMdrhvoLlU7uWzxVCFuifvNlWVRiADBHDCRQU2uNRFW35GQSfHQyok4KoBuKlfBtQ+Xu7c8R0JzxN/rPJPXoCbShz +DHo1uoz5/dzXZz0EjjWCPJk+LVEhEvH0GcWAp3x3irpNU4hRZLd0XomY0Z4NnUt7VMBNYDOxVxgT9qcLnEaEpIfYULubLLCFHwAga2YgsKzZYLuwM +aEWK4zhPVFynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2Mk14gJGHUnA8= +---- + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script reverts the changes made to the `undertow` subsystem and it also removes the `ssl-context`, `key-manager`, `trust-manager` and `key-store`s +from the `elytron` subsystem. You should see the following result when you run the script: + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] + + +== Remove the keystores and certificates created for this quickstart + +. Open a terminal and navigate to the {productName} server `configuration` directory: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ cd __{jbossHomeName}__/standalone/configuration/ +---- + +. Remove the `clientCert.p12`, `client.crt`, `client.keystore`, and `client.truststore` files that +were generated for this quickstart. + +[[remove_the_client_certificate_from_your_browser]] +== Remove the Client Certificate from Your Browser + +After you are done with this quickstart, remember to remove the certificate that was imported into your browser. + +=== Remove the Client Certificate from Google Chrome + +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to chrome://settings/. +. Click on *Privacy and security* and then on *Security*. +. Scroll down to the *Advanced* section and on the *Manage certificates* screen, select the *Your Certificates* tab and click on the arrow to the right of the certificate to be removed. +. The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select *Delete*. +. Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. + +=== Remove the Client Certificate from Mozilla Firefox + +. Click the *Edit* menu item on the browser menu and choose *Preferences*. +. A new window will open. Click on *Privacy & Security* and scroll down to the *Certificates* section. +. Click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab. +. Select the `quickstartUser` certificate and click the `Delete` button. +. The certificate has now been removed from the Mozilla Firefox browser. + +// Run the Quickstart in Red Hat Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +* Make sure you configure the keystore and client certificate as described under xref:set_up_client_keystore_using_java_keytool[Set Up the Client Keystore Using Java Keytool]. +* Depending on the browser you choose, make sure you either xref:import_the_client_certificate_into_google_chrome[import the certificate into Google Chrome] or xref:import_the_client_certificate_into_mozilla_firefox[import the certificate into Mozilla Firefox]. +* Make sure you configure the server by running the JBoss CLI commands as described above under xref:configure_the_server[Configure the Server]. Stop the server at the end of that step. +* In {JBDSProductName}, choose *Window* –> *Web Browser*, then select the browser you chose to import the certificate. +* To deploy the application, right-click on the *{artifactId}* project and choose *Run As* –> *Run on Server*. +* Make sure you xref:restore_the_server_configuration[restore the server configuration] when you have completed testing this quickstart. + +== Debug the Application + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/helloworld-mutual-ssl/README.adoc b/helloworld-mutual-ssl/README.adoc index 751614a594..2df75331ff 100644 --- a/helloworld-mutual-ssl/README.adoc +++ b/helloworld-mutual-ssl/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: helloworld-mutual-ssl +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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-mutual-ssl: {productName} Mutual TLS(two-way) Configuration Example :author: Giriraj Sharma, Stefan Guilhen @@ -21,11 +218,66 @@ The out of the box configuration for {productName} has one-way TLS enabled by de Before you run this example, you must create the client certificate and configure the server to use two-way TLS. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: [[set_up_client_keystore_using_java_keytool]] == Set Up the Client Keystore Using Java Keytool @@ -101,9 +353,203 @@ $>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -des . The certificate and keystore are now properly configured. // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] @@ -207,7 +653,114 @@ Before you access the application, you must import the _clientCert.p12_, which h . The certificate is now installed in the Mozilla Firefox browser. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -233,9 +786,61 @@ aEWK4zhPVFynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9 ---- // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script reverts the changes made to the `undertow` subsystem and it also removes the `ssl-context`, `key-manager`, `trust-manager` and `key-store`s @@ -248,7 +853,84 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: == Remove the keystores and certificates created for this quickstart @@ -286,7 +968,27 @@ After you are done with this quickstart, remember to remove the certificate that . The certificate has now been removed from the Mozilla Firefox browser. // Run the Quickstart in Red Hat Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions * Make sure you configure the keystore and client certificate as described under xref:set_up_client_keystore_using_java_keytool[Set Up the Client Keystore Using Java Keytool]. @@ -314,4 +1016,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/helloworld-mutual-ssl/pom.xml b/helloworld-mutual-ssl/pom.xml index 0740336e46..7ea54a7e02 100644 --- a/helloworld-mutual-ssl/pom.xml +++ b/helloworld-mutual-ssl/pom.xml @@ -26,11 +26,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld-mutual-ssl - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: helloworld-mutual-ssl Helloworld Mutual SSL Authentication diff --git a/helloworld-singleton/README-source.adoc b/helloworld-singleton/README-source.adoc new file mode 100644 index 0000000000..2e1bbfaeb0 --- /dev/null +++ b/helloworld-singleton/README-source.adoc @@ -0,0 +1,53 @@ +include::../shared-doc/attributes.adoc[] + += helloworld-singleton: Helloworld Using a Singleton EJB +:author: Serge Pagop +:level: Beginner +:technologies: EJB, Singleton +:openshift: true + +[abstract] +The `helloworld-singleton` quickstart demonstrates an EJB Singleton Bean that is instantiated once and maintains state for the life of the session. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `helloworld-singleton` quickstart demonstrates the use of an EJB Singleton Bean in {productNameFull}. It is instantiated once and maintains its state for the life of the session. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +This example demonstrates a singleton session bean that maintains state information for 2 variables: `Increment A` and `Increment B`. + +A counter is incremented when you click on the link to the variable name. If you close and restart your browser, or if you have multiple browsers, you can see that the counter always increments the last value. These values are maintained until you restart the server. + +To test the singleton bean, click on either *Increment A* or *Increment B*. The result page will give you the current value of the variable. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/helloworld-singleton/README.adoc b/helloworld-singleton/README.adoc index 0cf299d32f..3497fb62ac 100644 --- a/helloworld-singleton/README.adoc +++ b/helloworld-singleton/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: helloworld-singleton +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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-singleton: Helloworld Using a Singleton EJB :author: Serge Pagop @@ -18,19 +215,295 @@ The `helloworld-singleton` quickstart demonstrates an EJB Singleton Bean that is The `helloworld-singleton` quickstart demonstrates the use of an EJB Singleton Bean in {productNameFull}. It is instantiated once and maintains its state for the life of the session. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -43,12 +516,625 @@ A counter is incremented when you click on the link to the variable name. If you To test the singleton bean, click on either *Increment A* or *Increment B*. The result page will give you the current value of the variable. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + contextDir: helloworld-singleton +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/helloworld-singleton/charts/helm.yaml b/helloworld-singleton/charts/helm.yaml index c3dda38fcd..3cef659fe2 100644 --- a/helloworld-singleton/charts/helm.yaml +++ b/helloworld-singleton/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: helloworld-singleton deploy: replicas: 1 \ No newline at end of file diff --git a/helloworld-singleton/pom.xml b/helloworld-singleton/pom.xml index a90be92804..2d295bff84 100644 --- a/helloworld-singleton/pom.xml +++ b/helloworld-singleton/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld-singleton - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: helloworld-singleton This project demonstrates a Hello World Singleton Session Bean with a JSF client @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/helloworld-ws/README-source.adoc b/helloworld-ws/README-source.adoc new file mode 100644 index 0000000000..541e80271c --- /dev/null +++ b/helloworld-ws/README-source.adoc @@ -0,0 +1,59 @@ +include::../shared-doc/attributes.adoc[] + += helloworld-ws: Hello World JAX-WS Web Service +:author: Lee Newson +:level: Beginner +:technologies: JAX-WS +:openshift: true + +[abstract] +The `helloworld-ws` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-WS to say Hello. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `helloworld-ws` quickstart demonstrates the use of JAX-WS in {productNameFull} as a simple Hello World application. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +Review the server log to see useful information about the deployed web service endpoint. + +[source,options="nowrap"] +---- +JBWS024061: Adding service endpoint metadata: id=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl + address=http://localhost:8080/HelloWorldService + implementor=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl + serviceName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorldService + portName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorld + annotationWsdlLocation=null + wsdlLocationOverride=null + mtomEnabled=false +---- + +=== Access the Application + +You can verify that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/HelloWorldService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service. + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/helloworld-ws/README.adoc b/helloworld-ws/README.adoc index bb3037832c..a3abcf4605 100644 --- a/helloworld-ws/README.adoc +++ b/helloworld-ws/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: helloworld-ws +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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-ws: Hello World JAX-WS Web Service :author: Lee Newson @@ -18,19 +215,295 @@ The `helloworld-ws` quickstart demonstrates a simple Hello World application, bu The `helloworld-ws` quickstart demonstrates the use of JAX-WS in {productNameFull} as a simple Hello World application. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: Review the server log to see useful information about the deployed web service endpoint. @@ -51,10 +524,599 @@ JBWS024061: Adding service endpoint metadata: id=org.jboss.as.quickstarts.wshell You can verify that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/HelloWorldService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service. // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file + +// 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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: helloworld-ws +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/helloworld-ws/charts/helm.yaml b/helloworld-ws/charts/helm.yaml index 86e1ccf577..b4ba05e719 100644 --- a/helloworld-ws/charts/helm.yaml +++ b/helloworld-ws/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: helloworld-ws deploy: replicas: 1 \ No newline at end of file diff --git a/helloworld-ws/pom.xml b/helloworld-ws/pom.xml index 1c4c168271..0e07d4121e 100644 --- a/helloworld-ws/pom.xml +++ b/helloworld-ws/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld-ws - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: helloworld-ws This project demonstrates a Hello World JAX-WS web service @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/helloworld/README-source.adoc b/helloworld/README-source.adoc new file mode 100644 index 0000000000..3ee136f9bd --- /dev/null +++ b/helloworld/README-source.adoc @@ -0,0 +1,46 @@ +include::../shared-doc/attributes.adoc[] + += 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 +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/helloworld/README.adoc b/helloworld/README.adoc index 8e8e2efe2b..268bab533d 100644 --- a/helloworld/README.adoc +++ b/helloworld/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 @@ -18,30 +215,919 @@ The `helloworld` quickstart demonstrates the use of Servlet 6 and is a good star The `helloworld` quickstart demonstrates the use of _Servlet 6_ in {productNameFull} {productVersion}. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application The application will be running at the following URL: http://localhost:8080/{artifactId}/. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + 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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/helloworld/charts/helm.yaml b/helloworld/charts/helm.yaml index cf70083673..7cb8467697 100644 --- a/helloworld/charts/helm.yaml +++ b/helloworld/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: helloworld deploy: replicas: 1 \ No newline at end of file diff --git a/helloworld/pom.xml b/helloworld/pom.xml index 8ede3df4de..7ce98f64a1 100644 --- a/helloworld/pom.xml +++ b/helloworld/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 helloworld - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: helloworld Helloworld @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/hibernate/README-source.adoc b/hibernate/README-source.adoc new file mode 100644 index 0000000000..e6c9fe1fc2 --- /dev/null +++ b/hibernate/README-source.adoc @@ -0,0 +1,142 @@ +include::../shared-doc/attributes.adoc[] + += hibernate: How to Use Hibernate in an Application +:author: Madhumita Sadhukhan +:level: Intermediate +:technologies: Hibernate +:openshift: true + +[abstract] +The `hibernate` quickstart demonstrates how to use Hibernate ORM 6 over Persistence, using Bean Validation, and Enterprise Beans. + +:standalone-server-type: default +:archiveType: war +:uses-h2: +:restoreScriptName: restore-configuration.cli + +== What is it? + +The `hibernate` quickstart is based upon the link:../kitchensink/README{outfilesuffix}[kitchensink] example, but demonstrates how to use Hibernate Object/Relational Mapping (ORM) over Persistence in {productNameFull}. + +This project is setup to allow you to create a compliant {javaVersion} application using Faces, Contexts and Dependency Injection, Enterprise Beans, Persistence, Hibernate ORM and Bean Validation. It includes a persistence unit, Persistence use to help you with database access. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Add the Correct Dependencies + +{productName} provides Hibernate 6 and Persistence support. + +If you use Hibernate 6 packaged within {productName}, you will need to first import the Persistence API. + +This quickstart demonstrates usage of Persistence and Bean Validation. + +If you look at the `pom.xml` file in the root of the hibernate quickstart directory, you will see that the dependencies for the Hibernate modules have been added with the scope as `provided`. + +For example: +[source,xml,options="nowrap"] +---- + + org.hibernate.validator + hibernate-validator + provided + +---- + +// 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 +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] + +[[configure_the_server]] +=== Configure the Server + +You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds datasource required for this quickstart. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following datasource was added to the `datasources` subsystem. ++ +[source,xml,options="nowrap"] +---- + + jdbc:h2:mem:hibernate-quickstart;DB_CLOSE_ON_EXIT=FALSE;DB_CLOSE_DELAY=-1 + h2 + + sa + sa + + +---- + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] + +// Additional information about this script +This script removes the datasource used for this quickstart. You should see the following result when you run the script: + + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] diff --git a/hibernate/README.adoc b/hibernate/README.adoc index 6cd4095312..0a5f3a79f4 100644 --- a/hibernate/README.adoc +++ b/hibernate/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: hibernate +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = hibernate: How to Use Hibernate in an Application :author: Madhumita Sadhukhan @@ -22,13 +219,97 @@ The `hibernate` quickstart is based upon the link:../kitchensink/README{outfiles This project is setup to allow you to create a compliant {javaVersion} application using Faces, Contexts and Dependency Injection, Enterprise Beans, Persistence, Hibernate ORM and Bean Validation. It includes a persistence unit, Persistence use to help you with database access. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Add the Correct Dependencies @@ -54,9 +335,203 @@ For example: [[build_and_run_the_quickstart_with_server_dist]] == Building and running the quickstart application with a {productName} server distribution // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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!: [[configure_the_server]] === Configure the Server @@ -109,19 +584,202 @@ After stopping the server, open the `__{jbossHomeName}__/standalone/configuratio ---- // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application The application will be running at the following URL: http://localhost:8080/{artifactId}/. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script removes the datasource used for this quickstart. You should see the following result when you run the script: @@ -134,10 +792,657 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] +:leveloffset: +3 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +[[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: 31.x + contextDir: hibernate +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/hibernate/charts/helm.yaml b/hibernate/charts/helm.yaml index fa78d17df7..2ce204cc81 100644 --- a/hibernate/charts/helm.yaml +++ b/hibernate/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: hibernate deploy: replicas: 1 \ No newline at end of file diff --git a/hibernate/pom.xml b/hibernate/pom.xml index 159e5cf8ef..2fb85c5327 100644 --- a/hibernate/pom.xml +++ b/hibernate/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 hibernate - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: hibernate This project demonstrates how to use Hibernate ORM @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/http-custom-mechanism/README-source.adoc b/http-custom-mechanism/README-source.adoc new file mode 100644 index 0000000000..0544977175 --- /dev/null +++ b/http-custom-mechanism/README-source.adoc @@ -0,0 +1,244 @@ +include::../shared-doc/attributes.adoc[] + += http-custom-mechanism: Create a custom HTTP authorization mechanism +:author: Darran Lofthouse +:level: Intermediate +:technologies: EJB, Security + +[abstract] +The `http-custom-mechanism` quickstart demonstrates how to implement a custom HTTP authentication mechanism that can be registered with Elytron. + +:standalone-server-type: default +:archiveType: war +:archiveName: {artifactId}-webapp +:app-user-groups: Users +:deploymentDir: webapp + +== What is it? + +The `http-custom-mechanism` quickstart demonstrates how to implement a custom HTTP mechanism and then register it with Elytron. This makes it possible to override the configuration within the deployment to make use of this mechanism without requiring modifications to the deployment. This example makes use of custom HTTP headers to receive a clear text `username` and `password` and use them for authentication. + +WARNING: Generally you should avoid passing clear text passwords. It is only done here to simplify the example. + +This example consists of the following Maven projects. + +[cols="20%,80%",options="headers"] +|=== +|Project |Description + +| `webapp` +a| The project in the `webapp/` folder contains a deployable web application consisting of a secured servlet that is used to test the configuration. It generates the `{archiveName}.war` archive that is used to test the secured application. + +| `custom-module` +a| This project contains the source for a custom HTTP authentication module that overrides the deployment configuration. It contains of the following Java classes and resources. + +* `CustomMechanismFactory`: This class implements `HttpServerAuthenticationMechanismFactory` and creates the new custom `HttpServerAuthenticationMechanism`. +* `CustomHeaderHttpAuthenticationMechanism`: This class implements `HttpServerAuthenticationMechanism` and contains the source code for the custom mechanism processing. An `HttpServerRequest` object is passed to the `evaluateRequest` method. The mechanism processes the requests and uses one of the following callback methods on the request to indicate the outcome: + +** `authenticationComplete` - The mechanism successfully authenticated the request. +** `authenticationFailed` - Authentication was attempted but failed. +** `authenticationInProgress` - Authentication started but an additional round trip is needed. +** `badRequest` - The authentication for this mechanism failed validation of the request. +** `noAuthenticationInProgress` - The mechanism did not attempt any stage of authentication. + +* `org.wildfly.security.examples.CustomMechanismFactory`: This resource file contains a single line of text that names the custom mechanism factory class, which in this case is `org.jboss.as.quickstart.http_custom_mechanism.CustomMechanismFactory`. +|=== + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] + +include::../shared-doc/add-application-user.adoc[leveloffset=+2] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +[[test_the_secured_servlet]] +=== Test the Secured Servlet + +Before you continue, you must test the secured servlet deployment to make sure it is working. Since this application uses a standard mechanism, it could be tested using a browser. However, after you implement the custom HTTP mechanism, the browser will not understand the request, so it is better to test the call using a client that will allow you to manipulate the headers yourself. + +Issue the following command to test the deployment. + +[source,options="nowrap"] +---- +curl -v http://localhost:8080/http-custom-mechanism-webapp/secured -u quickstartUser:quickstartPwd1! +---- + +You should see the HTTP result `HTTP/1.1 200 OK`, along with some header information, then followed by this output. + +[source,xml,options="nowrap"] +---- + + Secured Servlet + +

Secured Servlet

+

Current Principal 'quickstartUser'

+ + +---- + +[[add_the_custom_module_to_the_server]] +=== Add the Custom Module to the Server + +Now you must add the jar built by `custom-module`, as a custom module to the {productName} server. For your convenience, this quickstart includes the command to add the module in the `add-custom-module.cli` script, provided in the root directory of this quickstart. + +In a terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=add-custom-module.cli +---- + +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +This creates the custom `__{jbossHomeName}__/modules/modules/org/jboss/as/quickstart/http_custom_mechanism/main` folder, then copies in the `custom-module/target/custom-module.jar` file and creates the required `module.xml` file. + +You can verify the module structure in your file manager. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +. +└── __{jbossHomeName}__ + └── modules + └── org + └── jboss + └── as + └── quickstart + └── http_custom_mechanism + └── main + ├── custom-module.jar + └── module.xml +---- + +[[configure_the_server_to_use_the_custom_module]] +=== Configure the Server to Use the Custom Module + +You configure the server to use the custom module by running CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script, provided in the root directory of this quickstart. + +. Before you begin, make sure you have done the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security to use the custom HTTP module created by this quickstart . Comments in the script describe the purpose of each block of commands. +. 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. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. Stop the {productName} server. + +[[review_the_modified_server_configuration]] +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following `service-loader-http-server-mechanism-factory` was added to the `http` element of the `elytron` subsystem: ++ +[source,xml,options="nowrap"] +---- + + + + + + + ... + + +---- + +. The `application-security-domain` in the `undertow` subsystem was updated to use the `custom-mechanism` authentication factory with `override-deployment-config` set to `true`. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +[[test_the_secured_servlet_using_the_custom_mechnism]] +== Test the Secured Servlet Using the Custom Mechanism + +Now you need to test the override of the deployment with the custom HTTP mechanism, please start the server as previously described. + +If you use the same `curl` command as when you xref:test_the_secured_servlet[tested the servlet before implementing the custom HTTP mechanism], it will fail with the following error. +[source,options="nowrap"] +---- +< HTTP/1.1 401 Unauthorized +.... +< X-MESSAGE: Please resubmit the request with a username specified using the X-USERNAME and a password specified using the X-PASSWORD header. +---- + +This is because the authentication mechanism rejected the call and subsequently added a header describing how to do authentication. You must modify the curl command to the following. + +[source,options="nowrap"] +---- +curl -v http://localhost:8080/http-custom-mechanism-webapp/secured -H "X-USERNAME:quickstartUser" -H "X-PASSWORD:password" +---- + +You should see the HTTP result `HTTP/1.1 200 OK`, along with some header information, then followed by this output. + +[source,xml,options="nowrap"] +---- + + Secured Servlet + +

Secured Servlet

+

Current Principal 'quickstartUser'

+ + +---- + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration Manually +:restoreScriptName: restore-configuration.cli +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] + +// Additional information about this script +This script reverts the changes made to the `undertow` and `elytron` subsystems. You should see the following result when you run the script. + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file diff --git a/http-custom-mechanism/README.adoc b/http-custom-mechanism/README.adoc index 7e5fd2b0cd..2bb16ce205 100644 --- a/http-custom-mechanism/README.adoc +++ b/http-custom-mechanism/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: http-custom-mechanism +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = http-custom-mechanism: Create a custom HTTP authorization mechanism :author: Darran Lofthouse @@ -46,26 +243,422 @@ a| This project contains the source for a custom HTTP authentication module that |=== // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: + +:leveloffset: +2 + +[[add_the_application_user]] += Add the Authorized Application User + +// Note: The group ID syntax must be defined in the calling topic. +// using the document attribute :app-user-groups: +// Use a comma-delimited list to define more than one group. +// +// :app-user-groups: guest, users + +ifdef::app-user-groups[] +:app-group-list: {app-user-groups} +:app-group-command: -g '{app-user-groups}' +endif::app-user-groups[] + +ifndef::app-user-groups[] +:app-group-list: +:app-group-command: +endif::app-user-groups[] + +// attr which other sections may check (ifdef) to know if users needs to be added +:addQuickstartUser: true -include::../shared-doc/add-application-user.adoc[leveloffset=+2] +This quickstart uses secured application interfaces and requires that you create the following application user to access the running application. + +[cols="20%,20%,20%,40%",options="headers"] +|=== +|UserName |Realm |Password |Roles + +|quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} +|=== + +To add the application user, open a terminal and type the following command: +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} +---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: [[test_the_secured_servlet]] === Test the Secured Servlet @@ -219,10 +812,106 @@ You should see the HTTP result `HTTP/1.1 200 OK`, along with some header informa ---- // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration Manually :restoreScriptName: restore-configuration.cli -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Additional information about this script This script reverts the changes made to the `undertow` and `elytron` subsystems. You should see the following result when you run the script. @@ -234,12 +923,355 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] // Quickstart not compatible with OpenShift -include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] \ No newline at end of file +:leveloffset: +1 + +[[openshift_incompatibility]] += {xpaasproduct-shortname} Incompatibility + +This quickstart is not compatible with {xpaasproduct-shortname} or {xpaasproductOpenShiftOnline-shortname} templates. + +:leveloffset!: diff --git a/http-custom-mechanism/custom-module/pom.xml b/http-custom-mechanism/custom-module/pom.xml index fddaa72fa3..3160e3b433 100644 --- a/http-custom-mechanism/custom-module/pom.xml +++ b/http-custom-mechanism/custom-module/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts http-custom-mechanism - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ../pom.xml diff --git a/http-custom-mechanism/pom.xml b/http-custom-mechanism/pom.xml index 0c2853766f..c6a99ca416 100644 --- a/http-custom-mechanism/pom.xml +++ b/http-custom-mechanism/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 http-custom-mechanism - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom Quickstart: http-custom-mechanism This project demonstrates how to implement a custom HTTP authentication mechanism @@ -50,7 +50,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/http-custom-mechanism/webapp/pom.xml b/http-custom-mechanism/webapp/pom.xml index b6025587a4..39d70f6c8f 100644 --- a/http-custom-mechanism/webapp/pom.xml +++ b/http-custom-mechanism/webapp/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts http-custom-mechanism - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ../pom.xml http-custom-mechanism-webapp diff --git a/jaxrs-client/README-source.adoc b/jaxrs-client/README-source.adoc new file mode 100644 index 0000000000..cc5bf16906 --- /dev/null +++ b/jaxrs-client/README-source.adoc @@ -0,0 +1,68 @@ +include::../shared-doc/attributes.adoc[] + += jaxrs-client: Jakarta REST Client API example +:author: Rafael Benevides +:level: Beginner +:technologies: JAX-RS +:openshift: true + +[abstract] +The `jaxrs-client` quickstart demonstrates Jakarta REST Client API, which interacts with a Jakarta REST Web service that runs on {productName}. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `jaxrs-client` quickstart demonstrates the Jakarta REST Client API which interacts with a Jakarta REST Web service. + +This client tests "call" many `POST`, `GET`, and `DELETE` operations using different ways: synchronized, asynchronous, +delayed and filtered invocations. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +=== Investigate the Console Output + +When you run the integration tests, Maven prints summary of the performed tests to the console. You should see the following results. + +[source,options="nowrap"] +---- +[INFO] ------------------------------------------------------- +[INFO] T E S T S +[INFO] ------------------------------------------------------- +[INFO] Running org.jboss.as.quickstarts.jaxrsclient.test.InvocationContactsRestClientIT +[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.42 s - in org.jboss.as.quickstarts.jaxrsclient.test.InvocationContactsRestClientIT +[INFO] Running org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientIT +[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.047 s - in org.jboss.as.quickstarts.jaxrsclient.test.ContactsRestClientIT +[INFO] Running org.jboss.as.quickstarts.jaxrsclient.test.FilteredContactsRestClientIT +[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.052 s - in org.jboss.as.quickstarts.jaxrsclient.test.FilteredContactsRestClientIT +[INFO] Running org.jboss.as.quickstarts.jaxrsclient.test.AsyncContactsRestClientIT +[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.064 s - in org.jboss.as.quickstarts.jaxrsclient.test.AsyncContactsRestClientIT +[INFO] +[INFO] Results: +[INFO] +[INFO] Tests run: 20, Failures: 0, Errors: 0, Skipped: 0 +---- + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] diff --git a/jaxrs-client/README.adoc b/jaxrs-client/README.adoc index 1bbdbbe7cb..f1ddfce6b2 100644 --- a/jaxrs-client/README.adoc +++ b/jaxrs-client/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jaxrs-client +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jaxrs-client: Jakarta REST Client API example :author: Rafael Benevides @@ -21,23 +218,342 @@ This client tests "call" many `POST`, `GET`, and `DELETE` operations using diffe delayed and filtered invocations. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: === Investigate the Console Output @@ -64,6 +580,576 @@ When you run the integration tests, Maven prints summary of the performed tests // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: jaxrs-client +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/jaxrs-client/charts/helm.yaml b/jaxrs-client/charts/helm.yaml index 3e17b4ab5f..97dc121bb6 100644 --- a/jaxrs-client/charts/helm.yaml +++ b/jaxrs-client/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: jaxrs-client deploy: replicas: 1 \ No newline at end of file diff --git a/jaxrs-client/pom.xml b/jaxrs-client/pom.xml index 5e514cf5c3..3b2323e20a 100644 --- a/jaxrs-client/pom.xml +++ b/jaxrs-client/pom.xml @@ -26,11 +26,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jaxrs-client - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: jaxrs-client A JAX-RS Client API project @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/jaxrs-jwt/README-source.adoc b/jaxrs-jwt/README-source.adoc new file mode 100644 index 0000000000..d543ddfc46 --- /dev/null +++ b/jaxrs-jwt/README-source.adoc @@ -0,0 +1,154 @@ +include::../shared-doc/attributes.adoc[] + += jaxrs-jwt: Jakarta REST secured using JSON Web Tokens (JWTs) +:author: Martin Mazanek +:level: Intermediate +:technologies: JAX-RS, Security + +[abstract] +The `jaxrs-jwt` quickstart demonstrates a Jakarta REST secured application using JSON Web Tokens (JWT) with Elytron. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +This quickstart demonstrates how to secure a Jakarta REST service with JWTs using the Elytron subsystem. + +There are 4 resource endpoints, plus another one for generating JWTs. + +* `/rest/public` - Requires no authentication. +* `/rest/customer` - Can be accessed by users with `customer` role authority. +* `/rest/admin` - Can be accessed by users with `admin` role authority. +* `/rest/claims` - Can be accessed by any authenticated user and demonstrates how to extract token claims. +* `/rest/token` - `POST` endpoint for generating tokens from provided credentials. + +NOTE: This quickstart asserts only few JWT claims for demonstration purposes. In your application, you should use all claims required by the specification you are using. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart deployment. Comments in the script describe the purpose of each block of commands. ++ +IMPORTANT: This script contains placeholder PEM public key to make the deployment of this quickstart easy. DO _not_ use this key for anything but testing purposes! You must generate your own key pair for your own application. + +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following `token-realm` was added to the `security-realms` element in the `elytron` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + +---- +. The following `security-domain` was added, which uses the `jwt-realm`. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +. The following HTTP authentication factory was added, which uses `BEARER_TOKEN` and the `jwt-realm`. ++ +[source,xml,options="nowrap"] +---- + + + + + + + +---- + +. The application security domain in the Undertow subsystem is configured to use the new HTTP authentication factory. ++ +[source,xml,options="nowrap"] +---- + + + + +---- + +. Finally, the application security domain in the EJB subsystem is configured to use the `jwt-domain`. ++ +[source,xml,options="nowrap"] +---- + + + + +---- + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +[[access_the_application]] +== Access the Application + +The `JwtAuthIT` test shows how a client can authenticate with the server. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Restore the {productName} Standalone Server Configuration +:restoreScriptName: restore-configuration.cli +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script reverts the changes made to the `undertow` and `elytron` subsystem.You should see the following result when you run the script. + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/jaxrs-jwt/README.adoc b/jaxrs-jwt/README.adoc index 21b74b2f39..179699b92c 100644 --- a/jaxrs-jwt/README.adoc +++ b/jaxrs-jwt/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jaxrs-jwt +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jaxrs-jwt: Jakarta REST secured using JSON Web Tokens (JWTs) :author: Martin Mazanek @@ -27,16 +224,265 @@ There are 4 resource endpoints, plus another one for generating JWTs. NOTE: This quickstart asserts only few JWT claims for demonstration purposes. In your application, you should use all claims required by the specification you are using. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -119,7 +565,114 @@ After stopping the server, open the `__{jbossHomeName}__/standalone/configuratio ---- // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: [[access_the_application]] == Access the Application @@ -127,12 +680,88 @@ include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] The `JwtAuthIT` test shows how a client can authenticate with the server. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration :restoreScriptName: restore-configuration.cli -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script reverts the changes made to the `undertow` and `elytron` subsystem.You should see the following result when you run the script. @@ -144,12 +773,680 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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] +---- +Unresolved directive in ../shared-doc/helm-deploy-project.adoc - include::/home/runner/work/quickstart/quickstart/jaxrs-jwt/charts/helm.yaml[] +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/jaxrs-jwt/pom.xml b/jaxrs-jwt/pom.xml index 5ad46d28b4..84c30eb211 100644 --- a/jaxrs-jwt/pom.xml +++ b/jaxrs-jwt/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jaxrs-jwt - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: jaxrs-jwt JWT authentication using Elytron @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/jaxrs-jwt/src/charts/helm.yaml b/jaxrs-jwt/src/charts/helm.yaml index d9c4d656db..7049e1f802 100644 --- a/jaxrs-jwt/src/charts/helm.yaml +++ b/jaxrs-jwt/src/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: jaxrs-jwt deploy: replicas: 1 \ No newline at end of file diff --git a/jaxws-ejb/README-source.adoc b/jaxws-ejb/README-source.adoc new file mode 100644 index 0000000000..efd4e03e4e --- /dev/null +++ b/jaxws-ejb/README-source.adoc @@ -0,0 +1,51 @@ +include::../shared-doc/attributes.adoc[] + += jaxws-ejb: An EJB JAX-WS Web Service +:author: R Searls +:level: Beginner +:technologies: JAX-WS + +[abstract] +The `jaxws-ejb` quickstart is a working example of the web service endpoint created from an EJB. + +:standalone-server-type: default +:archiveType: war +// Override the archive directory +:archiveDir: {artifactId}/target +// Override the archive name +:archiveName: {artifactId} + +== What is it? + +The `jaxws-ejb` quickstart demonstrates the use of _JAX-WS_ in {productNameFull} as a simple EJB web service application. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +== Access the Application + +You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/EJB3Bean?wsdl. +This URL will display the deployed WSDL endpoint for the Web Service. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/jaxws-ejb/README.adoc b/jaxws-ejb/README.adoc index 9b87618fa1..1a0134e0aa 100644 --- a/jaxws-ejb/README.adoc +++ b/jaxws-ejb/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jaxws-ejb +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jaxws-ejb: An EJB JAX-WS Web Service :author: R Searls @@ -21,19 +218,295 @@ The `jaxws-ejb` quickstart is a working example of the web service endpoint crea The `jaxws-ejb` quickstart demonstrates the use of _JAX-WS_ in {productNameFull} as a simple EJB web service application. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -41,12 +514,625 @@ You can check that the Web Service is running and deployed correctly by accessin This URL will display the deployed WSDL endpoint for the Web Service. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: jaxws-ejb +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/jaxws-ejb/charts/helm.yaml b/jaxws-ejb/charts/helm.yaml index fb4da91070..2903677ac3 100644 --- a/jaxws-ejb/charts/helm.yaml +++ b/jaxws-ejb/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: jaxws-ejb deploy: replicas: 1 \ No newline at end of file diff --git a/jaxws-ejb/pom.xml b/jaxws-ejb/pom.xml index 3e849d5501..38120b6cf5 100644 --- a/jaxws-ejb/pom.xml +++ b/jaxws-ejb/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jaxws-ejb - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: jaxws-ejb This project is a working example of a JAX-WS web service EJB endpoint @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/jaxws-retail/README-source.adoc b/jaxws-retail/README-source.adoc new file mode 100644 index 0000000000..03e2dc9d55 --- /dev/null +++ b/jaxws-retail/README-source.adoc @@ -0,0 +1,48 @@ +include::../shared-doc/attributes.adoc[] + += jaxws-retail: A Retail JAX-WS Web Service +:author: R Searls +:level: Beginner +:technologies: JAX-WS + +[abstract] +The `jaxws-retail` quickstart is a working example of a simple web service endpoint. + +:standalone-server-type: default +:archiveType: war +// Override the archive directory +:archiveDir: {artifactId}/target +// Override the archive name +:archiveName: {artifactId} + +== What is it? + +The `jaxws-retail` quickstart demonstrates the use of _JAX-WS_ in {productNameFull} as a simple profile management application. It also demonstrates usage of wsconsume to generate classes from WSDL file. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + + +== Access the Application + +You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/{artifactId}/ProfileMgmtService/ProfileMgmt?wsdl. This URL will display the deployed WSDL endpoint for the Web Service. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/jaxws-retail/README.adoc b/jaxws-retail/README.adoc index 24a5279bbe..f467d17a6b 100644 --- a/jaxws-retail/README.adoc +++ b/jaxws-retail/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jaxws-retail +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jaxws-retail: A Retail JAX-WS Web Service :author: R Searls @@ -21,16 +218,292 @@ The `jaxws-retail` quickstart is a working example of a simple web service endpo The `jaxws-retail` quickstart demonstrates the use of _JAX-WS_ in {productNameFull} as a simple profile management application. It also demonstrates usage of wsconsume to generate classes from WSDL file. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -38,12 +511,625 @@ include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] You can check that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/{artifactId}/ProfileMgmtService/ProfileMgmt?wsdl. This URL will display the deployed WSDL endpoint for the Web Service. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: jaxws-retail +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/jaxws-retail/charts/helm.yaml b/jaxws-retail/charts/helm.yaml index 110f339a2d..a65b34904e 100644 --- a/jaxws-retail/charts/helm.yaml +++ b/jaxws-retail/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: jaxws-retail deploy: replicas: 1 \ No newline at end of file diff --git a/jaxws-retail/pom.xml b/jaxws-retail/pom.xml index 7906e79d8b..a9da61e136 100644 --- a/jaxws-retail/pom.xml +++ b/jaxws-retail/pom.xml @@ -25,7 +25,7 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jaxws-retail @@ -43,7 +43,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/jsonp/README-source.adoc b/jsonp/README-source.adoc new file mode 100644 index 0000000000..f74ae52a82 --- /dev/null +++ b/jsonp/README-source.adoc @@ -0,0 +1,53 @@ +include::../shared-doc/attributes.adoc[] + += jsonp: JSON-P Object-based JSON generation and Stream-based JSON consuming +:author: Rafael Benevides +:level: Beginner +:technologies: CDI, JSF, JSON-P +:openshift: true + +[abstract] +The `jsonp` quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `jsonp` quickstart creates a JSON string through object-based JSON generation and then parses and consumes it using stream-based JSON. + +It shows how to use the JSON-P API to generate, parse, and consume JSON files. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +== Access the Application + +Access the running application in a browser at the following URL: http://localhost:8080/{artifactId}/ + +. You are presented with a simple form that is pre-filled with personal data. You can change those values if you prefer. + +. Click on the *Generate JSON String from Personal Data* button. The text area below the button presents a JSON string representing the data and values from the completed form. ++ +Note that the JSON string contains String, number, boolean and array values. + +. Now, click on the *Parse JSON String using Stream* button. The text area below the button shows the events generated from the parsed JSON string. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/jsonp/README.adoc b/jsonp/README.adoc index c7ea1b6218..64207ee895 100644 --- a/jsonp/README.adoc +++ b/jsonp/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jsonp +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jsonp: JSON-P Object-based JSON generation and Stream-based JSON consuming :author: Rafael Benevides @@ -20,15 +217,242 @@ The `jsonp` quickstart creates a JSON string through object-based JSON generatio It shows how to use the JSON-P API to generate, parse, and consume JSON files. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -43,12 +467,625 @@ Note that the JSON string contains String, number, boolean and array values. . Now, click on the *Parse JSON String using Stream* button. The text area below the button shows the events generated from the parsed JSON string. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: jsonp +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/jsonp/charts/helm.yaml b/jsonp/charts/helm.yaml index ff181f49c8..fbff6cd6f9 100644 --- a/jsonp/charts/helm.yaml +++ b/jsonp/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: jsonp deploy: replicas: 1 \ No newline at end of file diff --git a/jsonp/pom.xml b/jsonp/pom.xml index e298608512..50853c0c43 100644 --- a/jsonp/pom.xml +++ b/jsonp/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jsonp - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: jsonp A starter Jakarta EE webapp project for use on JBoss EAP @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/jta-crash-rec/README-source.adoc b/jta-crash-rec/README-source.adoc new file mode 100644 index 0000000000..50c13fa822 --- /dev/null +++ b/jta-crash-rec/README-source.adoc @@ -0,0 +1,205 @@ +include::../shared-doc/attributes.adoc[] + += jta-crash-rec: Example of JTA Crash Recovery +:author: Mike Musgrove +:level: Advanced +:technologies: JTA, Crash Recovery + +[abstract] +The `jta-crash-rec` quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash. + +:standalone-server-type: full +:archiveType: war +:uses-h2: +:uses-ds-xml: + +== What is it? + +The `jta-crash-rec` quickstart demonstrates how to code distributed or XA (eXtended Architecture) transactions so that the ACID properties are preserved across participating resources deployed to {productNameFull} after a server crash. An XA transaction is one in which multiple resources, such as MDBs and databases, participate within the same transaction. It ensures all operations are performed as a single entity of work. ACID is a set of 4 properties that guarantee the resources are processed in the following manner: + +* Atomic - if any part of the transaction fails, all resources remain unchanged. +* Consistent - the state will be consistent across resources after a commit +* Isolated - the execution of the transaction for each resource is isolated from each others +* Durable - the data will persist after the transaction is committed + +This quickstart shows how to atomically update multiple resources within one transaction. It updates a relational database table using JPA and sends a message using JMS. This type of paired updates to two different resources are called XA transactions and are defined by the Jakarta EE JTA specification JSR-907. + +The relational database table in this example contains two columns that represent a `key` / `value` pair. The application presents an HTML form containing two input text boxes and allows you to create, update, delete or list these pairs. When you add or update a `key` / `value` pair, the quickstart starts a transaction, updates the database table, produces a JMS message containing the update, and then commits the transaction. If all goes well, eventually the consumer gets the message and generates a database update, setting the `value` corresponding to the `key` to something that indicates it was changed by the message consumer. + +In this example, you halt the {productName} server in the middle of an XA transaction after the database modification has been committed, but before the JMS producer is committed. You can verify that the transaction was started, then restart the {productName} server to complete the transaction. You then verify that everything is in a consistent state. + +{productName} ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the `jta-crash-rec-ds.xml` file in the WEB-INF folder of the WAR archive. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Download and Configure Byteman + +This quickstart uses _Byteman_ to help demonstrate crash recovery. You can find more information about _Byteman_ here: link:{configureBytemanQuickstartsDocUrl}[Configure Byteman for Use with the Quickstarts] + +Follow the instructions here to download and configure _Byteman_: link:{configureBytemanDownloadDocUrl}[Download and Configure Byteman] + +== Configure the Server + +_NOTE_: The _Byteman_ scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the {productName} server before making the following changes. Otherwise _Byteman_ will not halt the server. + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/XA. + +== Test the Application + +. When you access the application, you will find a web page containing two html input boxes for adding `key` / `value` pairs to a database. Instructions for using the application are shown at the top of the application web page. + +. When you add a new `key` / `value` pair, the change is committed to the database and a JMS message sent. The message consumer then updates the newly inserted row by appending the text `updated via JMS` to the value. Since the consumer updates the row asynchronously, you may need to click _Refresh Table_ to see the text added to the `key` / `value` pair you previously entered. + +. When an _XA transaction_ is committed, the application server completes the transaction in two phases. + +** In phase 1 each of the resources, in this example the database and the JMS message producer, are asked to prepare to commit any changes made during the transaction. +** If all resources vote to commit then the application server starts phase 2 in which it tells each resource to commit those changes. +** The added complexity is to cope with failures, especially failures that occur during phase 2. Some failure modes require cooperation between the application server and the resources in order to guarantee that any pending changes are recovered. + +. To demonstrate XA recovery, you must enable the Byteman tool to terminate the application server while _phase 2_ is running as follows: + +** Stop the {productName} server. +** Follow the instructions here to clear the transaction objectstore remaining from any previous tests: link:{configureBytemanClearDocUrl}[Clear the Transaction ObjectStore] +** The following line of text must be appended to the server configuration file using the instructions located here: link:{configureBytemanHaltDocUrl}[Use Byteman to Halt the Application] ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +JAVA_OPTS="-javaagent:/__BYTEMAN_HOME__/lib/byteman.jar=script:/__QUICKSTART_HOME__/jta-crash-rec/src/main/scripts/xa.btm ${JAVA_OPTS}" +---- ++ +[NOTE] +==== +For Windows, append the following line. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +`JAVA_OPTS=%JAVA_OPTS% -javaagent:C:__BYTEMAN_HOME__\lib\byteman.jar=script:C:\__QUICKSTART_HOME__\jta-crash-rec\src\main\scripts\xa.btm %JAVA_OPTS%`` +---- +==== + +** xref:start_the_eap_standalone_server[Start the {productName} server] with the standalone full profile as described above. + +. Once you complete step 4, you are ready to create a _recovery record_. Go to the application URL http://localhost:8080/{artifactId}/XA and insert another row into the database. At this point, Byteman halts the application server. + +. If you want to verify the database insert was committed but that message delivery is still pending, you can use an SQL client such as the H2 database console tool. Issue a query to show that the value is present but does not contain the message added by the consumer (`updated via JMS`). Here is how you can do it using H2: + +** Start the H2 console by typing: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ java -cp __{jbossHomeName}__/modules/system/layers/base/com/h2database/h2/main/h2*.jar org.h2.tools.Console +---- + +** Log in: ++ +[source,options="nowrap"] +---- +Database URL: jdbc:h2:file:~/jta-crash-rec-quickstart +User name: sa +Password: sa +---- + +** The console is available at the url http://localhost:8082. If you receive an error such as `Exception opening port "8082"` it is most likely because some other application has that port open. You will need to find which application is using the port and close it. +** Once you are logged in enter the following query to see that the pair you entered is present but does not contain _"updated via JMS"_. ++ +[source,options="nowrap"] +---- +select * from kvpair +---- + +** Log out of the H2 console and make sure you close the terminal. H2 is limited to one connection and the application will need it from this point forward. +** If you are using the default file based transaction logging store, there will be a record in the file system corresponding to the pending transaction. +*** Open a terminal and navigate to the `__{jbossHomeName}__` directory +*** List the contents of the following directory: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ ls __{jbossHomeName}__/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/ +---- + +*** An example of a logging record file name is: ++ +[source,options="nowrap"] +---- +0_ffff7f000001_-7f1cf331_4f0b0ad4_15 +---- + +*** After recovery, log records are normally deleted automatically. However, logs may remain in the case where the Transaction Manager (TM) commit request was received and acted upon by a resource, but the TM crashed before it had time to clean up the logs of that resource. +. To observe XA recovery +** Stop the H2 console and exit the terminal to close the database connections. Otherwise, you may see messages like the following when you start your server: ++ +[source,options="nowrap"] +---- +Database may be already in use: "Locked by another process" +---- + +** link:{configureBytemanDisableDocUrl}[Disable the Byteman script] by restoring the backup server configuration file. +** xref:start_the_eap_standalone_server[Start the {productName} server] with the standalone full profile as described above. + +** Load the web interface to the application +** By the time the {productName} server is ready, the transaction should have recovered. +** A message is printed on the {productName} server console when the consumer has completed the update. Look for a line that reads: ++ +[source,options="now"] +---- +JTA Crash Record Quickstart: key value pair updated via JMS +---- + +** Check that the row you inserted in step 4 now contains the text `updated via JMS`, showing that the JMS message was recovered successfully. Use the application URL to perform this check. + +** You will most likely see the following messages in the server log. ++ +[source,options="nowrap"] +---- +WARN [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016037: Could not find new XAResource to use for recovering non-serializable XAResource XAResourceRecord < resource:null, txid:< formatId=131077, gtrid_length=29, bqual_length=36, tx_uid=0:ffff7f000001:1040a11d:534ede43:1c, node_name=1, branch_uid=0:ffff7f000001:1040a11d:534ede43:20, subordinatenodename=null, eis_name=java:jboss/datasources/JTACrashRecQuickstartDS >, heuristic: TwoPhaseOutcome.FINISH_OK, product: H2/1.3.168-redhat-2 (2012-07-13), jndiName: java:jboss/datasources/JTACrashRecQuickstartDS com.arjuna.ats.internal.jta.resources.arjunacore.XAResourceRecord@788f0ec1 > +WARN [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016038: No XAResource to recover < formatId=131077, gtrid_length=29, bqual_length=36, tx_uid=0:ffff7f000001:1040a11d:534ede43:1c, node_name=1, branch_uid=0:ffff7f000001:1040a11d:534ede43:20, subordinatenodename=null, eis_name=java:jboss/datasources/JTACrashRecQuickstartDS > +---- ++ +This is normal. What actually happened is that the first resource, `JTACrashRecQuickstartDS`, committed before the {productName} server was halted to insert the recovery record. The transaction logs are only updated/deleted after the outcome of the transaction is determined. If the transaction manager did update the log as each participant (database and JMS queue) completed then throughput would suffer. Notice you do not get a similar message for the JMS resource since that is the resource that recovered and the log record was updated to reflect this change. You need to manually remove the record for the first participant if you know which one is which or, if you are using the community version of the ${product.name} server, then you can also inspect the transaction logs using a JMX browser. For the demo it is simplest to delete the records from the file system, however, *be wary of doing this on a production system*. + +. Do NOT forget to link:{configureBytemanDisableDocUrl}[Disable the Byteman script] by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions! + +== Server Log: Expected Warnings and Errors + +You will see the following warnings in the server log. You can ignore these warnings. + +[source,options="nowrap"] +---- +WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. +HHH000431: Unable to determine H2 database version, certain features may not work +---- + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + + +NOTE: Within {JBDSProductName}, make sure you define a server runtime environment that uses the `standalone-full.xml` configuration file. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/jta-crash-rec/README.adoc b/jta-crash-rec/README.adoc index 50c13fa822..1ae8c59353 100644 --- a/jta-crash-rec/README.adoc +++ b/jta-crash-rec/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jta-crash-rec +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jta-crash-rec: Example of JTA Crash Recovery :author: Mike Musgrove @@ -31,13 +228,97 @@ In this example, you halt the {productName} server in the middle of an XA transa {productName} ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the `jta-crash-rec-ds.xml` file in the WEB-INF folder of the WAR archive. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Download and Configure Byteman @@ -50,9 +331,230 @@ Follow the instructions here to download and configure _Byteman_: link:{configur _NOTE_: The _Byteman_ scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the {productName} server before making the following changes. Otherwise _Byteman_ will not halt the server. // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -184,15 +686,80 @@ HHH000431: Unable to determine H2 database version, certain features may not wor ---- // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: NOTE: Within {JBDSProductName}, make sure you define a server runtime environment that uses the `standalone-full.xml` configuration file. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -202,4 +769,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/jta-crash-rec/pom.xml b/jta-crash-rec/pom.xml index f026e74d9d..7fc7ab3025 100644 --- a/jta-crash-rec/pom.xml +++ b/jta-crash-rec/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jta-crash-rec - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: jta-crash-rec This project demonstrates JTA crash recovery @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} diff --git a/jts/README-source.adoc b/jts/README-source.adoc new file mode 100644 index 0000000000..c199634b61 --- /dev/null +++ b/jts/README-source.adoc @@ -0,0 +1,406 @@ +include::../shared-doc/attributes.adoc[] + += jts: Java Transaction Service - Distributed EJB Transactions +:author: Tom Jenkinson +:level: Intermediate +:technologies: JTS, EJB, JMS +:prerequisites: link:cmt/README{outfilesuffix}[cmt] + +[abstract] +The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. + +:standalone-server-type: full +:archiveType: war +:requires-multiple-servers: +:jbds-not-supported: +:uses-ds-xml: + +== What is it? + +The `jts` quickstart demonstrates how to perform distributed transactions across multiple containers in an application deployed to {productNameFull}. A distributed transaction is a set of operations performed by two or more nodes, participating in an activity coordinated as a single entity of work, and fulfilling the properties of an ACID transaction. + +ACID is a set of 4 properties that guarantee the resources are processed in the following manner: + +* Atomic - if any part of the transaction fails, all resources remain unchanged. +* Consistent - the state will be consistent across resources after a commit +* Isolated - the execution of the transaction for each resource is isolated from each others +* Durable - the data will persist after the transaction is committed + +The example uses Java Transaction Service (JTS) to propagate a transaction context across two Container-Managed Transaction (CMT) EJBs that, although deployed in separate servers, participate in the same transaction. In this example, one server processes the Customer and Account data and the other server processes the Invoice data. + +The code base is essentially the same as the link:../cmt/README.adoc[cmt] quickstart, however in this case the `InvoiceManager` has been separated to a different deployment archive to demonstrate the usage of JTS. You can see the changes in the +following ways: + +* `cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/InvoiceManagerEJB.java` has been moved to `application-component-2/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/InvoiceManagerEJB` +* `cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/CustomerManagerEJB.java` has been moved to `jts/application-component-1/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/CustomerManagerEJB.java` + +The changes to `CustomerManagerEJB` are purely to accommodate the fact that `InvoiceManager` is now distributed. + +You will see that the `CustomerManagerEJB` uses the EJB home for the remote EJB, this is expected to connect to remote EJBs. The example expects the EJBs to be deployed onto the same physical machine. This is not a restriction of JTS and the example can easily be converted to run on separate machines by editing the hostname value for the `InvoiceManagerEJB` in `org.jboss.as.quickstarts.cmt.jts.ejb.CustomerManagerEJB`. + +A simple MDB has been provided that prints out the messages sent but this is not a transactional MDB and is purely provided for debugging purposes. + +Also, while the `cmt` quickstart uses the Jakarta EE container default datasource, which is not distributed, this quickstart instead uses an external PostgreSQL database. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Prerequisites + +Developers should be familiar with the concepts introduced in the `cmt` quickstart. + +This quickstart requires the configuration of two servers. The first server must be configured to use the PostgreSQL database. Instructions to install and configure PostgreSQL are below. + +[[configure_the_postgresql_database_for_use_with_this_quickstart]] +== Configure the PostgreSQL Database for Use with this Quickstart + +This quickstart requires the PostgreSQL database. + +. Instructions to install and configure PostgreSQL can be found here: link:{configurePostgresDownloadDocUrl}[Download and Install PostgreSQL] + +. For the purpose of this quickstart, replace the word `__QUICKSTART_DATABASE_NAME__` with `jts-quickstart-database` in the PostgreSQL instructions. + +. Make sure you link:{configurePostgresCreateUserDocUrl}[Create a Database User] for the PostgeSQL database. + +. When you have completed these steps, make sure you start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions to start the database server for your operating system every time you reboot your machine. + +Wait until later in these instructions to add the PostgreSQL module and driver configuration to the first {productName} server. + +== Configure the Servers + +For this example, you will need two instances of the application server, with a subtle startup configuration difference. Application server 2 must be started up 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. After you clone the second server, the first server must be configured for PostgreSQL. + +=== Configure the First Server + +You configure JTS transactions by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-jts-transactions.cli` script provided in the root directory of this quickstart. + +. Before you begin, back up your server configuration file +** If it is running, stop the {productName} server. +** Back up the file: `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` +** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. +. Start the {productName} server with the standalone full profile, passing a unique node ID, by typing the following command. Make sure you replace `UNIQUE_NODE_ID_1` with a node identifier that is unique to both servers. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + +. Review the `configure-jts-transactions.cli` file in the root of this quickstart directory. This script configures the server to use jts transaction processing. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: restart-required +---- + +. Stop the {productName} server. + +IMPORTANT: When you have completed testing this quickstart, it is important to xref:remove_the_jts_configuration_from_the_server[Remove the JTS Configuration from the {productName} Server]. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file and review the changes. + +. The orb initializers `transactions` attribute is changed from `spec` to `full` in the `iiop-openjdk` subsystem to enable JTS. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + +---- + +. An empty `` element is added to the end of the `transactions` subsystem to enable JTS. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + + + + + + + + + +---- + +=== Clone the Server Directory + +Make a copy of this {productName} directory structure to use for the second server. + +=== Configure Server1 to use PostgreSQL + +Application server 1 must be now configured to use the PostgreSQL database created previously in the xref:configure_the_postgresql_database_for_use_with_this_quickstart[Configure the PostgreSQL Database for Use with this Quickstart] section. + +. Make sure you start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions "Start the database server" for your operating system every time you reboot your machine. +. Follow the instructions to link:{configurePostgresAddModuleDocUrl}[Add the PostgreSQL Module to the {productName} Server] to the server 1 install only. +. Follow the instructions to link:{configurePostgresDriverDocUrl}[Configure the PostgreSQL Driver in the {ProductName} Server] for the server 1 configuration. Make sure you pass the `-Djboss.tx.node.id=UNIQUE_NODE_ID_1` on the command line when you start the first server to configure PostgreSQL. + +If there are issues with the scripts or you just want to configure the servers manually then the following will work: + +Start server 1: +``` +export WILDFLY_HOME_1=... +$WILDFLY_HOME_1/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 & +# enable JTS mode +cd /jts +$WILDFLY_HOME_1/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli +``` + +Stop server 1 and create second server by copying the installation directory: +``` +cp -r $WILDFLY_HOME_1 ${WILDFLY_HOME_1}-2 +export WILDFLY_HOME_2=${WILDFLY_HOME_1}-2 +``` + +Configure postgresql on server 1 only as a module: +``` +mkdir -p $WILDFLY_HOME_1/modules/org/postgresql/main +# download postgresql-42.6.0.jar or later and install it into the server: +cp /postgresql-42.6.0.jar $WILDFLY_HOME_1/modules/org/postgresql/main +``` +Create a module.xml for postgresql with the following contents: +``` +$ cat $WILDFLY_HOME_1/modules/org/postgresql/main/module.xml + + + + + + + + + + + +``` + +Add the datasource to $WILDFLY_HOME_1/standalone/configuration/standalone-full.xml +When you have done this the final changes to standalone-full.xml should be: + +``` +$ diff $WILDFLY_HOME_1/standalone/configuration/standalone-full.xml $WILDFLY_HOME_2/standalone/configuration/standalone-full.xml +137,142d136 +< +< jdbc:postgresql://localhost:5432/postgres +< postgresql +< +< +< +147,149d140 +< +< org.postgresql.xa.PGXADataSource +< + +``` +[[start_the_servers]] +== Start the Servers + +Start the two {productName} server with the standalone full profile, passing a unique node ID, by typing the following commands. You must pass a socket binding port offset on the command to start the second server. Make sure you replace `UNIQUE_NODE_ID_1` and `UNIQUE_NODE_ID_2` with node identifiers that are unique across both servers. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_2 -Djboss.socket.binding.port-offset=100 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. + +== Build and Deploy the Quickstart +// +// This quickstart deploys multiple archives and cannot use the shared doc. +// +Since this quickstart builds two separate components, you can not use the standard _Build and Deploy_ commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart. + +. Make sure you have started the {productName} server with the PostgreSQL driver. +. Open a terminal and navigate to the root directory of this quickstart. +. Type this command to build and deploy the archive. ++ +[source,options="nowrap"] +---- +$ mvn clean install wildfly:deploy +---- + +. This will deploy `{artifactId}-application-component-1.war` and `{artifactId}-application-component-2.jar` to the running instance of the server. + +== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}-application-component-1/. + +When you enter a name and click to `Add` that customer, you will see the following in the application server 1 console: + +[source,options="nowrap"] +---- +INFO [org.hibernate.hql.internal.QueryTranslatorFactoryInitiator] (default task-2) HHH000397: Using ASTQueryTranslatorFactory +INFO [org.jboss.ejb.client] (default task-4) JBoss EJB Client version 2.1.4.Final-redhat-1 +---- + +You will also see the following in application-server-2 console: + +[source,options="nowrap"] +---- +INFO [org.jboss.ejb.client] (p: default-threadpool; w: Idle) JBoss EJB Client version 2.1.4.Final-redhat-1 +INFO [class org.jboss.as.quickstarts.cmt.jts.mdb.HelloWorldMDB] (Thread-97 (ActiveMQ-client-global-threads-6840624)) Received Message: Created invoice for customer named: Tom +---- + +The web page will also change and show you the new list of customers. + +== Server Log: Expected Warnings and Errors + +You will see the following warnings in the server log. You can ignore these warnings. + +[source,options="nowrap"] +---- +WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. +---- + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + + +[[remove_the_jts_configuration_from_the_server]] +== Remove the JTS Configuration From the Server + +You must remove the JTS server configuration you did during setup because it interferes with the JTA quickstarts. + +You can modify the server configuration by running the `remove-jts-transactions.cli` script provided in the root directory of this quickstart, by using the JBoss CLI interactively, or by manually editing the configuration file. + +=== Remove the JTS Server Configuration by Running the CLI Script + +. Start the first {productName} server with the standalone full profile, passing a unique node ID, by typing the following command. Make sure you replace `UNIQUE_NODE_ID_1` with the node identifier that you used when you previously started the server. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` script. + +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}_1__` with the path to your server: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=remove-jts-transactions.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +This script removes the JTS configuration from the `iiop-openjdk` and `transactions` subsystems in the server configuration. You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: restart-required +{ + "outcome" => "success", + "result" => undefined +} +---- + +=== Remove the JTS Server Configuration using the Management CLI + +. Start the first {productName} server with the standalone full profile, passing a unique node ID, by typing the following command. Make sure you replace `UNIQUE_NODE_ID_1` with the node identifier that you used when you previously started the server. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` script. + +. To start the JBoss CLI tool, open a new terminal, navigate to the `__{jbossHomeName}_1__` directory, and type the following: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + +. At the prompt, type the following commands. ++ +[source,options="nowrap"] +---- +/subsystem=iiop-openjdk/:write-attribute(name=transactions,value=spec) +/subsystem=transactions/:undefine-attribute(name=jts) +/subsystem=transactions/:undefine-attribute(name=node-identifier) +---- + +. You should see the following response after each command execution. ++ +[source,options="nowrap"] +---- +{ + "outcome" => "success", + "response-headers" => { + "operation-requires-reload" => true, + "process-state" => "restart-required" + } +} +---- + +=== Remove the JTS Server Configuration Manually + +. Stop the server. +. If you backed up the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file, ,simply replace the edited configuration file with the backup copy. +. If you did not make a backup copy, open the file `__{jbossHomeName}__/standalone/configuration/standalone-full.`xml` and disable JTS as follows: +** Find the `orb` subsystem and change the configuration back to its original state. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + +---- + +** Find the `transaction` subsystem and remove the `node-identifier` attribute from the `core-environment` element. Also remove the `` element. ++ +[source,xml,subs="attributes+",options="nowrap"] +---- + + + + + + + + +---- + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] diff --git a/jts/README.adoc b/jts/README.adoc index c199634b61..7de25a664a 100644 --- a/jts/README.adoc +++ b/jts/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: jts +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = jts: Java Transaction Service - Distributed EJB Transactions :author: Tom Jenkinson @@ -43,13 +240,97 @@ A simple MDB has been provided that prints out the messages sent but this is not Also, while the `cmt` quickstart uses the Jakarta EE container default datasource, which is not distributed, this quickstart instead uses an external PostgreSQL database. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Prerequisites @@ -279,7 +560,26 @@ WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in ---- // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: [[remove_the_jts_configuration_from_the_server]] @@ -393,7 +693,27 @@ NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. ---- // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: //************************************************* // Product Release content only diff --git a/jts/application-component-1/pom.xml b/jts/application-component-1/pom.xml index f27b5707d5..359596e379 100644 --- a/jts/application-component-1/pom.xml +++ b/jts/application-component-1/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts jts - 31.0.0.Final-SNAPSHOT + 31.0.0.Final jts-application-component-1 war diff --git a/jts/application-component-2/pom.xml b/jts/application-component-2/pom.xml index 57f6c425af..ecec015e6d 100644 --- a/jts/application-component-2/pom.xml +++ b/jts/application-component-2/pom.xml @@ -21,7 +21,7 @@ org.wildfly.quickstarts jts - 31.0.0.Final-SNAPSHOT + 31.0.0.Final jts-application-component-2 Quickstart: jts - application-component-2 diff --git a/jts/pom.xml b/jts/pom.xml index 7c3bcbe580..3123c6ee58 100644 --- a/jts/pom.xml +++ b/jts/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jts - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom Quickstart: jts A project that demonstrates how to use CMT with JTS @@ -52,7 +52,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 4.2.1.Final diff --git a/kitchensink/README-source.adoc b/kitchensink/README-source.adoc new file mode 100644 index 0000000000..5643a37f82 --- /dev/null +++ b/kitchensink/README-source.adoc @@ -0,0 +1,150 @@ +include::../shared-doc/attributes.adoc[] + += kitchensink: Assortment of technologies +:author: Pete Muir +:level: Intermediate +:technologies: CDI, JSF, JPA, EJB, JAX-RS, BV +:openshift: true + +[abstract] +The `kitchensink` quickstart demonstrates a localized {javaVersion} web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation. + +:standalone-server-type: default +:archiveType: war +:uses-h2: +:uses-ds-xml: + +== What is it? + +The `kitchensink` quickstart is a deployable Maven 3 project designed to help you get your foot in the door developing with {javaVersion} on {productNameFull}. + +It demonstrates how to create a _localized_ {javaVersion} compliant application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. A localized application is one that supports multiple languages. It also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. + +This quickstart has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using http://translate.google.com, so the translations may not be ideal. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +=== Localization Code Changes + +The following changes were made to the quickstart to enable it to use the browser preferred locale setting when displaying the web page: + +* Properties files were created for the supported languages. + +** This quickstart is localized for Spanish and French. You can add additional language support by creating properties files with the appropriate suffix and populating the properties with translated values. + +** The JSF resource Bundle is located at `src/main/resources/org/jboss/as/quickstarts/kitchensink/bundle/Resources_(es|fr).properties + +** Messages generated by Java code (e.g. log messages and messages sent to the UI) are internationalized using JBoss Logging. The log messages are accessed via the `org.jboss.as.quickstarts.kitchensink.util.KitchensinkMessages` interface, and the message bundles are located at: `src/main/resources/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.i18_(es|fr).properties` + +** The message bundle consumed by Bean Validation is located at `src/main/resources/ValidationMessages.properties`. This is defined by the bean validation specification. + +* The following XML was added to the `src/main/webapp/WEB-INF/faces-config.xml` file. When you create a property file for a new language, you must add the supported locale to this file. ++ +[source,xml,options="nowrap"] +---- + + + en + en-US + fr + fr-FR + es + es-ES + + + org/jboss/as/quickstarts/kitchensink/bundle/Resources + bundle + + +---- + +* The `src/main/java/org/jboss/as/quickstarts/kitchensink/model/Member.java` file was modififed to add the message key to @Pattern annotation. ++ +[source,java,options="nowrap"] +---- +@NotNull +@Size(min = 1, max = 25) +@Pattern(regexp = "[A-Za-z ]*", message = "{name_validation_message}") +private String name; +---- + +* The `src/main/java/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.java` file was created, which defines default messages in English. The `jboss-logging-processor` will automatically generate an implementation for you, which can be accesssed via the `MESSAGES` static variable. ++ +[source,java,options="nowrap"] +---- +@MessageBundle(projectCode = "") +public interface KitchensinkMessages { + + KitchensinkMessages MESSAGES = Messages.getBundle(KitchensinkMessages.class, FacesContext.getCurrentInstance().getViewRoot().getLocale()); + + @Message("Registered!") + String registeredMessage(); + + @Message("Successfully registered!") + String registerSuccessfulMessage(); + + @Message("Registration failed:") + String registerFailMessage(); + + @Message("Registration failed. See server log for more information.") + String defaultErrorMessage(); +} +---- + +* The `src/main/java/org/jboss/as/quickstarts/kitchensink/controller/MemberController.java` file was modified as follows: + +** Messages strings were replaced with strings retrieved using the resource bundle property names. For example: ++ +[source,java,options="nowrap"] +---- +FacesMessage m = new FacesMessage(FacesMessage.SEVERITY_INFO, + KitchensinkMessages.MESSAGES.registeredMessage(), + KitchensinkMessages.MESSAGES.registerSuccessfulMessage()); +---- + +* The `src/main/webapp/index.xhtml` file were modified. + +** Strings for headers, messages, labels were replaced with the appropriate `# {bundle.}`, for example: `# {bundle.memberWelcomeHeader}`. + +=== Set the Browser Preferred Locale + +How you set your browser preferred locale depends on the browser and version you use. Use your browser help option to search for instructions to change the preferred language setting. + +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +=== Server Log: Expected Warnings and Errors + +You will see the following warnings in the server log. You can ignore these warnings. + +[source,options="nowrap"] +---- +WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/kitchensink/README.adoc b/kitchensink/README.adoc index 17edd0d02a..8a07416133 100644 --- a/kitchensink/README.adoc +++ b/kitchensink/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: kitchensink +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = kitchensink: Assortment of technologies :author: Pete Muir @@ -24,7 +221,13 @@ It demonstrates how to create a _localized_ {javaVersion} compliant application This quickstart has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using http://translate.google.com, so the translations may not be ideal. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: === Localization Code Changes @@ -113,19 +316,318 @@ FacesMessage m = new FacesMessage(FacesMessage.SEVERITY_INFO, How you set your browser preferred locale depends on the browser and version you use. Use your browser help option to search for instructions to change the preferred language setting. // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -141,11 +643,624 @@ WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file + +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: kitchensink +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/kitchensink/charts/helm.yaml b/kitchensink/charts/helm.yaml index 07593d4f85..7d2fd49968 100644 --- a/kitchensink/charts/helm.yaml +++ b/kitchensink/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: kitchensink deploy: replicas: 1 \ No newline at end of file diff --git a/kitchensink/pom.xml b/kitchensink/pom.xml index 620cd1e667..51272e775a 100644 --- a/kitchensink/pom.xml +++ b/kitchensink/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 kitchensink - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: kitchensink A starter Jakarta EE web application project for use in JBoss EAP @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/logging/README-source.adoc b/logging/README-source.adoc new file mode 100644 index 0000000000..8e066f1331 --- /dev/null +++ b/logging/README-source.adoc @@ -0,0 +1,164 @@ +include::../shared-doc/attributes.adoc[] + += logging: Example That Sets Up Different Logging Levels +:author: Joel Tosi +:level: Intermediate +:technologies: Logging + +[abstract] +The `logging` quickstart demonstrates how to configure different logging levels in {productName}. + +:standalone-server-type: default +:archiveType: war +:restoreScriptName: remove-logging.cli +:openshift: true + +== What is it? + +The `logging` quickstart demonstrates how to set up and log different levels of information in {productNameFull}. + +This quickstart contains contains a simple REST endpoint which will log messages. The `index.html` page can be used +to log messages and see the results. However, you could use a REST client or something like `cURL` to invoke log +messages. + +To better visualize how the logging configuration works, you first deploy and access the application before configuring the logs and view the resulting log files. Then you configure the logs, redeploy and access the application, and look at the log files again to see the differences. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +[[access_the_application]] +== Access the Application + +The application is running at the following URL: http://localhost:8080/{artifactId}/. + +You will see the following message in the server console: + +[source,options="nowrap"] +---- +18:20:33,272 FATAL [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an FATAL message from 127.0.0.1:50130 +18:20:34,530 ERROR [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an ERROR message from 127.0.0.1:50130 +18:20:35,332 WARN [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an WARN message from 127.0.0.1:50130 +18:20:36,254 INFO [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an INFO message from 127.0.0.1:50130 +18:20:37,156 DEBUG [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an DEBUG message from 127.0.0.1:50130 +18:20:38,003 TRACE [org.jboss.as.quickstarts.logging.rest.LogListingResource] (default task-1) This is an TRACE message from 127.0.0.1:50130 +---- + +== Check the Server Logs + +The log files are located in the `__{jbossHomeName}__/standalone/log` log directory. At this point you should see the following log files. + +* `server.log` - This is the standard log produced by the application server. By default, it contains all the server log messages, including the server startup messages. + +== Configure the Server + +Now you have deployed the quickstart with the default configuration, you run a management CLI script to configure the logging subsystem and review the differences in the resulting log files. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + + +. Review the `configure-logging.cli` file in the root of this quickstart directory. This script configures the logging subsystem in the server configuration file. It configures the file handlers, creates the logger for our quickstart and sets the level to TRACE. It also assigns the handlers for our quickstart to our logger. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-logging.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +== Test the New Logging Configuration + +. Make sure you xref:start_the_eap_standalone_server[start the {productName} server with the standalone default profile] as described above. +. xref:build_and_deploy_the_quickstart[Build and deploy the quickstart]. +. xref:access_the_application[Access the application]. + +== Recheck the Server Logs + +The log files are located in the `__{jbossHomeName}__/standalone/log` log directory. You should now see the 6 additional log files that are produced by this quickstart. They are listed below in hierarchical order from the largest file containing the most messages to the smallest file containing the least messages. + +** `quickstart.trace.log` +** `quickstart.debug.log` +** `quickstart.info.log` +** `quickstart.warn.log` +** `quickstart.error.log` +** `quickstart.fatal.log` + +The following are the rest endpoint paths. Note these can be accessed from the `index.html` by clicking the buttons + +* `/api/logs/trace` +* `/api/logs/debug` +* `/api/logs/info` +* `/api/logs/warn` +* `/api/logs/error` +* `/api/logs/fatal` + +The following describes what happens when you access this quickstart: + +. When you access one of the above endpoints, a simple message is logged. +. Finally, the class file logs various levels, each to its own file as configured in `standalone.xml`. Note that log levels are hierarchical. When set, all log levels above the specified level are logged as well. +. Common uses of the 6 log levels are outlined below. You should use the level that makes the most sense in your environment. ++ +[source,options="nowrap"] +---- +FATAL - Used to track critical system failures. When this log message is written, it is writing application error that has caused service to cease. This is the most narrow logging. +ERROR - Used to track application errors that may cause one request to fail (not a service ceasement). +WARN - Used for warnings. At this level, all *WARN*, *ERROR*, and *FATAL* messages are written. Use this level message as a predictive measure for possible forthcoming issues. +INFO - This provides any information - state transition, object values, etc +DEBUG - Turned on in any environment when a problem is occuring. The information captured may be throughput, communication, object values, etc. +TRACE - Turned on in any environment where you are trying to follow an execution path, for optimization or debugging. This is the most broad logging level and all messages are written. +---- + +. To view log file differences for different logging levels, change the level for the "org.jboss.as.quickstarts.logging" logger +from TRACE to DEBUG, INFO, WARN, ERROR, or FATAL, then access the application. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script removes the log and file handlers from the `logging` subsystem in the server configuration. You should see the following result when you run the script: + +[source,options="nowrap"] +---- +{"outcome" => "success"} +{"outcome" => "success"} +{"outcome" => "success"} +{"outcome" => "success"} +{"outcome" => "success"} +{"outcome" => "success"} +{"outcome" => "success"} +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] diff --git a/logging/README.adoc b/logging/README.adoc index 8d5107cfea..e74c9d13af 100644 --- a/logging/README.adoc +++ b/logging/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: logging +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = logging: Example That Sets Up Different Logging Levels :author: Joel Tosi @@ -25,17 +222,373 @@ messages. To better visualize how the logging configuration works, you first deploy and access the application before configuring the logs and view the resulting log files. Then you configure the logs, redeploy and access the application, and look at the log files again to see the differences. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: [[access_the_application]] == Access the Application @@ -135,11 +688,87 @@ TRACE - Turned on in any environment where you are trying to follow an execution from TRACE to DEBUG, INFO, WARN, ERROR, or FATAL, then access the application. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script removes the log and file handlers from the `logging` subsystem in the server configuration. You should see the following result when you run the script: @@ -156,11 +785,653 @@ This script removes the log and file handlers from the `logging` subsystem in th ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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] +---- +Unresolved directive in ../shared-doc/helm-deploy-project.adoc - include::/home/runner/work/quickstart/quickstart/logging/charts/helm.yaml[] +---- +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[] + + +[[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 + +// 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 -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +:leveloffset!: diff --git a/logging/pom.xml b/logging/pom.xml index a759a95437..64fed0c9b5 100644 --- a/logging/pom.xml +++ b/logging/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 jboss-logging - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: logging This project demonstrates logging in JBoss EAP @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/logging/src/charts/helm.yaml b/logging/src/charts/helm.yaml index f3e9d294ce..c411a053e0 100644 --- a/logging/src/charts/helm.yaml +++ b/logging/src/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: logging deploy: replicas: 1 \ No newline at end of file diff --git a/mail/README-source.adoc b/mail/README-source.adoc new file mode 100644 index 0000000000..4e3fdd8375 --- /dev/null +++ b/mail/README-source.adoc @@ -0,0 +1,203 @@ +include::../shared-doc/attributes.adoc[] + += mail: E-Mail Example using CDI and JSF +:author: Joel Tosi +:level: Beginner +:technologies: JavaMail, CDI, JSF + +[abstract] +The `mail` quickstart demonstrates how to send and receive emails using CDI and JSF and with custom Mail provider configured in {productName}. + +:standalone-server-type: default +:archiveType: war +:restoreScriptName: remove-mail-session.cli + +== What is it? + +The `mail` quickstart demonstrates sending and receiving emails with the use of _CDI_ (Contexts and Dependency Injection) and _JSF_ (JavaServer Faces) in {productNameFull}. + +The mail provider is configured in the `mail` subsystem of the `__{jbossHomeName}__/standalone/configuration/standalone.xml` configuration file if you are running a standalone server or in the `__{jbossHomeName}__/domain/configuration/domain.xml` configuration file if you are running in a managed domain. + +You can use the default mail provider that comes out of the box with {productName}. It uses your local mail relay and the default SMTP port of 25. However, this quickstart demonstrates how to define and use a custom mail provider. + +This example is a web application that takes `To`, `From`, `Subject`, and `Message Body` input and sends mail using SMTP. These emails can be later read by using IMAP or POP3. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +[[configure_an_smtp_server_on_your_local_machine]] +== Configure a Mail Server on Your Local Machine + +To run the Mail Quickstart, you need a Mail Server configured with the following protocols and ports: + +- SMTP port:1025 +- POP3 port:1110 +- IMAP port:1143 + +In addition, the Mail Subsystem configuration and the test cases expect you have the following Mail accounts configured on your Mail Server: + +- user01@james.local +- user02@james.local + +You can use any Mail Server you consider, although to facilitate this task, you will find under the Mail Quickstart root directory a docker compose file prepared to launch an Apache James Mail server with all the required configuration. You will need to have installed a Container Engine capable of work with Docker compose files and Linux images. The following command assumes you have https://podman.io/[Podman] and https://docs.podman.io/en/latest/markdown/podman-compose.1.html[Podman Compose] installed in your local environment. + +To launch the Apache James Mail server, open the terminal and navigate to the Mail Quickstart root directory and execute the following: + +``` +$ podman compose up --wait +>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<< + +[+] Running 1/1 + ✔ Container apache-james Healthy +``` + +NOTE: The Apache James server is configured without allowing the relay of the emails to external addresses that are not configured in the server. When you are sending / receiving emails with this server, you have to use the accounts shipped with the apache James demo image. These are the accounts available out of the box: user01@james.local, user02@james.local and user03@james.local. +All accounts use the same password: `1234` + +Once you have finished with the Mail Quickstart, you can shutdown and remove the Apache James Mail server with the following command: + +``` +$ podman compose down --volumes +>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<< + +[+] Running 2/1 + ✔ Container apache-james Removed + ✔ Network mail_default Removed +``` + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You configure the custom mail session in {productName} by running Management CLI commands. For your convenience, this quickstart batches the commands into a `configure-mail-session.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-mail-session.cli` file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom `MyOtherMail` mail session and configures it to use the custom outbound socket binding ports and default user credentials for SMTP and IMAP. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-mail-session.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script. ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +The following `outbound-socket-binding` groups are added to the `standard-sockets` `` element. + +[source,xml,options="nowrap"] +---- + + ... + + + + + + + + + + + +---- + +The `MyOtherMail` mail session is added to the `mail` subsystem and configured to use the custom outbound socket binding ports. + +[source,xml,subs="attributes+",options="nowrap"] +---- + + + + + + + + + + +---- + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/[http://localhost:8080/{artifactId}/^]. + +NOTE: If you see `Error processing request` in the browser when you access the application and attempt to send email, followed by `jakarta.servlet.ServletException: MailConnectException: Couldn't connect to host, port: localhost, 1025; timeout -1; nested exception is: java.net.ConnectException: Connection refused`, make sure you followed the instructions above to xref:configure_an_smtp_server_on_your_local_machine[Configure an SMTP Server on Your Local Machine]. + +NOTE: If you are using the Mail server shipped with this Quickstart and see `Error sending the Email. Invalid Addresses` in the browser when you attempt to send email, make sure you are sending your email to an existing account configured in the Mail Server since by default Apache James demo image is shipped with relay disabled. By default, Apache James demo image has the following accounts configured: user01@james.local, user02@james.local and user03@james.local. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script removes the custom `MyOtherMail` session from the `mail` subsystem in the server configuration. file You should see the following result when you run the script: + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +* Make sure you xref:configure_an_smtp_server_on_your_local_machine[Configure an SMTP Server on Your Local Machine]. +* Make sure you configure the {productName} custom mail configuration as described above under xref:configure_the_server[Configure the {productName} Server]. Stop the server at the end of that step. +* To deploy the server project, right-click on the *{artifactId}* project and choose *Run As* –> *Run on Server*. A browser window appears that accesses the running application. +* To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* –> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. +* Make sure you xref:restore_the_server_configuration[restore the {productName} server configuration] when you have completed testing this quickstart. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] diff --git a/mail/README.adoc b/mail/README.adoc index 15d2a3a308..89c21f0d09 100644 --- a/mail/README.adoc +++ b/mail/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: mail +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = mail: E-Mail Example using CDI and JSF :author: Joel Tosi @@ -24,11 +221,66 @@ You can use the default mail provider that comes out of the box with {productNam This example is a web application that takes `To`, `From`, `Subject`, and `Message Body` input and sends mail using SMTP. These emails can be later read by using IMAP or POP3. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: [[configure_an_smtp_server_on_your_local_machine]] == Configure a Mail Server on Your Local Machine @@ -71,9 +323,203 @@ $ podman compose down --volumes ``` // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -146,7 +592,114 @@ The `MyOtherMail` mail session is added to the `mail` subsystem and configured t ---- // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -157,12 +710,88 @@ NOTE: If you see `Error processing request` in the browser when you access the a NOTE: If you are using the Mail server shipped with this Quickstart and see `Error sending the Email. Invalid Addresses` in the browser when you attempt to send email, make sure you are sending your email to an existing account configured in the Mail Server since by default Apache James demo image is shipped with relay disabled. By default, Apache James demo image has the following accounts configured: user01@james.local, user02@james.local and user03@james.local. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script removes the custom `MyOtherMail` session from the `mail` subsystem in the server configuration. file You should see the following result when you run the script: @@ -174,9 +803,106 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions * Make sure you xref:configure_an_smtp_server_on_your_local_machine[Configure an SMTP Server on Your Local Machine]. @@ -186,11 +912,296 @@ include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[levelof * Make sure you xref:restore_the_server_configuration[restore the {productName} server configuration] when you have completed testing this quickstart. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] //************************************************* diff --git a/mail/pom.xml b/mail/pom.xml index 4a8744f8e7..d1fb54d1f1 100644 --- a/mail/pom.xml +++ b/mail/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 mail - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: mail This project demonstrates how to send mail @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/messaging-clustering-singleton/README-source.adoc b/messaging-clustering-singleton/README-source.adoc new file mode 100644 index 0000000000..1052023a16 --- /dev/null +++ b/messaging-clustering-singleton/README-source.adoc @@ -0,0 +1,487 @@ +include::../shared-doc/attributes.adoc[] + += messaging-clustering-singleton: Messaging Example that Demonstrates Clustering +:author: Flavia Rainone, Jess Sightler +:level: Advanced +:technologies: JMS, MDB, Clustering + +[abstract] +The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using {productName} messaging with MDB singleton configuration where only one node in the cluster will be active. + +:standalone-server-type: full-ha +:archiveType: war +:optional-domain-or-multiple-servers: +:jbds-not-supported: + +== What is it? + +The `messaging-clustering-singleton` quickstart demonstrates the use of clustering with integrated Apache ActiveMQ Artemis. It uses the same code as in link:../helloworld-mdb/README.adoc[helloworld-mdb] quickstart, with only a difference in the configuration to run it as a clustered singleton. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. + +These are the two JMS resources contained in this quickstart: + +* A queue named `HELLOWORLDMDBQueue` bound in JNDI as `java:/queue/HELLOWORLDMDBQueue` +* A topic named `HELLOWORLDMDBTopic` bound in JNDI as `java:/topic/HELLOWORLDMDBTopic` + +Both contain a singleton configuration as specified in the file link:src/main/webapp/WEB-INF/jboss-ejb3.xml[WEB-INF/jboss-ejb3.xml]: + +[source,xml,options="nowrap"] +---- + + * + true + +---- + +The wildcard (*) in the `ejb-name` element indicates that all MDBs contained in the application will be clustered singleton. As a result, only one node in the cluster will have those MDBs active at a specific time. If that node shuts down, another node in the cluster will become the active node with MDBs, called the singleton provider. + +Also, we can find a configuration for delivery group in the same file: + +[source,xml,options="nowrap"] +---- + + HelloWorldTopicMDB + my-mdb-delivery-group + +---- + +Here, you can see that only one of the MDBs, `HelloWorldTopicMDB`, is associated with a delivery group. All delivery groups used by an MDB must be declared in the `ejb` subsystem configuration, and they can be enabled or disabled. If the delivery group is disabled in a cluster node, all MDBs belonging to that group will be inactive in that node. Notice that delivery groups can be used in non-clustered environments as well. In that case, the MDB will be active in the server whenever the delivery group is enabled in the server. A delivery group can be enabled using the management CLI as you will see in this quickstart. + +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. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Build the Project + +Follow these steps to build the project without deploying it. + +. Open a terminal and navigate to the root directory of this quickstart. +. Type this command to build the archive: ++ +[source,options="nowrap"] +---- +$ mvn clean install +---- + +== 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 + +You configure the server by running the `install-domain.cli` script provided in the root directory of this quickstart. + +// Back Up the {productName} Managed Domain Configuration +include::../shared-doc/back-up-managed-domain-configuration.adoc[leveloffset=+3] +// Start the {productName} Managed Domain +include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+3] + +==== 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: + +** Stops the servers. +** Creates the `quickstart-messaging-clustering-singleton-group` server group to test ActiveMQ clustering. +** Enables console logging to allow you to view the quickstart output. +** Adds two servers to the `server-group`. +** Configures ActiveMQ clustering in the `full-ha` profile. +** Creates a delivery group named `my-mdb-delivery-group`, with initial active value set to `true`. +** Deploys the `{artifactId}.war` archive. +** Starts the servers that were added to the managed domain. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=install-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following output: ++ +[source,options="nowrap"] +---- +{ + "outcome" => "success", + "result" => undefined, + "server-groups" => undefined +} +The batch executed successfully +{ + "outcome" => "success", + "result" => "STARTED" +} +{ + "outcome" => "success", + "result" => "STARTED" +} +---- + +[[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 +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+3] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+3] + +==== 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=install-standalone.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +You should see the following output: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +==== 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. + +. Stop the server. +. Make a copy of this {productName} directory structure to use for the second server. +. Remove the following directories from the cloned instance: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}_2__/standalone/data/activemq/bindings +__{jbossHomeName}_2__/standalone/data/activemq/journal +__{jbossHomeName}_2__/standalone/data/activemq/largemessages +---- + +==== Start the {productName} Standalone Servers with the Full HA Profile + +Use the following commands to start the standalone servers with the full HA profile. + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full-ha.xml +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-full-ha.xml -Djboss.socket.binding.port-offset=100 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` and `__{jbossHomeName}_2__\bin\standalone.bat` scripts. + +== Access the Application + +=== Access the Application Running in a Managed Domain + +The application will be running at the following URL: http://localhost:9080/{artifactId}/HelloWorldMDBServletClient. + +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 + +The application will be running at the following URL: http://localhost:8080/{artifactId}/HelloWorldMDBServletClient. + +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 + +Review the messages in both {productName} server consoles or logs. + +The following messages are sent to the queue: + +[source,options="nowrap"] +---- +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-0 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 1 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-2 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 3 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 5 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-3 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 4 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-1 (ActiveMQ-client-global-threads)) Received Message from queue: This is message 2 +---- + +The following messages are sent to the topic: + +[source,options="nowrap"] +---- +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-5 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 1 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-6 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 2 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-8 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 4 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-7 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 3 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldTopicMDB] (Thread-9 (ActiveMQ-client-global-threads)) Received Message from topic: This is message 5 +---- + +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 + +You will see the following warnings in the server logs. You can ignore these warnings as they are intended for production servers. + +[source,options="nowrap"] +---- +WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket DatagramSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the receive buffer of socket DatagramSocket was set to 20MB, 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) +WARNING [org.jgroups.protocols.UDP] (Thread-0 (ActiveMQ-server-ActiveMQServerImpl::serverUUID=c79278db-56e6-11e5-af50-69dd76236ee8-1573164340)) JGRP000015: the send buffer of socket MulticastSocket was set to 1MB, but the OS only allocated 212.99KB. This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux) +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 + +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. + +You should see the following output in the new singleton provider server: + +[source,options="nowrap"] +---- +WFLYCLSV0003: master:quickstart-messagingcluster-nodeX elected as the singleton provider of the org.wildfly.ejb3.clustered.singleton service +---- + +Where `nodeX` will be either `node1` or `node2`, depending on which node is the new singleton provider. + +If you now try to access the servlet urls, you will see that the new provider is receiving all new messages. + +You will see the following warnings in the log of the server that is _not_ the singleton provider. These messages show that the other node went down unexpectedly, which is exactly the scenario we are reproducing in this quickstart. For that reason, those warnings can be ignored. + +[source,options="nowrap"] +---- +WARN [org.apache.activemq.artemis.core.client] (Thread-2 (ActiveMQ-client-global-threads)) AMQ212037: Connection failure has been detected: AMQ119015: The connection was disconnected because of server shutdown [code=DISCONNECTED] +WARN [org.apache.activemq.artemis.core.server] (Thread-2 (ActiveMQ-client-global-threads)) AMQ222095: Connection failed with failedOver=false +---- + +You may see the following log message as well. When a server is restarted, it may broadcast that it is up and running (with its nodeID) while other nodes still reference the previous server instance for the same nodeID. Eventually, the cluster will be informed of the new instance representing the given nodeID but as the warning explains, it is possible to see this log (once or more) when a server is restarted. + +[source,options="nowrap"] +---- +WARN [org.apache.activemq.artemis.core.client] (activemq-discovery-group-thread-dg-group1) AMQ212034: There are more than one servers on the network broadcasting the same node id. You will see this message exactly once (per node) if a node is restarted, in which case it can be safely ignored. But if it is logged continuously it means you really do have more than one node on the same network active concurrently with the same node id. This could occur if you have a backup node active at the same time as its live node. nodeID=a114b652-689e-11e7-a2f4-54ee751c6182 +---- + +The next error message is a https://issues.jboss.org/browse/WFLY-9261[known issue]. You can ignore it, as it does not affect the scenario that this quickstart reproduces: + +[source,options="nowrap"] +---- +ERROR [org.apache.activemq.artemis.core.server] (Thread-3 (ActiveMQ-client-global-threads)) AMQ224037: cluster connection Failed to handle message: java.lang.IllegalStateException: Cannot find binding for jms.queue.HelloWorldMDBQueuedea3e995-713c-11e7-85f2-b8f6b112daf7 on ClusterConnectionImpl@1129705701[nodeUUID=dabaa1fa-713c-11e7-8f3a-b8f6b112daf7, connector=TransportConfiguration(name=http-connector, factory=org-apache-activemq-artemis-core-remoting-impl-netty-NettyConnectorFactory) ?httpUpgradeEndpoint=http-acceptor&activemqServerName=default&httpUpgradeEnabled=true&port=9080&host=localhost, address=jms, server=ActiveMQServerImpl::serverUUID=dabaa1fa-713c-11e7-8f3a-b8f6b112daf7] +at org.apache.activemq.artemis.core.server.cluster.impl.ClusterConnectionImpl$MessageFlowRecordImpl.doConsumerCreated(ClusterConnectionImpl.java:1294) +at org.apache.activemq.artemis.core.server.cluster.impl.ClusterConnectionImpl$MessageFlowRecordImpl.handleNotificationMessage(ClusterConnectionImpl.java:1029) +at org.apache.activemq.artemis.core.server.cluster.impl.ClusterConnectionImpl$MessageFlowRecordImpl.onMessage(ClusterConnectionImpl.java:1004) +at org.apache.activemq.artemis.core.client.impl.ClientConsumerImpl.callOnMessage(ClientConsumerImpl.java:1001) +at org.apache.activemq.artemis.core.client.impl.ClientConsumerImpl.access$400(ClientConsumerImpl.java:49) +at org.apache.activemq.artemis.core.client.impl.ClientConsumerImpl$Runner.run(ClientConsumerImpl.java:1124) +at org.apache.activemq.artemis.utils.OrderedExecutorFactory$OrderedExecutor$ExecutorTask.run(OrderedExecutorFactory.java:101) +at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142) +at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617) +at java.lang.Thread.run(Thread.java:745) +---- + +=== 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 +---- + +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +=== 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 + +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. + +After disabling the delivery group, try sending messages to the topic, You should notice that the topic messages are not delivered when the delivery group is inactive. + +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 + +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 +---- + +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +Similarly, to enable the delivery group, run the `enable-delivery-group-domain.cli` script: + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{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 + +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}_2__/bin/jboss-cli.sh --connect controller=localhost:10090 --file=disable-delivery-group-standalone.cli +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. + + +Similarly, to enable the delivery group, run the `enable-delivery-group-standalone.cli` script in both servers: + +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{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 + +When you are finished testing, use the following instructions to undeploy the quickstart. + +=== 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 +---- + +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +=== Undeploy the quickstart in a Standalone Server + +. 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: ++ +[source,subs="+quotes,attributes+",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 +---- + +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. + +== Restore the Server Configuration + +=== Restore the Domain 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 Manually + +IMPORTANT: This method ensures the server is restored to its prior configuration. + +. If it is running, stop the {productName} server. +. 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 + +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. + +. 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 `remove-domain.cli` script, replacing `__{jbossHomeName}__` with the path to your server. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-domain.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +This script removes the server configuration that was done by the `install-domain.cli` script. You should see the following result following the script commands: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +=== 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. + +[[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 + +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. + +. Start the {productName} server by typing the following, replacing `__{jbossHomeName}_1__` with the path to your first server: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-full-ha.xml +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` script. + +. Open a new terminal, navigate to the root directory of this quickstart, and run the `remove-standalone.cli` script, replacing `__{jbossHomeName}_1__` with the path to your first server. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=remove-standalone.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. + ++ +This script removes the server configuration that was done by the install-standalone.cli script. You should see the following result following the script commands: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +=== 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 +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/messaging-clustering-singleton/README.adoc b/messaging-clustering-singleton/README.adoc index 1052023a16..c546b603b5 100644 --- a/messaging-clustering-singleton/README.adoc +++ b/messaging-clustering-singleton/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: messaging-clustering-singleton +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = messaging-clustering-singleton: Messaging Example that Demonstrates Clustering :author: Flavia Rainone, Jess Sightler @@ -49,11 +246,66 @@ 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. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 the Project @@ -77,9 +329,58 @@ You can choose to configure and deploy this quickstart to a xref:configure_the_s You configure the server by running the `install-domain.cli` script provided in the root directory of this quickstart. // Back Up the {productName} Managed Domain Configuration -include::../shared-doc/back-up-managed-domain-configuration.adoc[leveloffset=+3] +:leveloffset: +3 + +[[back_up_managed_domain_configuration]] += Back Up the {productName} Managed Domain Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a managed domain and +// needs to back up the server configuration files before running +// a CLI script to modify the server. +//****************************************************************************** + +Before you begin, back up your server configuration files. + +. If it is running, stop the {productName} server. +. Back up the following files: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +__{jbossHomeName}__/domain/configuration/domain.xml +__{jbossHomeName}__/domain/configuration/host.xml +---- + +After you have completed testing this quickstart, you can replace these file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Managed Domain -include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+3] +:leveloffset: +3 + +[[start_the_eap_managed_domain]] += Start the {productName} Managed Domain +//****************************************************************************** +// Include this template if your quickstart requires a normal start of a +// managed domain. +// +// This template does not currently support passing arguments for starting +// the domain, but it could be added. +// +// * Define the managed domain profile type. Supported values are: +// :managed-domain-type: default +// +//****************************************************************************** + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} managed domain by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/domain.sh +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\domain.bat` script. + +:leveloffset!: ==== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI @@ -131,9 +432,203 @@ If you choose to use standalone servers rather than a managed domain, you need t 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 -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+3] +:leveloffset: +3 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+3] +:leveloffset: +3 + +[[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!: ==== Configure the Standalone Server and Deploy the Quickstart Using the JBoss CLI @@ -474,7 +969,27 @@ The batch executed successfully . Delete the cloned directory. // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: //************************************************* // Product Release content only @@ -484,4 +999,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/messaging-clustering-singleton/pom.xml b/messaging-clustering-singleton/pom.xml index a44a993cfa..cec8063200 100644 --- a/messaging-clustering-singleton/pom.xml +++ b/messaging-clustering-singleton/pom.xml @@ -24,12 +24,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 messaging-clustering-singleton - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: messaging-clustering-singleton This project demonstrates a hello world Message-Driven Bean with Servlet 3.0 as client diff --git a/micrometer/README-source.adoc b/micrometer/README-source.adoc new file mode 100644 index 0000000000..3596ac0f89 --- /dev/null +++ b/micrometer/README-source.adoc @@ -0,0 +1,276 @@ +include::../shared-doc/attributes.adoc[] + += micrometer: Micrometer QuickStart +:author: Jason Lee +:level: Beginner +:technologies: Micrometer +:openshift: true + +[abstract] +The `micrometer` quickstart demonstrates the use of the Micrometer library in {productName}. + +:standalone-server-type: default +:archiveType: war +:archiveName: {artifactId} +:restoreScriptName: restore-configuration.cli + +== What is it? + +https://micrometer.io[Micrometer] is a vendor-neutral facade that allows application developers to collect and report application and system metrics to the backend of their choice in an entirely portable manner. By simply replacing the `MeterRegistry` used, or combining them in Micrometer's `CompositeRegistry` data can be exported a variety of monitoring systems with no application code changes. + +== Architecture + +In this quickstart, we will build a small, simple application that shows the usage of a number of Micrometer's `Meter` implementations. We will also demonstrate the means by which {productName} exports the metrics data, which is via the https://opentelemetry.io/docs/reference/specification/protocol/otlp/[OpenTelemetry Protocol (OTLP)] to the https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]. To provide simpler access to the published metrics, the Collector will be configured with a Prometheus endpoint, from which we can scrape data. + +== Prerequisites + +To complete this guide, you will need: + +* less than 15 minutes +* JDK 11+ installed with `JAVA_HOME` configured appropriately +* Apache Maven 3.5.3+ +* Docker Compose, or alternatively Podman Compose + +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Steps + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +=== Configure the Server + +You enable Micrometer by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-micrometer.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-micrometer.cli` file in the root of this quickstart directory. This script adds the configuration that enables Micrometer for the quickstart components. Comments in the script describe the purpose of each block of commands. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-micrometer.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. You'll need to reload the configuration after that: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --commands=reload +---- + +[[start_opentelemetry_collector]] +=== Starting the OpenTelemetry Collector + +By default, {productName} will publish metrics every 10 seconds, so you will soon start seeing errors about a refused connection. + +This is because we told {productName} to publish to a server that is not there, so we need to fix that. To make that as simple as possible, you can use Docker Compose to start an instance of the OpenTelemetry Collector. + +The Docker Compose configuration file is `docker-compose.yaml`: + +[source,yaml] +---- +include::docker-compose.yaml[] +---- + +The Collector server configuration file is `otel-collector-config.yaml`: + +[source,yaml] +---- +include::otel-collector-config.yaml[] +---- + +We can now bring up the collector server instance: + +[source,bash] +---- +$ docker-compose up +---- + +The service should be available almost immediately, which you can verify by looking at the Prometheus endpoint we've configured by pointing your browser at http://localhost:1234/metrics[]. You should see quite a few metrics listed, none of which are what our application has registered. What you're seeing are the system and JVM metrics automatically registered and published by {productName} to give systems/applications administrators a comprehensive view of system health and performance. + +[NOTE] +==== +You may use Podman as alternative to Docker if you prefer, in such case the command should be `podman-compose up`. +==== + +[NOTE] +==== +If your environment does not support Docker or Podman, please refer to https://opentelemetry.io/docs/collector/installation[Otel Collector documentation] for alternatives on how to install and run the OpenTelemetry Collector. +==== + +=== Registering metrics + +Micrometer uses a programmatic approach to metrics definition, as opposed the more declarative, annotation-based approach of other libraries. Because of that, we need to explicitly register our `Meter` s before they can be used: + +[source,java] +---- +@Path("/") +@ApplicationScoped +public class RootResource { + // ... + @Inject + private MeterRegistry registry; + + private Counter performCheckCounter; + private Counter originalCounter; + private Counter duplicatedCounter; + + @PostConstruct + private void createMeters() { + Gauge.builder("prime.highestSoFar", () -> highestPrimeNumberSoFar) + .description("Highest prime number so far.") + .register(registry); + performCheckCounter = Counter + .builder("prime.performedChecks") + .description("How many prime checks have been performed.") + .register(registry); + originalCounter = Counter + .builder("prime.duplicatedCounter") + .tags(List.of(Tag.of("type", "original"))) + .register(registry); + duplicatedCounter = Counter + .builder("prime.duplicatedCounter") + .tags(List.of(Tag.of("type", "copy"))) + .register(registry); + } + // ... +} +---- + +Notice that we start by `@Inject` ing the `MeterRegistry`. This is a {productName}-managed instance, so all applications need to do it inject it and start using. Once we have that, we can use to build and register our meters, which we do in `@PostConstuct private void createMeters()` + +[NOTE] +==== +This must be done _post_-construction, as the `MeterRegistry` must be injected before it can be used to register the meters. +==== + +In this example, we register several different types to demonstrate their use. With those registered, we can start writing application logic: + +[source,java] +---- +@GET +@Path("/prime/{number}") +public String checkIfPrime(@PathParam("number") long number) throws Exception { + performCheckCounter.increment(); + + Timer timer = registry.timer("prime.timer"); + + return timer.recordCallable(() -> { + + if (number < 1) { + return "Only natural numbers can be prime numbers."; + } + + if (number == 1) { + return "1 is not prime."; + } + + if (number == 2) { + return "2 is prime."; + } + + if (number % 2 == 0) { + return number + " is not prime, it is divisible by 2."; + } + + for (int i = 3; i < Math.floor(Math.sqrt(number)) + 1; i = i + 2) { + try { + Thread.sleep(10); + } catch (InterruptedException e) { + // + } + if (number % i == 0) { + return number + " is not prime, is divisible by " + i + "."; + } + } + + if (number > highestPrimeNumberSoFar) { + highestPrimeNumberSoFar = number; + } + + return number + " is prime."; + }); +} +---- + +This method represents a simple REST endpoint that is able to determine whether the number passed as a path parameter is a prime number. + +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +=== Access the quickstart application + +You can either access the application via your browser at http://localhost:8080/micrometer/prime/13[], or from the command line: + +[source,bash] +---- +$ curl http://localhost:8080/micrometer/prime/13 +---- + +It should return a simple document: + +[source] +----- +13 is prime. +----- + +Once given enough time to allow {productName} to publish metrics updates, you now see your application's meters reported in the http://localhost:1234/metrics[Prometheus export]. You can also view them via the command-line: + +[source,bash] +---- +$ curl -s http://localhost:1234/metrics | grep "prime_" +# HELP prime_duplicatedCounter +# TYPE prime_duplicatedCounter counter +prime_duplicatedCounter{job="wildfly",type="copy"} 0 +prime_duplicatedCounter{job="wildfly",type="original"} 0 +# HELP prime_highestSoFar Highest prime number so far. +# TYPE prime_highestSoFar gauge +prime_highestSoFar{job="wildfly"} 13 +# HELP prime_performedChecks How many prime checks have been performed. +# TYPE prime_performedChecks counter +prime_performedChecks{job="wildfly"} 1 +# HELP prime_timer +# TYPE prime_timer histogram +prime_timer_bucket{job="wildfly",le="+Inf"} 1 +prime_timer_sum{job="wildfly"} 10.941035 +prime_timer_count{job="wildfly"} 1 + +---- + +Notice that all four meters registered in the `@PostConstruct` method as well as the `Timer` in our endpoint method have all been published. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +Micrometer provides a de facto standard way of capturing and publishing metrics to the monitoring solution of your choice. {productName} provides a convenient, out-of-the-box integration of Micrometer to make it easier to capture those metrics and monitor your application's health and performance. For more information on Micrometer, please refer to the project's https://micrometer.io[website]. diff --git a/micrometer/README.adoc b/micrometer/README.adoc index 3596ac0f89..9ee8cf9462 100644 --- a/micrometer/README.adoc +++ b/micrometer/README.adoc @@ -1,4 +1,205 @@ +<<<<<<< HEAD include::../shared-doc/attributes.adoc[] +======= +ifdef::env-github[] +:artifactId: micrometer +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 = micrometer: Micrometer QuickStart :author: Jason Lee @@ -31,12 +232,167 @@ To complete this guide, you will need: * Apache Maven 3.5.3+ * Docker Compose, or alternatively Podman Compose +<<<<<<< HEAD include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +======= +: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!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 == Steps // Start the {productName} Standalone Server +<<<<<<< HEAD include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +======= +:leveloffset: +1 + +[[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!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 [[configure_the_server]] === Configure the Server @@ -85,14 +441,66 @@ The Docker Compose configuration file is `docker-compose.yaml`: [source,yaml] ---- +<<<<<<< HEAD include::docker-compose.yaml[] +======= +version: "3" + +services: + otel-collector: + image: otel/opentelemetry-collector + command: [--config=/etc/otel-collector-config.yaml] + volumes: + - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:Z + ports: + - 1888:1888 # pprof extension + - 8888:8888 # Prometheus metrics exposed by the collector + - 8889:8889 # Prometheus exporter metrics + - 13133:13133 # health_check extension + - 4317:4317 # OTLP gRPC receiver + - 4318:4318 # OTLP http receiver + - 55679:55679 # zpages extension + - 1234:1234 # /metrics endpoint +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 ---- The Collector server configuration file is `otel-collector-config.yaml`: [source,yaml] ---- +<<<<<<< HEAD include::otel-collector-config.yaml[] +======= +extensions: + health_check: + pprof: + endpoint: 0.0.0.0:1777 + zpages: + endpoint: 0.0.0.0:55679 + +receivers: + otlp: + protocols: + grpc: + http: + +processors: + batch: + +exporters: + prometheus: + endpoint: "0.0.0.0:1234" + +service: + pipelines: + metrics: + receivers: [otlp] + processors: [batch] + exporters: [prometheus] + + extensions: [health_check, pprof, zpages] + +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 ---- We can now bring up the collector server instance: @@ -211,7 +619,118 @@ public String checkIfPrime(@PathParam("number") long number) throws Exception { This method represents a simple REST endpoint that is able to determine whether the number passed as a path parameter is a prime number. +<<<<<<< HEAD include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +======= +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 === Access the quickstart application @@ -255,6 +774,7 @@ prime_timer_count{job="wildfly"} 1 Notice that all four meters registered in the `@PostConstruct` method as well as the `Timer` in our endpoint method have all been published. // Server Distribution Testing +<<<<<<< HEAD include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] // Undeploy the Quickstart include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] @@ -270,6 +790,920 @@ endif::[] include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] // OpenShift include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +======= +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: +// Restore the {productName} Standalone Server Configuration +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: +// Restore the {productName} Standalone Server Configuration Manually +:leveloffset: +3 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +: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: ] + +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} +---- + +. 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::[] +// Bootable JAR +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: +// OpenShift +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: micrometer +deploy: + replicas: 1 + env: + - name: OTEL_COLLECTOR_HOST + value: "opentelemetrycollector" +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 == Conclusion diff --git a/micrometer/charts/helm.yaml b/micrometer/charts/helm.yaml index c0bbbce795..f87a7c0469 100644 --- a/micrometer/charts/helm.yaml +++ b/micrometer/charts/helm.yaml @@ -1,6 +1,10 @@ build: uri: https://github.com/wildfly/quickstart.git +<<<<<<< HEAD ref: main +======= + ref: 31.x +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 contextDir: micrometer deploy: replicas: 1 diff --git a/micrometer/pom.xml b/micrometer/pom.xml index 204b9f75ce..6d81bc16e0 100644 --- a/micrometer/pom.xml +++ b/micrometer/pom.xml @@ -10,24 +10,24 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 micrometer - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: micrometer - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 4.2.1.Final 10.0.0.Final - 5.0.0.Final + 6.0.0.Final diff --git a/microprofile-config/README-source.adoc b/microprofile-config/README-source.adoc new file mode 100644 index 0000000000..45d8a6454f --- /dev/null +++ b/microprofile-config/README-source.adoc @@ -0,0 +1,811 @@ +include::../shared-doc/attributes.adoc[] + += microprofile-config: MicroProfile Config QuickStart +:author: Martin Stefanko +:level: Beginner +:technologies: MicroProfile Config + +[abstract] +The `microprofile-config` quickstart demonstrates the use of the MicroProfile Config specification in {productName}. + +:standalone-server-type: microprofile +:archiveType: war +:archiveName: {artifactId} +:arq-prerequisities: These tests require that JBOSS_HOME environment variable is set. + +== What is it? + +MicroProfile Config allows users to externalize their configuration from their +application code. Users can modify the configuration from outside of the application +so they can change it without the need to rebuild their applications. It exposes the +configuration values to the application code through the CDI injection. + +== Architecture + +In this quickstart, we have a collection of CDI beans that expose functionalities of +the MicroProfile Config specification. The individual externally configured values +are provided to the users through a set of REST endpoints. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +== Solution + +We recommend that you follow the instructions that +<>. However, you can +also go right to the completed example which is available in this directory. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +[[creating-new-project]] +== Creating the Maven Project + +[source,options="nowrap"] +---- +mvn archetype:generate \ + -DgroupId=org.wildfly.quickstarts \ + -DartifactId=microprofile-config \ + -DinteractiveMode=false \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-webapp +cd microprofile-config +---- + +Open the project in your favourite IDE. + +Open the generated `pom.xml`: + +The first thing to do is to setup our dependencies. Add the following section to your +`pom.xml`: + +[source,xml,subs="attributes+"] +---- + + + + + org.wildfly.bom + wildfly-microprofile + {versionMicroprofileBom} + pom + import + + + +---- + +Now we need to add the following two dependencies: + +[source,xml] +---- + + + org.eclipse.microprofile.config + microprofile-config-api + provided + + + + jakarta.enterprise + jakarta.enterprise.cdi-api + provided + + + + jakarta.ws.rs + jakarta.ws.rs-api + provided + +---- + +NOTE: Because MicroProfile Config uses CDI injection to expose configuration values +to the user application we need to also include the CDI API dependency. + +All dependencies can have provided scope. + +As we are going to be deploying this application to the {productName} server, let's +also add a maven plugin that will simplify the deployment operations (you can replace +the generated build section): + +[source,xml] +---- + + + ${project.artifactId} + + + + org.wildfly.plugins + wildfly-maven-plugin + + + +---- + +// Setup required repositories +include::../shared-doc/setup-repositories.adoc[leveloffset=+1] + +As this is a Jakarta REST application we need to also create an application class. +Create `org.wildfly.quickstarts.microprofile.config.JaxRsApplication` with the following content: + +NOTE: The new file should be created in +`src/main/java/org/quickstarts/microprofile/config/JaxRsApplication.java`. + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config; + +import jakarta.ws.rs.ApplicationPath; +import jakarta.ws.rs.core.Application; + +@ApplicationPath("/") +public class JaxRsApplication extends Application { +} +---- + +Now we are ready to start working with MicroProfile Config. + +== Injecting a configuration value + +Let's start by creating a new CDI bean which will use for the injection of our +configuration values. This CDI bean will also be a JAX-RS resource. Create a new +class `org.wildfly.quickstarts.microprofile.config.ConfigResource`; + +To inject any configuration value, MicroProfile Config provides a custom qualifier +`ConfigProperty`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config; + +import org.eclipse.microprofile.config.inject.ConfigProperty; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; + +@Path("/config") +@ApplicationScoped +public class ConfigResource { + + @Inject + @ConfigProperty(name = "config.prop") + private String configValue; + + @GET + @Path("/value") + public String getValue() { + return configValue; + } +} +---- + +As you can see, we are injecting a `String` configuration value named `config.prop` +directly into our CDI bean (annotated with `@ApplicationScoped`) which is also at the +same time a REST endpoint. + +Let's try to deploy this application to the application server. There are several +ways of how you can specify the value of your configuration properties which the +specification calls config sources. By default each MicroProfile Config +implementation must provide at least three default config sources: + +* System properties +* Environment properties +* META-INF/microprofile-config.properties file + +If the same configuration value is defined by several config sources at the same +time, it is resolved based on the config sources priority. The default config +sources are prioritized in descending order (system properties, environment +properties, and microprofile-config.properties). So we look for the configuration +value in the environment properties only if we cannot find it in the system +properties. + +Now we can start configuring our application. As specified above, the lowest +ranking of the default config sources has the microprofile-config.properties file. +So let's create a new file in our +`src/main/resources/META-INF/microprofile-config.properties` with the following +content: + +[source,properties] +---- +config.prop=MyPropertyFileConfigValue +---- + +Now we can test our application correctly recognizes the configuration value: + +* Start your {productName} server + +* Package and deploy your application: + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +To check that the {productName} is working as expected: + +* access the `http://localhost:8080/microprofile-config/config/value` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/config/value` + +You will see that the returned value is our configured system property +`MyPropertyFileConfigValue`. + +As said above, there are three different default config sources. So far we have +seen only the `microprofile-config.properties` file which has the lowest priority. +Let's override our configuration value with an environment property which has +a bigger priority: + +* Stop you {productName} server + +* Set the environment propety `CONFIG_PROP` (the name is defined by the +specification): `export CONFIG_PROP=MyEnvPropConfigValue` + +* Start your {productName} server again + +* access the `http://localhost:8080/microprofile-config/config/value` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/config/value` + +You can see that our configuration value defined in the configuration file was +now overridden by the environment property and the value `MyEnvPropConfigValue` +is returned. + +The last default config source is the system properties which has the highest +priority: + +* Stop you {productName} server + +* Start your {productName} server with the `-Dconfig.prop=MySysPropConfigValue` + +* access the `http://localhost:8080/microprofile-config/config/value` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/config/value` + +The configuration property was overriden again and the value `MySysPropConfigValue` +is returned. + +We covered the basic injection and the default config sources provided by the +MicroProfile Config specification. Let's see what else the MicroProfile Config can +offer. + +== Different types of configuration injections and default values + +In our first example we injected a concrete `String` value: + +[source,java] +---- +@Inject +@ConfigProperty(name = "config.prop") +private String configValue; +---- + +The `ConfigProperty` qualifier contains one more optional parameter called the +`defaultValue`. As the name says, this parameter sets the default value if the +configuration property is not found in any of the config sources. + +To demonstrate how this works, let's define a new configuration property without +the default value: + +* Add the following code to `org.wildfly.quickstarts.microprofile.config.ConfigResource`: + +[source,java] +---- +@Inject +@ConfigProperty(name = "required.prop") +private String requiredProp; + +@GET +@Path("/required") +public String getRequiredProp() { + return requiredProp; +} +---- + +* Build and redeploy the application + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +The deployment will fail with the following error: + +``` +Caused by: org.jboss.weld.exceptions.DeploymentException: No Config Value exists for required property required.prop +``` + +because the required configuration property `required.prop` wasn't defined. Let's +fix this by providing a default value for this property if it's not found in any +of the config sources: + +[source,java] +---- +@Inject +@ConfigProperty(name = "required.prop", defaultValue = "Default required prop value") +private String requiredProp; +---- + +Build and redeploy the application + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +The application should now deploy without any errors and if access the +`http://localhost:8080/microprofile-config/config/required` endpoint +using your browser or +`curl http://localhost:8080/microprofile-config/config/required` you +will see the default value that we configured in the `ConfigProperty` qualifier. + +However, this is not the only way how you can deal with the situation when the +configuration value is not provided. MicroProfile Config allows you to define +different types of injections: + +* concrete values (String, int, double, ...) -- see the default converters later +* optional values (Optional) -- if the value is not found the specification +injects `Optional.empty()` so the application can still be successfully deployed +even if the configuration property is undefined +* always reloaded values (Provider) -- the value will be reevaluated with every +access (see later with custom config sources) + +Let's add a new configuration property `optional.prop` with the type +`Optional` and corresponding endpoint: + +[source,java] +---- +@Inject +@ConfigProperty(name = "optional.prop") +private Optional optionalString; + +@GET +@Path("/optional") +public String getOptionalValue() { + return optionalString.orElse("no optional value provided, use this as the default"); +} +---- + +Build and redeploy the application + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +If you now access the +`http://localhost:8080/microprofile-config/config/optional` endpoint +using your browser or +`curl http://localhost:8080/microprofile-config/config/optional` you +will get back the `orElse` value because the `optional.prop` was not defined +in our config sources. + +Last but not least, MicroProfile Config also allows you to inject the whole +configuration collected from all config sources as a single object instance of +the `Config` interface which provides a programmatic access to the configuration. +Add the following code to `org.wildfly.quickstarts.microprofile.config.ConfigResource`: + +[source,java] +---- +@Inject +private Config config; + +@GET +@Path("/all-props") +public String getConfigPropertyNames() { + return config.getPropertyNames().toString(); +} +---- + +Build and redeploy the application + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +Access the `http://localhost:8080/microprofile-config/config/all-props` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/config/all-props` and +you will see all available configuration property names. + +NOTE: You can investigate also the other methods of the `Config` interface. + +== Custom configuration sources + +MicroProfile Config allows you to define your own custom configuration sources +to extend the three default ones provided by the implementation. To define your +custom configuration source you need to provide a class which implements either +`org.eclipse.microprofile.config.spi.ConfigSource` or +`org.eclipse.microprofile.config.spi.ConfigSourceProvider` and define it through +the https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html[service file] +which will be detected and installed at application startup/deployment. + +Let's define a custom config source with some predefined values. First create +a new REST resource +`org.wildfly.quickstarts.microprofile.config.CustomConfigResource` which will be enclosing +our custom configurations: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config; + +import org.eclipse.microprofile.config.inject.ConfigProperty; + +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; + +@Path("/custom-config") +public class CustomConfigResource { + + @Inject + @ConfigProperty(name = "custom.config.source.prop") + private String customConfigSourceProp; + + @GET + @Path("/value") + public String getCustomConfigSourceProp() { + return customConfigSourceProp; + } +} +---- + +Let's now define a custom configuration source that will provide +`custom.config.source.prop` configuration property. Create a new class +`org.wildfly.quickstarts.microprofile.config.custom.CustomConfigSource`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config.custom; + +import org.eclipse.microprofile.config.spi.ConfigSource; + +import java.util.HashMap; +import java.util.Map; + +public class CustomConfigSource implements ConfigSource { + + private final Map properties; + + public CustomConfigSource() { + properties = new HashMap<>(); + properties.put("custom.config.source.prop", "MyCustomValue"); + } + + @Override + public Map getProperties() { + return properties; + } + + @Override + public String getValue(String propertyName) { + return properties.get(propertyName); + } + + @Override + public String getName() { + return "Custom Config Source with predefined values"; + } + + @Override + public int getOrdinal() { + return 400; + } +} +---- + +We only need to override the necessary methods required to get the properties and +to set the config source name. In this example, we also override the `getOrdinal` +method which sets the config source priority to be higher than any of the default +config sources. + +The last thing we need to do is to include our custom configuration source service +loader definition. Create +`src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSource` +with the following content: +`org.wildfly.quickstarts.microprofile.config.custom.CustomConfigSource`. + +Build and redeploy the application + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +If you now access the +`http://localhost:8080/microprofile-config/custom-config/value` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/custom-config/value` +you will get back the configuration value `MyCustomValue` defined in our custom +configuration source. + +If you would like to have a more programmatic approach to the definition of +different ``ConfigSource``s, you can use +`org.eclipse.microprofile.config.spi.ConfigSourceProvider`. Let's create a +`ConfigSourceProvider` that defines a dynamic `ConfigSource`. Create a new class +`org.wildfly.quickstarts.microprofile.config.custom.CustomPropertiesFileProvider`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config.custom; + +import org.eclipse.microprofile.config.spi.ConfigSource; +import org.eclipse.microprofile.config.spi.ConfigSourceProvider; + +import java.io.FileInputStream; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.Properties; +import java.util.stream.Collectors; + +public class CustomPropertiesFileProvider implements ConfigSourceProvider { + + @Override + public Iterable getConfigSources(ClassLoader forClassLoader) { + List configSources = new ArrayList<>(); + + configSources.add(new ConfigSource() { + @Override + public Map getProperties() { + return reloadPropertiesFile(); + } + + @Override + public String getValue(String propertyName) { + return reloadPropertiesFile().get(propertyName); + } + + @Override + public String getName() { + return "Custom dynamic configuration source"; + } + }); + + return configSources; + } + + private Map reloadPropertiesFile() { + Properties properties = new Properties(); + Path customPropertiesPath = Paths.get(System.getenv("JBOSS_HOME") + "/custom.properties"); + + if (!Files.exists(customPropertiesPath)) { + return new HashMap<>(); + } + + try (FileInputStream is = new FileInputStream(customPropertiesPath.toFile())) { + properties.load(is); + } catch (Exception e) { + throw new RuntimeException(e); + } + + return properties.entrySet().stream().collect( + Collectors.toMap( + entry -> entry.getKey().toString(), + entry -> entry.getValue().toString() + ) + ); + } +} +---- + +IMPORTANT: This requires that the `JBOSS_HOME` environment variable is set. + +NOTE: Note that our new custom `ConfigSource` reloads the property file on every +access. + +As you can see above, our custom configuration source is accessing a file +named `custom.properties` which needs to be created in your {productName} +root directory (`JBOSS_HOME`): + +[source,properties] +---- +custom.provided.prop=FileSystemCustomConfigValue +---- + +And as previously we need the service loader definition +`src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.ConfigSourceProvider` +with the content: +`org.wildfly.quickstarts.microprofile.config.custom.CustomPropertiesFileProvider`. + +Let's define a new endpoint for accessing this custom dynamic config source. +Add the following code to the +`org.wildfly.quickstarts.microprofile.config.CustomConfigResource`: + +[source,java] +---- +@Inject +@ConfigProperty(name = "custom.provided.prop", defaultValue = "default") +private Provider providedCustomProp; + +@GET +@Path("/reloaded-value") +public String providedCustomProp() { + return providedCustomProp.get(); +} +---- + +Note that we are now using `jakarta.inject.Provider` as an injected type. This means +that our value will be reloaded from config sources on every access. Since we are +reloading the property file from the file system on every access this allows us to +change the configuration dynamically without the need to restart the {productName} +server or to redeploy the application. + +Build and redeploy the application: + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +If you now access the +`http://localhost:8080/microprofile-config/custom-config/reloaded-value` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/custom-config/reloaded-value` +you will get back the configuration value `FileSystemCustomConfigValue` defined +in our custom configuration file. But if you now change the `custom.properties` +file (without stopping of the server or the need to redeploy the application) +and repeat the invocation at +`http://localhost:8080/microprofile-config/custom-config/reloaded-value` +you will see that the value is dynamically reloaded: + +* change `$JBOSS_HOME/custom.properties` (don't forget to save the file): + +[source,properties] +---- +custom.provided.prop=DynamicallyUpdatedValue +---- + +* repeat the invocation at +`http://localhost:8080/microprofile-config/custom-config/reloaded-value` + +You will see that the value `DynamicallyUpdatedValue` is returned. If you repeat +this with different values of `custom.provide.prop` it will always get reloaded. + +== Custom configuration converters + +The MicroProfile Config provides several default converters from the configuration +values which are typed as ``String``s (e.g. `int`, `Integer`, `Double`, `float`, ...). +However, you can also use your custom types as a configuration values. This can be +done by implementing +`org.eclipse.microprofile.config.spi.Converter` and adding its fully qualified +class name in the +`META-INF/services/org.eclipse.microprofile.config.spi.Converter` file. Let's create +a new class +`org.wildfly.quickstarts.microprofile.config.converter.type.MicroProfileCustomValue`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config.converter.type; + +public class MicroProfileCustomValue { + + private String name; + + public MicroProfileCustomValue(String name) { + this.name = name; + } + + public String getName() { + return name; + } +} +---- + +which represents our custom value and the corresponding +`Converter` implementation +`org.wildfly.quickstarts.microprofile.config.converter.MicroProfileCustomValueConverter`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config.converter; + +import org.eclipse.microprofile.config.spi.Converter; +import org.wildfly.quickstarts.microprofile.config.converter.type.MicroProfileCustomValue; + +public class MicroProfileCustomValueConverter implements Converter { + + @Override + public MicroProfileCustomValue convert(String value) { + return new MicroProfileCustomValue(value); + } +} +---- + +NOTE: Please note that your custom converter class must be public and must have a +public no-argument constructor. It also must not be abstract. + +Then you need to include the fully qualified class name of the converter in a +service file +`src/main/resources/META-INF/services/org.eclipse.microprofile.config.spi.Converter`: + +[source] +---- +org.wildfly.quickstarts.microprofile.config.converter.MicroProfileCustomValueConverter +---- + +After this is done you can use your custom type as a configuration value. Create +a new resource class `org.wildfly.quickstarts.microprofile.config.ConverterResource`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.config; + +import org.eclipse.microprofile.config.inject.ConfigProperty; +import org.wildfly.quickstarts.microprofile.config.converter.type.MicroProfileCustomValue; + +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; + +@Path("/converter") +public class ConverterResource { + + @Inject + @ConfigProperty(name = "custom.converter.prop") + private MicroProfileCustomValue microProfileCustomValue; + + @GET + @Path("/value") + public String customConverterProp() { + return microProfileCustomValue.getName(); + } +} +---- + +And define the `custom.converter.prop` in, for instance, +`microprofile-config.properties` file. + +[source,properties] +---- +custom.converter.prop=MyCustomConverterValue +---- + +Build and redeploy the application + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +And now you can access the +`http://localhost:8080/microprofile-config/converter/value` +endpoint using your browser or +`curl http://localhost:8080/microprofile-config/converter/value` to make use of the custom +converter. You will see the configured value which is taken from our created +`MicroProfileCustomValue` object. + +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// Openshift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +MicroProfile Config provides a way for your application to separate the configuration +from your application code which is a requirement for modern applications targeting +containers and cloud deployments. It allows you to adjust every aspect of the +configuration according to the application needs. The more information can be found +in the https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/microprofile-config-spec.asciidoc[MicroProfile config specification]. diff --git a/microprofile-config/README.adoc b/microprofile-config/README.adoc index 59130ade08..6de7fae595 100644 --- a/microprofile-config/README.adoc +++ b/microprofile-config/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-config +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-config: MicroProfile Config QuickStart :author: Martin Stefanko @@ -28,15 +225,184 @@ the MicroProfile Config specification. The individual externally configured valu are provided to the users through a set of REST endpoints. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: == Solution @@ -45,13 +411,163 @@ We recommend that you follow the instructions that also go right to the completed example which is available in this directory. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: [[creating-new-project]] == Creating the Maven Project @@ -139,7 +655,69 @@ the generated build section): ---- // Setup required repositories -include::../shared-doc/setup-repositories.adoc[leveloffset=+1] +:leveloffset: +1 + +Setup the required Maven repositories (if you don't have them set up in Maven global settings): + +[source,xml] +---- + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + default + + true + never + + + true + never + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + default + + true + never + + + true + never + + + + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + + true + + + true + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + + true + + + true + + + +---- + +:leveloffset!: As this is a Jakarta REST application we need to also create an application class. Create `org.wildfly.quickstarts.microprofile.config.JaxRsApplication` with the following content: @@ -798,10 +1376,492 @@ converter. You will see the configured value which is taken from our created `MicroProfileCustomValue` object. // Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // Openshift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: microprofile-config +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[] + + +[[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 + +// 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 + +:leveloffset!: == Conclusion diff --git a/microprofile-config/charts/helm.yaml b/microprofile-config/charts/helm.yaml index c32c42525c..4c84f77028 100644 --- a/microprofile-config/charts/helm.yaml +++ b/microprofile-config/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-config deploy: replicas: 1 \ No newline at end of file diff --git a/microprofile-config/pom.xml b/microprofile-config/pom.xml index f20f2cd58d..49fc2b9471 100644 --- a/microprofile-config/pom.xml +++ b/microprofile-config/pom.xml @@ -8,19 +8,19 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-config - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-config - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} diff --git a/microprofile-fault-tolerance/README-source.adoc b/microprofile-fault-tolerance/README-source.adoc new file mode 100644 index 0000000000..19cdf30bd6 --- /dev/null +++ b/microprofile-fault-tolerance/README-source.adoc @@ -0,0 +1,639 @@ +//// +This guide is adapted from the main Quarkus repository +https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc +//// + +// Needed to correctly render on GitHub +:productName: WildFly +:standalone-server-type: microprofile + +include::../shared-doc/attributes.adoc[] + += microprofile-fault-tolerance: MicroProfile Fault Tolerance +:author: Radoslav Husar, Tomas Hofman +:level: Intermediate +:technologies: MicroProfile, Fault Tolerance + +[abstract] +The `microprofile-fault-tolerance` quickstart demonstrates how to use Eclipse MicroProfile Fault Tolerance in {productName}. + +One of the challenges brought by the distributed nature of microservices is that communication with external systems is +inherently unreliable. This increases demand on resiliency of applications. To simplify making more resilient +applications, {productName} contains an implementation of the MicroProfile Fault Tolerance specification. + +In this guide, we demonstrate usage of MicroProfile Fault Tolerance annotations such as `@Timeout`, `@Fallback`, +`@Retry` and `@CircuitBreaker`. The specification also introduces `@Bulkhead` and `@Asynchronous` interceptor bindings not +covered in this guide. + +== Scenario + +The application built in this guide simulates a simple backend for a gourmet coffee on-line store. It implements a REST +endpoint providing information about coffee samples we have in store. + +Let's imagine, although it's not implemented as such, that some methods in our endpoint require communication +to external services like a database or an external microservice, which introduces a factor of unreliability. +This is simulated in our code by intentionally throwing exceptions with certain probability. Then we use +the MicroProfile Fault Tolerance annotations to overcome these failures. + +== Solution + +We recommend that you follow the instructions that +<>. However, you can +also <> which is available in this directory. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[project-from-scratch]] +== Creating an Application from Scratch + +In this section we will go through the steps to create a new JAX-RS deployment from scratch and then make it more +resilient by using MicroProfile Fault Tolerance annotations. + +=== Project Generation + +First, we need to generate a maven project. Open a terminal and create an empty maven project with following command: + +[source] +---- +mvn archetype:generate \ + -DgroupId=org.wildfly.quickstarts.microprofile.faulttolerance \ + -DartifactId=microprofile-fault-tolerance \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-webapp \ + -DinteractiveMode=false +cd microprofile-fault-tolerance +---- + +Now, open the project in your favorite IDE. + +=== pom.xml Updates + +Next the project's `pom.xml` should be updated so the dependencies required by this quickstart are +available and so we have a plug-in installed which can deploy the quickstart directly to {productName}. + +Add the following properties to the `pom.xml`: + +[source,options="nowrap",subs="attributes+"] +---- +{versionMicroprofileBom} +{versionServerBom} +---- + +Also the project can be updated to use Java 8 as the minimum: + +[source,options="nowrap"] +---- +1.8 +1.8 +---- + +Before the dependencies are defined add the following boms: + +[source,xml,subs="attributes+"] +---- + + + + + org.wildfly.bom + wildfly-ee-with-tools + {versionServerBom} + pom + import + + + + org.wildfly.bom + wildfly-microprofile + {versionMicroprofileBom} + pom + import + + + +---- + +By using boms the majority of dependencies used within this quickstart align with the version uses by the application server. + +The following dependencies can now be added to the project. + +[source,xml] +---- + + + org.eclipse.microprofile.fault-tolerance + microprofile-fault-tolerance-api + provided + + + jakarta.enterprise + jakarta.enterprise.cdi-api + provided + + + org.jboss.resteasy + resteasy-jaxrs + provided + + + org.jboss.logging + jboss-logging + provided + + +---- + +Note that all dependencies have the scope `provided`. + +As we are going to be deploying this application to the {productName} server, let's +also add a maven plugin that will simplify working with the application server. +Add the following section under configuration: + +[source,xml] +---- + + + ... + + org.wildfly.plugins + wildfly-maven-plugin + + + +---- + +// Setup required repositories +include::../shared-doc/setup-repositories.adoc[leveloffset=+1] + +Now we are ready to start developing an application with MicroProfile Fault Tolerance capabilities. + + +=== Preparing an Application: REST Endpoint and CDI Bean + +In this section we create a skeleton of our application, so that we have something that we can extend and to which +we can add fault tolerance features later on. + +First, create a simple entity representing a coffee sample in our store: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.faulttolerance; + +public class Coffee { + + public Integer id; + public String name; + public String countryOfOrigin; + public Integer price; + + public Coffee() { + } + + public Coffee(Integer id, String name, String countryOfOrigin, Integer price) { + this.id = id; + this.name = name; + this.countryOfOrigin = countryOfOrigin; + this.price = price; + } +} +---- + +Now, lets expose our JAX-RS application at the context path: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.faulttolerance; + +import jakarta.ws.rs.ApplicationPath; +import jakarta.ws.rs.core.Application; + +@ApplicationPath("/") +public class CoffeeApplication extends Application { +} +---- + +Let's continue with a simple CDI bean, that would work as a repository of our coffee samples. + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.faulttolerance; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.stream.Collectors; +import jakarta.enterprise.context.ApplicationScoped; + +@ApplicationScoped +public class CoffeeRepositoryService { + + private Map coffeeList = new HashMap<>(); + + public CoffeeRepositoryService() { + coffeeList.put(1, new Coffee(1, "Fernandez Espresso", "Colombia", 23)); + coffeeList.put(2, new Coffee(2, "La Scala Whole Beans", "Bolivia", 18)); + coffeeList.put(3, new Coffee(3, "Dak Lak Filter", "Vietnam", 25)); + } + + public List getAllCoffees() { + return new ArrayList<>(coffeeList.values()); + } + + public Coffee getCoffeeById(Integer id) { + return coffeeList.get(id); + } + + public List getRecommendations(Integer id) { + if (id == null) { + return Collections.emptyList(); + } + return coffeeList.values().stream() + .filter(coffee -> !id.equals(coffee.id)) + .limit(2) + .collect(Collectors.toList()); + } +} +---- + +Finally, create the `org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource` class as follows: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.faulttolerance; + +import java.util.List; +import java.util.Random; +import java.util.concurrent.atomic.AtomicLong; +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; + +import org.jboss.logging.Logger; + +@Path("/coffee") +@Produces(MediaType.APPLICATION_JSON) +public class CoffeeResource { + + private static final Logger LOGGER = Logger.getLogger(CoffeeResource.class); + + @Inject + private CoffeeRepositoryService coffeeRepository; + + private AtomicLong counter = new AtomicLong(0); + + @GET + public List coffees() { + final Long invocationNumber = counter.getAndIncrement(); + + maybeFail(String.format("CoffeeResource#coffees() invocation #%d failed", invocationNumber)); + + LOGGER.infof("CoffeeResource#coffees() invocation #%d returning successfully", invocationNumber); + return coffeeRepository.getAllCoffees(); + } + + private void maybeFail(String failureLogMessage) { + if (new Random().nextBoolean()) { + LOGGER.error(failureLogMessage); + throw new RuntimeException("Resource failure."); + } + } +} +---- + +At this point, we expose a single REST method that will show a list of coffee samples in a JSON format. Note +that we introduced some fault making code in our `CoffeeResource#maybeFail()` method, which is going to cause failures +in the `CoffeeResource#coffees()` endpoint method in about 50% of requests. + +=== Build and Deploy the Initial Application +Let's check that our application works! + +. Make sure xref:start_the_eap_standalone_server[the {productName} server is started] as described above. +. Open new terminal and navigate to the root directory of your project. +. Type the following command to build and deploy the project: ++ +[source,shell] +---- +mvn clean package wildfly:deploy +---- + +Then, open `http://localhost:8080/microprofile-fault-tolerance/coffee` in your browser and make a couple of requests. +Some requests should show us the list of our coffee samples in JSON, the rest will fail +with a `RuntimeException` thrown in `CoffeeResource#maybeFail()`. + +[[adding_resiliency_retries]] +=== Adding Resiliency: Retries + +Let the {productName} server running and in your IDE add the `@Retry` annotation to the `CoffeeResource#coffees()` +method as follows and save the file: + +[source,java] +---- +import org.eclipse.microprofile.faulttolerance.Retry; +... + +public class CoffeeResource { + ... + @GET + @Retry(maxRetries = 4) + public List coffees() { + ... + } + ... +} +---- + +Rebuild and redeploy the application in {productName} server: + +[source,shell] +---- +mvn wildfly:deploy +---- + +You can reload the page couple more times. Practically all requests should now be succeeding. The `CoffeeResource#coffees()` +method is still in fact failing in about 50% of cases, but every time it happens the platform automatically retries +the call! + +To see that the failures still happen, check the output of the development server. The log messages should be +similar to these: + +[source] +---- +18:29:20,901 ERROR [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#coffees() invocation #0 failed +18:29:20,901 INFO [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#coffees() invocation #1 returning successfully +18:29:21,315 ERROR [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#coffees() invocation #0 failed +18:29:21,337 ERROR [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#coffees() invocation #1 failed +18:29:21,502 ERROR [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#coffees() invocation #2 failed +18:29:21,654 INFO [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#coffees() invocation #3 returning successfully +---- + +You can see that every time an invocation fails, it's immediately followed by another invocation, until one succeeds. +Since we allowed 4 retries, it would require 5 invocations to fail in a row, in order for the user to be actually exposed +to a failure. That is fairly unlikely to happen. + +[[adding_resiliency_timeouts]] +=== Adding Resiliency: Timeouts + +So what else have we got in MicroProfile Fault Tolerance? Let's look into timeouts. + +Add following two methods to our `CoffeeResource` endpoint and deploy onto the running server. + +[source,java] +---- +import org.jboss.resteasy.annotations.jaxrs.PathParam; +import org.eclipse.microprofile.faulttolerance.Timeout; +... +public class CoffeeResource { + ... + @GET + @Path("/{id}/recommendations") + @Timeout(250) + public List recommendations(@PathParam("id") int id) { + long started = System.currentTimeMillis(); + final long invocationNumber = counter.getAndIncrement(); + + try { + randomDelay(); + LOGGER.infof("CoffeeResource#recommendations() invocation #%d returning successfully", invocationNumber); + return coffeeRepository.getRecommendations(id); + } catch (InterruptedException e) { + LOGGER.errorf("CoffeeResource#recommendations() invocation #%d timed out after %d ms", + invocationNumber, System.currentTimeMillis() - started); + return null; + } + } + + private void randomDelay() throws InterruptedException { + Thread.sleep(new Random().nextInt(500)); + } +} +---- + +Rebuild and redeploy the application: + +[source,shell] +---- +mvn wildfly:deploy +---- + +We added some new functionality. We want to be able to recommend some related coffees based on a coffee that a user +is currently looking at. It's not a critical functionality, it's a nice-to-have. When the system is overloaded, and the +logic behind obtaining recommendations takes too long to execute, we would rather time out and render the UI without +recommendations. + +Note that the timeout was configured to 250 ms, and a random artificial delay between 0 and 500 ms was introduced +into the `CoffeeResource#recommendations()` method. + +In your browser, go to `http://localhost:8080/microprofile-fault-tolerance/coffee/2/recommendations` and hit reload a couple of times. + +You should see some requests time out with `org.eclipse.microprofile.faulttolerance.exceptions.TimeoutException`. +Requests that do not time out should show two recommended coffee samples in JSON. + +[[adding_resiliency_fallbacks]] +=== Adding Resiliency: Fallbacks + +Let's improve the recommendations feature by providing a fallback functionality for the case when a timeout happens. + +Add a fallback method to `CoffeeResource` and a `@Fallback` annotation to `CoffeeResource#recommendations()` method +as follows: + +[source,java] +---- +import java.util.Collections; +import org.eclipse.microprofile.faulttolerance.Fallback; +... +public class CoffeeResource { + ... + @Fallback(fallbackMethod = "fallbackRecommendations") + public List recommendations(@PathParam("id") int id) { + ... + } + + public List fallbackRecommendations(int id) { + LOGGER.info("Falling back to RecommendationResource#fallbackRecommendations()"); + // safe bet, return something that everybody likes + return Collections.singletonList(coffeeRepository.getCoffeeById(1)); + } + ... +} +---- + +Rebuild and redeploy the application. + +Hit reload several times on `http://localhost:8080/microprofile-fault-tolerance/coffee/2/recommendations`. +The `TimeoutException` should not appear anymore. Instead, in case of a timeout, the page will +display a single recommendation that we hardcoded in our fallback method `fallbackRecommendations()`, rather than +two recommendations returned by the original method. + +Check the server output to see that fallback is really happening: + +[source] +---- +18:36:01,873 INFO [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#recommendations() invocation #0 returning successfully +18:36:02,705 ERROR [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) CoffeeResource#recommendations() invocation #0 timed out after 253 ms +18:36:02,706 INFO [org.wildfly.quickstarts.microprofile.faulttolerance.CoffeeResource] (default task-3) Falling back to RecommendationResource#fallbackRecommendations() +---- + +NOTE: The fallback method is required to have the same parameters as the original method. + +[[adding_resiliency_circuit_breakers]] +=== Adding Resiliency: Circuit Breakers + +A circuit breaker is useful for limiting number of failures happening in the system, when part of the system becomes +temporarily unstable. The circuit breaker records successful and failed invocations of a method, and when the ratio +of failed invocations reaches the specified threshold, the circuit breaker _opens_ and blocks all further invocations +of that method for a given time. + +Add the following code into the `CoffeeRepositoryService` bean, so that we can demonstrate a circuit breaker in action: + +[source,java] +---- +import java.util.concurrent.atomic.AtomicLong; +import org.eclipse.microprofile.faulttolerance.CircuitBreaker; +... + +public class CoffeeRepositoryService { + ... + + private AtomicLong counter = new AtomicLong(0); + + @CircuitBreaker(requestVolumeThreshold = 4) + public Integer getAvailability(Coffee coffee) { + maybeFail(); + return new Random().nextInt(30); + } + + private void maybeFail() { + // introduce some artificial failures + final Long invocationNumber = counter.getAndIncrement(); + if (invocationNumber % 4 > 1) { // alternate 2 successful and 2 failing invocations + throw new RuntimeException("Service failed."); + } + } +} +---- + +and inject the code below into the `CoffeeResource` endpoint: + +[source,java] +---- +public class CoffeeResource { + ... + @Path("/{id}/availability") + @GET + public Response availability(@PathParam("id") int id) { + final Long invocationNumber = counter.getAndIncrement(); + + Coffee coffee = coffeeRepository.getCoffeeById(id); + // check that coffee with given id exists, return 404 if not + if (coffee == null) { + return Response.status(Response.Status.NOT_FOUND).build(); + } + + try { + Integer availability = coffeeRepository.getAvailability(coffee); + LOGGER.infof("CoffeeResource#availability() invocation #%d returning successfully", invocationNumber); + return Response.ok(availability).build(); + } catch (RuntimeException e) { + String message = e.getClass().getSimpleName() + ": " + e.getMessage(); + LOGGER.errorf("CoffeeResource#availability() invocation #%d failed: %s", invocationNumber, message); + return Response.status(Response.Status.INTERNAL_SERVER_ERROR) + .entity(message) + .type(MediaType.TEXT_PLAIN_TYPE) + .build(); + } + } + ... +} +---- + +Rebuild and redeploy the application. + +We added another functionality - the application can return the amount of remaining packages of given coffee on our store +(just a random number). + +This time an artificial failure was introduced in the CDI bean: the `CoffeeRepositoryService#getAvailability()` method is +going to alternate between two successful and two failed invocations. + +We also added a `@CircuitBreaker` annotation with `requestVolumeThreshold = 4`. `CircuitBreaker.failureRatio` is +by default 0.5, and `CircuitBreaker.delay` is by default 5 seconds. That means that a circuit breaker will open +when 2 of the last 4 invocations failed. It will stay open for 5 seconds. + +To test this out, do the following: + +1. Go to `http://localhost:8080/microprofile-fault-tolerance/coffee/2/availability` in your browser. You should see a number being returned. +2. Hit reload, this second request should again be successful and return a number. +3. Reload two more times. Both times you should see text "RuntimeException: Service failed.", which is the exception +thrown by `CoffeeRepositoryService#getAvailability()`. +4. Reload a couple more times. Unless you waited too long, you should again see exception, but this time it's +"CircuitBreakerOpenException: getAvailability". This exception indicates that the circuit breaker opened, +and the `CoffeeRepositoryService#getAvailability()` method is not being called anymore. +5. Give it 5 seconds during which circuit breaker should close. You should be able to make two successful requests +again. + +[[working_with_the_completed_quickstart]] +== Working with the Completed Quickstart + +This section shows how to work with the complete quickstart. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Test the Deployed Application + +You can visit following URLs in your browser: + +* ++ +This URL should almost always return a response with JSON data. Even though internally the endpoint fails +in about 50% of cases (you can see those errors in the server log), it uses automatic retries to mitigate these +failures. ++ +See details in the section <>. + +* http://localhost:8080/microprofile-fault-tolerance/coffee/1/recommendations ++ +This endpoint also fails in about 50% of cases, but it uses fallback strategy to provide an alternative response if +normal processing failed. As a result the response will either contain a JSON list with several items in it +(a successful response) or just a single item in it (a fallback response). ++ +See details in sections <> +and <>. + + +* http://localhost:8080/microprofile-fault-tolerance/coffee/1/availability ++ +This endpoint demonstrates the use of a circuit breaker. It returns a sequence of two successful responses, followed by +a sequence of two failed ones. After that, the circuit breaker will open and will block all +further request processing for the duration of 5 seconds. ++ +See details in the section <>. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +MicroProfile Fault Tolerance allows improving resiliency of your application, without having an impact on the complexity +of our business logic. diff --git a/microprofile-fault-tolerance/README.adoc b/microprofile-fault-tolerance/README.adoc index 89ece6e475..f4416584cf 100644 --- a/microprofile-fault-tolerance/README.adoc +++ b/microprofile-fault-tolerance/README.adoc @@ -1,3 +1,7 @@ +ifdef::env-github[] +:artifactId: microprofile-fault-tolerance +endif::[] + //// This guide is adapted from the main Quarkus repository https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc @@ -8,7 +12,200 @@ https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc :standalone-server-type: microprofile :portedToGlow: true -include::../shared-doc/attributes.adoc[] +//*********************************************************************************** +// 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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-fault-tolerance: MicroProfile Fault Tolerance :author: Radoslav Husar, Tomas Hofman @@ -43,15 +240,184 @@ We recommend that you follow the instructions that also <> which is available in this directory. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[project-from-scratch]] == Creating an Application from Scratch @@ -173,7 +539,69 @@ Add the following section under configuration: ---- // Setup required repositories -include::../shared-doc/setup-repositories.adoc[leveloffset=+1] +:leveloffset: +1 + +Setup the required Maven repositories (if you don't have them set up in Maven global settings): + +[source,xml] +---- + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + default + + true + never + + + true + never + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + default + + true + never + + + true + never + + + + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + + true + + + true + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + + true + + + true + + + +---- + +:leveloffset!: Now we are ready to start developing an application with MicroProfile Fault Tolerance capabilities. @@ -590,7 +1018,114 @@ again. This section shows how to work with the complete quickstart. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Test the Deployed Application @@ -623,16 +1158,541 @@ further request processing for the duration of 5 seconds. See details in the section <>. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: microprofile-fault-tolerance +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[] + + +[[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 + +// 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 + +:leveloffset!: == Conclusion diff --git a/microprofile-fault-tolerance/charts/helm.yaml b/microprofile-fault-tolerance/charts/helm.yaml index 88695c5b84..b52d7ef2fb 100644 --- a/microprofile-fault-tolerance/charts/helm.yaml +++ b/microprofile-fault-tolerance/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-fault-tolerance deploy: replicas: 1 diff --git a/microprofile-fault-tolerance/pom.xml b/microprofile-fault-tolerance/pom.xml index b6a412f7f4..cb7d267b7b 100644 --- a/microprofile-fault-tolerance/pom.xml +++ b/microprofile-fault-tolerance/pom.xml @@ -26,11 +26,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-fault-tolerance - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-fault-tolerance @@ -53,7 +53,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} diff --git a/microprofile-health/README-source.adoc b/microprofile-health/README-source.adoc new file mode 100644 index 0000000000..be7fdd02ab --- /dev/null +++ b/microprofile-health/README-source.adoc @@ -0,0 +1,468 @@ +include::../shared-doc/attributes.adoc[] + += microprofile-health: MicroProfile Health QuickStart +:author: Martin Stefanko +:level: Beginner +:technologies: MicroProfile Health +:management-port-openshift: +:post-helm-install-actions: ../microprofile-health/expose-management-port.adoc +:extra-openshift-testing-actions: ../microprofile-health/expose-management-port.adoc +:extra-openshift-test-arguments: -Dserver.management.host=https://$(oc get route {artifactId}-management --template='{{ .spec.host }}') + +[abstract] +The `microprofile-health` quickstart demonstrates the use of the MicroProfile Health specification in {productName}. + +:standalone-server-type: microprofile +:archiveType: war +:archiveName: {artifactId} +:include-management-port: http://localhost:9990/health/live + +== What is it? + +MicroProfile Health allows applications to provide information about their state +to external viewers which is typically useful in cloud environments where automated +processes must be able to determine whether the application should be discarded +or restarted. + +== Architecture + +In this quickstart, we have a simple REST application that exposes MicroProfile Health +functionalities at the `/health/live`, `/health/ready`, and `/health/started` endpoints according to the specification. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +== Solution + +We recommend that you follow the instructions that +<>. However, you can +also go right to the completed example which is available in this directory. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +=== Running the health check + +The {productName} server directly exposes three REST endpoints: + +- `/health/live` - The application is up and running. +- `/health/ready` - The application is ready to serve requests. +- `/health/started` - The application is started allowing switch to liveness check. +- `/health` - Accumulating all health check procedures in the application. + +To check that the {productName} is working as expected: + +* access the `http://localhost:9990/health/live` endpoint using your browser or +`curl http://localhost:9990/health/live` + +All of the health REST endpoints return a simple JSON object with two fields: + +* `status` -- the overall result of all the health check procedures +* `checks` -- an array of individual checks + +The general `status` of the health check is computed as a logical AND of all the +declared health check procedures. + +NOTE: Similarly, you can access `http://localhost:9990/health/ready`, +`http://localhost:9990/health/started`, and `http://localhost:9990/health` + +Congratulations! You successfully deployed and run this quickstart. If you wish to +create the application step by step you can follow the subsequent sections. + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +[[creating-new-project]] +== Creating the Maven Project + +[source,options="nowrap"] +---- +mvn archetype:generate \ + -DgroupId=org.wildfly.quickstarts \ + -DartifactId=microprofile-health \ + -DinteractiveMode=false \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-quickstart +cd microprofile-health +---- + +Open the project in your favourite IDE. + +Open the generated `pom.xml`. + +The first thing to do is to change the packaging to `war` as this is required by +the IDEs to recognize the application as a deployment: + +[source,xml] +---- +war +---- + +NOTE: For non-IDE deployments, the plain `jar` packaging is sufficient for +the MicroProfile Health applications. + +Next we need to setup our dependencies. Add the following section to your +`pom.xml`: + +[source,xml,subs="attributes+"] +---- + + + + + org.wildfly.bom + wildfly-microprofile + {versionMicroprofileBom} + pom + import + + + +---- + +Now we need to add the following two dependencies: + +[source,xml] +---- + + + org.eclipse.microprofile.health + microprofile-health-api + provided + + + + jakarta.enterprise + jakarta.enterprise.cdi-api + provided + +---- + +NOTE: Because MicroProfile Health requires that all health checks are defined as +CDI beans we need to also include the CDI API dependency. + +Both dependencies can have provided scope. The versions are taken from the above +defined BOM. + +As we are going to be deploying this application to the {productName} server, let's +also add a maven plugin that will simplify the deployment operations (you can replace +the generated build section): + +[source,xml] +---- + + + ${project.artifactId} + + + + org.wildfly.plugins + wildfly-maven-plugin + + + +---- + +// Setup required repositories +include::../shared-doc/setup-repositories.adoc[leveloffset=+1] + +Now we are ready to start working with MicroProfile Health. + +== Creating your first health check + +In this section, we create our first simple health check procedure. + +Create the `org.wildfly.quickstarts.microprofile.health.SimpleHealthCheck` class: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.health; + +import org.eclipse.microprofile.health.HealthCheck; +import org.eclipse.microprofile.health.HealthCheckResponse; +import org.eclipse.microprofile.health.Liveness; + +import jakarta.enterprise.context.ApplicationScoped; + +@Liveness +@ApplicationScoped +public class SimpleHealthCheck implements HealthCheck { + + @Override + public HealthCheckResponse call() { + return HealthCheckResponse.up("Simple health check"); + } +} +---- + +As you can see health check procedures are defined as implementations of the +`HealthCheck` interface which are defined as CDI beans with the one of the +following CDI qualifiers: + +- `@Liveness` - the liveness check accessible at `/health/live` +- `@Readiness` - the readiness check accessible at `/health/ready` +- `@Startup` - the readiness check accessible at `/health/started` + +`HealthCheck` is a functional interface whose single method `call` returns a +`HealthCheckResponse` object which can be easily constructed by the fluent builder +API shown in the example. + +Now it's time to build and deploy our application that contains this health check +to the {productName} server. + +WARN: Make sure your {productName} server is started. + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +Now we can simply repeat the request +to `http://localhost:9990/health/live` by refreshing your browser window or by +using `curl http://localhost:9990/health/live`. Because we defined our health check +to be a liveness procedure (with `@Liveness` qualifier) the new health check procedure +is now present in the `checks` array. + +Congratulations! You've created your first health check procedure. Let's +continue by exploring what else can be done with the MicroProfile Health specification. + +== Adding a readiness health check procedure + +In the previous section, we created a simple liveness health check procedure which +states whether our application is running or not. In this section, we will create a +readiness health check which will be able to state whether our application is able to +process requests. + +We will create another health check procedure that simulates a connection to +an external service provider such as a database. For starters, we will always return +the response indicating the application is ready. + +Create `org.wildfly.quickstarts.microprofile.health.DatabaseConnectionHealthCheck` class: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.health; + +import org.eclipse.microprofile.health.HealthCheck; +import org.eclipse.microprofile.health.HealthCheckResponse; +import org.eclipse.microprofile.health.Readiness; + +import jakarta.enterprise.context.ApplicationScoped; + +@Readiness +@ApplicationScoped +public class DatabaseConnectionHealthCheck implements HealthCheck { + + @Override + public HealthCheckResponse call() { + return HealthCheckResponse.up("Database connection health check"); + } +} +---- + +Now you can redeploy your application: + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +If you now rerun the health check at `http://localhost:9990/health/live` the `checks` +array will contain only the previously defined `SimpleHealthCheck` as it is the only +check defined with the `@Liveness` qualifier. However, if you access +`http://localhost:9990/health/ready` (in the browser or with +`curl http://localhost:9990/health/ready`) you will see only the +`Database connection health check` as it is the only health check defined with the +`@Readiness` qualifier as the readiness health check procedure. + +NOTE: If you access `http://localhost:9990/health` you will get back both checks. + +More information about which health check procedures should be used in which situation +is detailed in the MicroProfile Health specification. Generally, the liveness +procedures determine whether the application should be restarted while readiness +procedures determine whether it makes sense to contact the application with requests. + +== Startup health checks + +Startup health checks are used in cloud environments to define checks that should respond +UP before the liveness checks start to be called. This is useful in cases of slow container +startups so the container won't get prematurely restarted if liveness is called before the +container is fully initialized. These checks are defined in the same way as liveness or +readiness checks but with the `@Startup` CDI qualifier. The HTTP endpoint exposed for the +startup checks is available at `/health/started`. For simplicity, we will not include code +example in this quickstart. + +== Negative health check procedures + +In this section, we extend our `Database connection health check` with the option of +stating that our application is not ready to process requests as the underlying +database connection cannot be established. For simplicity reasons, we only determine +whether the database is accessible or not by a configuration property. + +To use MicroProfile Config configuration values we first need to add the Config API +dependency to our application: + +[source,xml] +---- + + + org.eclipse.microprofile.config + microprofile-config-api + provided + +---- + +Update the `org.wildfly.quickstarts.microprofile.health.DatabaseConnectionHealthCheck` class: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.health; + +import org.eclipse.microprofile.config.inject.ConfigProperty; +import org.eclipse.microprofile.health.HealthCheck; +import org.eclipse.microprofile.health.HealthCheckResponse; +import org.eclipse.microprofile.health.HealthCheckResponseBuilder; +import org.eclipse.microprofile.health.Readiness; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; + +@Readiness +@ApplicationScoped +public class DatabaseConnectionHealthCheck implements HealthCheck { + + @Inject + @ConfigProperty(name = "database.up", defaultValue = "false") + private boolean databaseUp; + + @Override + public HealthCheckResponse call() { + + HealthCheckResponseBuilder responseBuilder = HealthCheckResponse.named("Database connection health check"); + + try { + simulateDatabaseConnectionVerification(); + responseBuilder.up(); + } catch (IllegalStateException e) { + // cannot access the database + responseBuilder.down(); + } + + return responseBuilder.build(); + } + + private void simulateDatabaseConnectionVerification() { + if (!databaseUp) { + throw new IllegalStateException("Cannot contact database"); + } + } +} +---- + +Redeploy your application: + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +If you now rerun the readiness health check (at `http://localhost:9990/health/ready`) +the overall `status` should be DOWN. You can also check the liveness check at +`http://localhost:9990/health/live` which will return the overall `status` UP because +it isn't influenced by the readiness checks. + +As we shouldn't leave this application with a readiness check in a DOWN state you can +add `database.up=true` in `src/main/resources/META-INF/microprofile-config.properties` +and redeploy the application. The readiness health check should be up again. + + +== Adding user-specific data to the health check response + +In previous sections, we saw how to create simple health checks with only the minimal +attributes, namely, the health check name and its status (UP or DOWN). However, the +MicroProfile specification also provides a way for the applications to supply +arbitrary data in the form of key-value pairs sent to the consuming end. This can be +done by using the `withData(key, value)` method of the health check response +builder API. + +Let's create a new health check procedure +`org.wildfly.quickstarts.microprofile.health.DataHealthCheck`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.health; + +import org.eclipse.microprofile.health.Liveness; +import org.eclipse.microprofile.health.HealthCheck; +import org.eclipse.microprofile.health.HealthCheckResponse; + +import jakarta.enterprise.context.ApplicationScoped; + +@Liveness +@ApplicationScoped +public class DataHealthCheck implements HealthCheck { + + @Override + public HealthCheckResponse call() { + return HealthCheckResponse.named("Health check with data") + .up() + .withData("foo", "fooValue") + .withData("bar", "barValue") + .build(); + } +} +---- + +If you redeploy and rerun the liveness health check procedure by accessing the +`/health/live` endpoint you can see that the new health check `Health check with data` +is present in the `checks` array. This check contains a new attribute called `data` +which is a JSON object consisting of the properties we have defined in our health +check procedure. + +This functionality is specifically useful in failure scenarios where you can pass the +error along with the health check response. + + +[source,java] +---- + try { + simulateDatabaseConnectionVerification(); + responseBuilder.up(); + } catch (IllegalStateException e) { + // cannot access the database + responseBuilder.down() + .withData("error", e.getMessage()); // pass the exception message + } +---- + +//Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +MicroProfile Health provides a way for your application to distribute information +about its healthiness state to state whether or not it is able to function properly. +Liveness checks are utilized to tell whether the application should be restarted. +Readiness checks are used to tell whether the application is able to process requests. +And last but not least, startup checks are useful if your container has a slow startup to +prevent premature restarts if the liveness probes are called too soon. + +Congratulations! You have reached the end of this tutorial. You can find more information +about the MicroProfile Health in the specification https://github.com/eclipse/microprofile-health[github repository]. diff --git a/microprofile-health/README.adoc b/microprofile-health/README.adoc index 23d22b8365..9bcc9a672b 100644 --- a/microprofile-health/README.adoc +++ b/microprofile-health/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-health +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-health: MicroProfile Health QuickStart :author: Martin Stefanko @@ -31,15 +228,184 @@ In this quickstart, we have a simple REST application that exposes MicroProfile functionalities at the `/health/live`, `/health/ready`, and `/health/started` endpoints according to the specification. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: == Solution @@ -48,7 +414,114 @@ We recommend that you follow the instructions that also go right to the completed example which is available in this directory. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Running the health check @@ -79,13 +552,76 @@ Congratulations! You successfully deployed and run this quickstart. If you wish create the application step by step you can follow the subsequent sections. // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: [[creating-new-project]] == Creating the Maven Project @@ -179,7 +715,69 @@ the generated build section): ---- // Setup required repositories -include::../shared-doc/setup-repositories.adoc[leveloffset=+1] +:leveloffset: +1 + +Setup the required Maven repositories (if you don't have them set up in Maven global settings): + +[source,xml] +---- + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + default + + true + never + + + true + never + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + default + + true + never + + + true + never + + + + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + + true + + + true + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + + true + + + true + + + +---- + +:leveloffset!: Now we are ready to start working with MicroProfile Health. @@ -451,10 +1049,530 @@ error along with the health check response. ---- //Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: microprofile-health +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[] +:leveloffset: +1 + +This quickstart requires the management port (9990) to be exposed for demo purposes and testing. We do this only to demonstrate the concepts and ease the testing. + +IMPORTANT: It is **not** recommended to expose the management port in a production environment! + +To expose the management porte to manually exposes our service on port 9990 we deploying the following file: +[source,options="nowrap",subs="+attributes"] +---- +oc apply -f charts/management.yml +---- +Once this is deployed you will be able to access the management port via the created `microprofile-health-management` route. + +To get the address of the `microprofile-health-management` route, execute: +[source,options="nowrap",subs="+attributes"] +---- +$ oc get route microprofile-health -o jsonpath="{.spec.host}" +---- + +:leveloffset: 2 +endif::post-helm-install-actions[] + + +[[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 + +// 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[] +:leveloffset: +1 + +This quickstart requires the management port (9990) to be exposed for demo purposes and testing. We do this only to demonstrate the concepts and ease the testing. + +IMPORTANT: It is **not** recommended to expose the management port in a production environment! + +To expose the management porte to manually exposes our service on port 9990 we deploying the following file: +[source,options="nowrap",subs="+attributes"] +---- +oc apply -f charts/management.yml +---- +Once this is deployed you will be able to access the management port via the created `microprofile-health-management` route. + +To get the address of the `microprofile-health-management` route, execute: +[source,options="nowrap",subs="+attributes"] +---- +$ oc get route microprofile-health -o jsonpath="{.spec.host}" +---- + +:leveloffset: 2 +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 + +:leveloffset!: == Conclusion diff --git a/microprofile-health/charts/helm.yaml b/microprofile-health/charts/helm.yaml index a925c5de44..36aea2f9d3 100644 --- a/microprofile-health/charts/helm.yaml +++ b/microprofile-health/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-health deploy: replicas: 1 \ No newline at end of file diff --git a/microprofile-health/pom.xml b/microprofile-health/pom.xml index a902324903..8631530eb0 100644 --- a/microprofile-health/pom.xml +++ b/microprofile-health/pom.xml @@ -8,18 +8,18 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-health - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-health - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} diff --git a/microprofile-jwt/README-source.adoc b/microprofile-jwt/README-source.adoc new file mode 100644 index 0000000000..fba604aa2a --- /dev/null +++ b/microprofile-jwt/README-source.adoc @@ -0,0 +1,723 @@ +include::../shared-doc/attributes.adoc[] + += micro-profile-jwt: MicroProfile JWT QuickStart +:author: Darran Lofthouse +:level: Intermediate +:technologies: JWT, Security, MicroProfile + +[abstract] +The `microprofile-jwt` quickstart demonstrates the use of the MicroProfile JWT specification in {productName}. + +:standalone-server-type: microprofile +:archiveType: war +:archiveName: microprofile-jwt.war + +== What is it? + +The `microprofile-jwt` quickstart demonstrates the use of the MicroProfile JWT +specification in {productName}. Within the quickstart the following topics will be covered: - + + * Creation of a simple Rest deployment as the base of the quickstart. + * Initial calls to verify the endpoint is accessible. + * Creation of public and private keys to enable generation and validation of JWT tokens. + * Creation of a simple utility to generate JWT tokens. + * Activation of `MP-JWT` authentication for the deployment. + * Calling the rest endpoint with the generated JWT token. + * Enabling authorization based on claims contained within the JWT token. + * Injection of claims from the JWT token. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +[[considerations_for_use_in_a_production_environment]] +== Considerations for Use in a Production Environment + +To make it possible to execute this quickstart out of the box the public and private key are included in the +quickstart, as both keys are published publicly they should never be used in a production environment. + +Although this quickstart demonstrates the functionality using a token generation utility, within a production +environment it would be more appropriate to make use of an identity provider to issue the tokens. + +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +One of the benefits of using MicroProfile JWT is that the configuration is contained entirely within the deployment, +for this reason no manual configuration of the server is required to execute the quickstart. + +== Solution + +We recommend that you follow the instructions in the next sections and create the application step by step as this will +provide a better foundation for creating your own MP-JWT secured deployment, however if you want to jump straight to +executing the quickstarts the steps here can be followed to execute the included code. + +The quickstart can be deployed to the running application server using the following command: - + +[source] +---- +mvn package wildfly:deploy +---- + +An unauthenticated call can be made to one of the deployed endpoints using the following command: - + +[source] +---- +$ curl http://localhost:8080/microprofile-jwt/Sample/helloworld +Hello anonymous +---- + +Using the token generation utility contained within the quickstart a new JWT can be created using the following command: - + +[source] +---- +$ mvn exec:java -Dexec.mainClass=org.wildfly.quickstarts.mpjwt.TokenUtil -Dexec.classpathScope=test -Dexec.args="testUser 2017-09-15 Echoer Subscriber" + +JWT Header - {"kid":"Test Key","typ":"jwt","alg":"RS256"} + +JWT Claims - {"sub":"testUser","upn":"testUser","iss":"quickstart-jwt-issuer","aud":"jwt-audience","groups":["Echoer","Subscriber"],"birthdate":"2017-09-15","jti":"3b89e56f-b8fd-4d5f-a1ed-080b958873f9","iat":1579886816,"exp":1579901216} + +Generated JWT Token +eyJraWQiOiJUZXN0IEtleSIsInR5cCI6Imp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ0ZXN0VXNlciIsInVwbiI6InRlc3RVc2VyIiwiaXNzIjoicXVpY2tzdGFydC1qd3QtaXNzdWVyIiwiYXVkIjoiand0LWF1ZGllbmNlIiwiZ3JvdXBzIjpbIkVjaG9lciIsIlN1YnNjcmliZXIiXSwiYmlydGhkYXRlIjoiMjAxNy0wOS0xNSIsImp0aSI6IjNiODllNTZmLWI4ZmQtNGQ1Zi1hMWVkLTA4MGI5NTg4NzNmOSIsImlhdCI6MTU3OTg4NjgxNiwiZXhwIjoxNTc5OTAxMjE2fQ.srUrA3YwWg4V42Kdf5aLQzLiBO9u7ZCJ_bbNBrgU1XFhRBVzpLq4TJheN4ZFvTKDKFHFm2pa1_a_J70EONK9y8mzKnwiIfV1LbugophBE1xp7iDsBeOwGT8IKQVLaoniGGhqny_MkiMmcWt4tRzrTlJ4TOlCGKv3mZ_RzOj6xdWb12RK7-MTZYlRdnPD8kAfRT7QaJnRbuy5vIpqdz8cVg1y2KILBtg_yJB8s2jrx0ZYgTLDUH6yLpcxk43cLszDCfmdaZAoZFjAS9xUdAuk5eo7TBqt376q0BbE5DS8bHlo3ejWcNEwyo1dPD_TlKDJtNgeae89gru5Z2NOmc2XPA +---- + +A call can now be made to the first endpoint using the generated JWT token within the request message: - + +[source] +---- +$ curl -H "Authorization: Bearer eyJ...XPA" http://localhost:8080/microprofile-jwt/Sample/helloworld +Hello testUser +---- + +The quickstart also contains an endpoint which requires the identity to be granted the `Subscriber` role, using a generated token this can be +called using the following command: - + +[source] +---- +$ curl -H "Authorization: Bearer ey..XPA" http://localhost:8080/microprofile-jwt/Sample/subscription +hello + testUser, hasJWT: true +---- + +If a token is now generated and use without the `Subscriber` group access to this endpoint should be rejected. + +[source] +---- +$ mvn exec:java -Dexec.mainClass=org.wildfly.quickstarts.mpjwt.TokenUtil -Dexec.classpathScope=test -Dexec.args="testUser 2017-09-15 Echoer" + +JWT Header - {"kid":"Test Key","typ":"jwt","alg":"RS256"} + +JWT Claims - {"sub":"testUser","upn":"testUser","iss":"quickstart-jwt-issuer","aud":"jwt-audience","groups":["Echoer"],"birthdate":"2017-09-15","jti":"4346874f-eb48-4d84-ab51-c6efd1cd22d5","iat":1580136970,"exp":1580151370} + +Generated JWT Token +eyJraWQiOiJUZXN0IEtleSIsInR5cCI6Imp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ0ZXN0VXNlciIsInVwbiI6InRlc3RVc2VyIiwiaXNzIjoicXVpY2tzdGFydC1qd3QtaXNzdWVyIiwiYXVkIjoiand0LWF1ZGllbmNlIiwiZ3JvdXBzIjpbIkVjaG9lciJdLCJiaXJ0aGRhdGUiOiIyMDE3LTA5LTE1IiwianRpIjoiNDM0Njg3NGYtZWI0OC00ZDg0LWFiNTEtYzZlZmQxY2QyMmQ1IiwiaWF0IjoxNTgwMTM2OTcwLCJleHAiOjE1ODAxNTEzNzB9.NjWlGGi5iB2PW-g_fs74EgwiyOrgRSsHDym5PS7H3o6T3aEb3ZnMmx7W9uhT_pXvpAL_fboXxy7WMQHukGb_ywtxAmTlA7ecrsia-O9EYV2Gr1ZhlQ9kYVERwZdo5lFqphMvERJ1tClTR3Jk37tpu54HVgFquhUEXlEcldOSeRbYHF9fkiVD6_UPR9bfphhCdwzIbeDVnBJ3FuRl_ZuSxWCoWaRSLPGjuR3JzMlUWkRV8RXhRLTkFRgNowOx_uFFK6q7_aOVqQaHixRqT4ULcO9WiA7f6Up0NMscvq-aT3VFw64qEmn2S8pfX7PpSuAB71Z7w0dwhf4qx3iYklfAPw + +$ curl -H "Authorization: Bearer ey..APw" http://localhost:8080/microprofile-jwt/Sample/subscription +Access forbidden: role not allowed +---- + +The quickstart also contains an endpoint that makes use of the `birthdate` claim to calculate how long until the callers birthday, this can be called using a token which contains the `Subscriber` group. + +[source] +---- +$ curl -H "Authorization: Bearer ey..XPA" http://localhost:8080/microprofile-jwt/Sample/birthday +7 months and 19 days until your next birthday. +---- + +This section has been a fast run through of the commands required to deploy the quickstart, generate JWT tokens and call the various endpoints, for further information as to how this was achieved +please read through the next section where the process to generate this quickstart from scratch is described step by step. + +It is also possible to run each of these calls from the test case included in the quickstart. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +== Starting from Scratch + +In this section we will go through the steps to create a new JAX-RS deployment from scratch and incrementally +add support for MicroProfile JWT including token generation, activation of authorization and the injection +of claims. + +=== Project Generation + +This quickstart will be making use of JAX-RS endpoints secured using MicroProfile JWT so the first step +is to generate a new `webapp` project: - + +[source,options="nowrap"] +---- +mvn archetype:generate -DinteractiveMode=false \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-webapp \ + -DgroupId=org.wildfly.quickstarts -DartifactId=microprofile-jwt \ + -Dversion=1.0.0.Alpha1-SNAPSHOT +cd microprofile-jwt +---- + +The changes required on the project can be performed using a text editor, however you may prefer to import the +project into your favourite IDE. + +==== pom.xml Updates + +Next the project's `pom.xml` should be updated so the dependencies required by this quickstart are +available and so we have a plug-in installed which can deploy the quickstart directly to {productName}. + +Add the following properties to the `pom.xml`. + +[source,options="nowrap",subs="attributes+"] +---- +{versionComNimbusdsJoseJwt} +{versionGlassfishJson} +{versionMicroprofileBom} +{versionServerBom} +---- + +Also the project can be updated to use Java 11 as the minimum. + +[source,options="nowrap"] +---- +11 +11 +---- + +Before the dependencies are defined add the following boms. + +[source,options="nowrap"] +---- + + + + org.wildfly.bom + wildfly-ee-with-tools + ${version.server.bom} + pom + import + + + org.wildfly.bom + wildfly-microprofile + ${version.microprofile.bom} + pom + import + + + +---- + +By using boms the majority of dependencies used within this quickstart align with the version uses by the application server. + +The following dependencies can now be added to the project. + +[source,options="nowrap"] +---- + + jakarta.annotation + jakarta.annotation-api + provided + + + jakarta.enterprise + jakarta.enterprise.cdi-api + provided + + + jakarta.ws.rs + jakarta.ws.rs-api + provided + + + org.eclipse.microprofile.jwt + microprofile-jwt-auth-api + provided + +---- + +Also add the following test scoped dependencies. + +[source,options="nowrap"] +---- + + com.nimbusds + nimbus-jose-jwt + ${version.com.nimbusds.jose.jwt} + test + + + jakarta.json + jakarta.json-api + test + + + org.glassfish + jakarta.json + ${version.glassfish.json} + test + + + org.eclipse.parsson + parsson + test + +---- + +Within the `` section of the project add the following plug-in definition. + +[source,options="nowrap"] +---- + + + org.wildfly.plugins + wildfly-maven-plugin + + +---- + +Once the project has been developed this plug-in will handle the deployment to the application server. + +// Setup required repositories +include::../shared-doc/setup-repositories.adoc[leveloffset=+1] + +==== JAX-RS Conversion + +The generated project is a standard web application so the next step will be to delete the files not +required by this quickstart and add the JAX-RS application and a `helloWorld` endpoint. + +Under `src/main/webapp` delete the generated `index.jsp`. + +Within the directory `src/main/webapp/WEB-INF` add an empty `beans.xml` file, this will act as a trigger +to enable CDI for the deployment. + +Under `src/main` create a new `java` directory to hold the Java class to be added to the project. + +Add the following class in the `org.wildfly.quickstarts.mpjwt` package, this will be the main trigger to +process the deployment as a JAX-RS deployment. + +[source,java] +---- +package org.wildfly.quickstarts.mpjwt; + +import jakarta.ws.rs.ApplicationPath; +import jakarta.ws.rs.core.Application; + +import org.eclipse.microprofile.auth.LoginConfig; + +@ApplicationPath("/") +@LoginConfig(authMethod="MP-JWT", realmName="MP JWT Realm") +public class App extends Application {} +---- + +Also within the `org.wildfly.quickstarts.mpjwt` package add the following endpoint. + +[source,java] +---- +package org.wildfly.quickstarts.mpjwt; + +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; + + +@Path("/Sample") +public class SampleEndPoint { + + @GET + @Path("/helloworld") + public String helloworld() { + return "Hello World"; + } + +} +---- + +At this stage the project contains a simple JAX-RS endpoint we can deploy to the server and invoke to verify +everything is working as expected before moving on to enable JWT based authentication and authorization. + +First build the example and deploy it to the previously started application server. + +. Compile the application code and deploy it to {productName} +[source] +---- +$ mvn clean package wildfly:deploy +---- + +In the output of the application server's console check the deployment deployed successfully. + +[source] +---- +15:48:22,159 INFO [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 78) RESTEASY002225: Deploying jakarta.ws.rs.core.Application: class org.wildfly.quickstarts.mpjwt.App$Proxy$_$$_WeldClientProxy +15:48:22,193 INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 78) WFLYUT0021: Registered web context: '/microprofile-jwt' for server 'default-server' +15:48:22,239 INFO [org.jboss.as.server] (management-handler-thread - 1) WFLYSRV0010: Deployed "microprofile-jwt.war" (runtime-name : "microprofile-jwt.war") +---- + +The endpoint can now be called using the following command: - + +[source] +---- +$ curl http://localhost:8080/microprofile-jwt/Sample/helloworld +Hello World +---- + +Alternative HTTP clients can be used however later on we will be adding custom headers to the HTTP request which can be acomplished directly with the `curl` command. + +=== Report Authenticated Identity + +The first update to make to the project is to modify the `/helloworld` to report the name of the presently authenticated identity. + +Make the following changes to the previously created `org.wildfly.quickstarts.mpjwt.SampleEndPoint` class. + +Add the following `import` statements to the class. + +[source,java] +---- +import java.security.Principal; +import jakarta.ws.rs.core.Context; +import jakarta.ws.rs.core.SecurityContext; +---- + +Then replace the existing `helloWorld()` method with the following: - + +[source,java] +---- +@GET +@Path("/helloworld") +public String helloworld(@Context SecurityContext securityContext) { + Principal principal = securityContext.getUserPrincipal(); + String caller = principal == null ? "anonymous" : principal.getName(); + + return "Hello " + caller; +} +---- + +As before, deploy and call the endpoint. + +[source] +---- +$ mvn package wildfly:deploy + +$ curl http://localhost:8080/microprofile-jwt/Sample/helloworld +Hello anonymous +---- + +=== Public / Private Key + +Now that we have a deployable project our next step on the project will be to enable `MP-JWT` authentication, however before we can do this a couple of steps are +required the first being the generation of a public / private key pair for token signing and verification. + +For MicroProfile JWT we only require the keys, we do not require an X509Certificate so we can use openssl to generate the raw keys. + +[source,options="nowrap"] +---- +$ openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048 +---- + +From this we can then export the public key that will be included in the deployment. + +[source,options="nowrap"] +---- +$ mkdir -p src/main/resources/META-INF +$ openssl rsa -in private.pem -pubout -out src/main/resources/META-INF/public.pem +---- + +The commands used here offer no protection of the generated keys, in a real world environment any private keys that can be used for token generation should be handled securely. + +=== Token Generator + +The next step is to add a utility to the project which can be used to generate JWT tokens for use with this example. + +First create a directory to hold the test code. + +[source,options="nowrap"] +---- +$ mkdir -p src/test/java +---- + +Under `src/test/java` add the following utility class to the `org.wildfly.quickstarts.mpjwt` package. + +[source,java] +---- +package org.wildfly.quickstarts.mpjwt; + +import java.io.FileInputStream; +import java.io.InputStream; +import java.nio.charset.StandardCharsets; +import java.security.KeyFactory; +import java.security.PrivateKey; +import java.security.spec.PKCS8EncodedKeySpec; +import java.util.Base64; +import java.util.UUID; + +import jakarta.json.Json; +import jakarta.json.JsonArrayBuilder; +import jakarta.json.JsonObjectBuilder; + +import com.nimbusds.jose.JOSEObjectType; +import com.nimbusds.jose.JWSAlgorithm; +import com.nimbusds.jose.JWSHeader; +import com.nimbusds.jose.JWSObject; +import com.nimbusds.jose.JWSSigner; +import com.nimbusds.jose.Payload; +import com.nimbusds.jose.crypto.RSASSASigner; + +public class TokenUtil { + + private static PrivateKey loadPrivateKey(final String fileName) throws Exception { + try (InputStream is = new FileInputStream(fileName)) { + byte[] contents = new byte[4096]; + int length = is.read(contents); + String rawKey = new String(contents, 0, length, StandardCharsets.UTF_8) + .replaceAll("-----BEGIN (.*)-----", "") + .replaceAll("-----END (.*)----", "") + .replaceAll("\r\n", "").replaceAll("\n", "").trim(); + + PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(rawKey)); + KeyFactory keyFactory = KeyFactory.getInstance("RSA"); + + return keyFactory.generatePrivate(keySpec); + } + } + + public static String generateJWT(final String principal, final String birthdate, final String...groups) throws Exception { + PrivateKey privateKey = loadPrivateKey("private.pem"); + + JWSSigner signer = new RSASSASigner(privateKey); + JsonArrayBuilder groupsBuilder = Json.createArrayBuilder(); + for (String group : groups) { groupsBuilder.add(group); } + + long currentTime = System.currentTimeMillis() / 1000; + JsonObjectBuilder claimsBuilder = Json.createObjectBuilder() + .add("sub", principal) + .add("upn", principal) + .add("iss", "quickstart-jwt-issuer") + .add("aud", "jwt-audience") + .add("groups", groupsBuilder.build()) + .add("birthdate", birthdate) + .add("jti", UUID.randomUUID().toString()) + .add("iat", currentTime) + .add("exp", currentTime + 14400); + + JWSObject jwsObject = new JWSObject(new JWSHeader.Builder(JWSAlgorithm.RS256) + .type(new JOSEObjectType("jwt")) + .keyID("Test Key").build(), + new Payload(claimsBuilder.build().toString())); + + jwsObject.sign(signer); + + return jwsObject.serialize(); + } + + public static void main(String[] args) throws Exception { + if (args.length < 2) throw new IllegalArgumentException("Usage TokenUtil {principal} {birthdate} {groups}"); + String principal = args[0]; + String birthdate = args[1]; + String[] groups = new String[args.length - 2]; + System.arraycopy(args, 2, groups, 0, groups.length); + + String token = generateJWT(principal, birthdate, groups); + String[] parts = token.split("\\."); + System.out.println(String.format("\nJWT Header - %s", new String(Base64.getDecoder().decode(parts[0]), StandardCharsets.UTF_8))); + System.out.println(String.format("\nJWT Claims - %s", new String(Base64.getDecoder().decode(parts[1]), StandardCharsets.UTF_8))); + System.out.println(String.format("\nGenerated JWT Token \n%s\n", token)); + } +} +---- + +After adding the class the project will need to be compiled again and can then be executed using Maven. + +[source] +---- +$ mvn package +... +$ mvn exec:java -Dexec.mainClass=org.wildfly.quickstarts.mpjwt.TokenUtil -Dexec.classpathScope=test -Dexec.args="testUser 2017-09-15 Echoer Subscriber" + +JWT Header - {"kid":"Test Key","typ":"jwt","alg":"RS256"} + +JWT Claims - {"sub":"testUser","upn":"testUser","iss":"quickstart-jwt-issuer","aud":"jwt-audience","groups":["Echoer","Subscriber"],"birthdate":"2017-09-15","jti":"3b89e56f-b8fd-4d5f-a1ed-080b958873f9","iat":1579886816,"exp":1579901216} + +Generated JWT Token +eyJraWQiOiJUZXN0IEtleSIsInR5cCI6Imp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ0ZXN0VXNlciIsInVwbiI6InRlc3RVc2VyIiwiaXNzIjoicXVpY2tzdGFydC1qd3QtaXNzdWVyIiwiYXVkIjoiand0LWF1ZGllbmNlIiwiZ3JvdXBzIjpbIkVjaG9lciIsIlN1YnNjcmliZXIiXSwiYmlydGhkYXRlIjoiMjAxNy0wOS0xNSIsImp0aSI6IjNiODllNTZmLWI4ZmQtNGQ1Zi1hMWVkLTA4MGI5NTg4NzNmOSIsImlhdCI6MTU3OTg4NjgxNiwiZXhwIjoxNTc5OTAxMjE2fQ.srUrA3YwWg4V42Kdf5aLQzLiBO9u7ZCJ_bbNBrgU1XFhRBVzpLq4TJheN4ZFvTKDKFHFm2pa1_a_J70EONK9y8mzKnwiIfV1LbugophBE1xp7iDsBeOwGT8IKQVLaoniGGhqny_MkiMmcWt4tRzrTlJ4TOlCGKv3mZ_RzOj6xdWb12RK7-MTZYlRdnPD8kAfRT7QaJnRbuy5vIpqdz8cVg1y2KILBtg_yJB8s2jrx0ZYgTLDUH6yLpcxk43cLszDCfmdaZAoZFjAS9xUdAuk5eo7TBqt376q0BbE5DS8bHlo3ejWcNEwyo1dPD_TlKDJtNgeae89gru5Z2NOmc2XPA +---- + +We now have everything we need to activate `MP-JWT` authentication on the deployment and start accepting JWT tokens within the HTTP requests. + +=== Activating MicroProfile JWT + +At this stage we have a basic JAX-RS deployment, a pair of keys for the generation of and validation of JWT tokens and a utility to generate JWT tokens. +Our next step is to activate MicroProfile JWT authentication for the deployment and we can then make use of some of the advanced features such as role +based access control using the groups from within the token and access to individual claims within the token. + +The configuration for JWT validation can be contained within a MicroProfile Config properties file, under `src/main/resources/META-INF` +add a `microprofile-config.properties` with the following content. + +[source] +---- +mp.jwt.verify.publickey.location=META-INF/public.pem +mp.jwt.verify.issuer=quickstart-jwt-issuer +---- + +As before, deploy and call the endpoint. + +[source] +---- +$ mvn package wildfly:deploy + +$ curl http://localhost:8080/microprofile-jwt/Sample/helloworld +Hello anonymous +---- + +A new token can now be generated using the TokenUtility created previously and the token passed in as we call the endpoint. + +[source] +---- +$ curl -H "Authorization: Bearer eyJ...59g" http://localhost:8080/microprofile-jwt/Sample/helloworld +Hello testUser +---- + +At this point our first endpoint now supports optional authentication making use of a JWT token. + +=== Authorization + +Now that authentication has been activated we can add another endpoint that requires the caller to have been granted the +‘Subscribers’ role which will be based on the groups in the incoming JWT token. + +The following imports should be added to the “SampleEndPoint” class: - + +[source,java] +---- +import jakarta.annotation.security.RolesAllowed; +import jakarta.inject.Inject; + +import org.eclipse.microprofile.jwt.JsonWebToken; +---- + +And then the following new endpoint can be added: - + +[source,java] +---- +@Inject +JsonWebToken jwt; + +@GET() +@Path("/subscription") +@RolesAllowed({"Subscriber"}) +public String helloRolesAllowed(@Context SecurityContext ctx) { + Principal caller = ctx.getUserPrincipal(); + String name = caller == null ? "anonymous" : caller.getName(); + boolean hasJWT = jwt.getClaimNames() != null; + String helloReply = String.format("hello + %s, hasJWT: %s", name, hasJWT); + return helloReply; +} +---- + + +Within WildFly the JAX-RS deployment is handled by RESTEasy so under `src/main/webapp/WEB-INF` add the following to the web.xml to enable RESTEasy authorization checks. + +[source,xml] +---- + + resteasy.role.based.security + true + + + + Subscriber + +---- + +As before, build and deploy the example. + +[source] +---- +$ mvn package wildfly:deploy +---- + +Using a recently generated token the new endpoint can be called. + +[source] +---- +$ curl -H "Authorization: Bearer ey..59g" http://localhost:8080/microprofile-jwt/Sample/subscription +hello + testUser, hasJWT: true +---- + +If a token is now generated without including the “Subscriber” group access should be denied to the endpoint. + +[source] +---- +$ curl -H "Authorization: Bearer ey..Pw" http://localhost:8080/microprofile-jwt/Sample/subscription +Access forbidden: role not allowed +---- + +=== Claims + +A final feature that will be explored within this Quickstart is accessing the claims contained within the JWT. + +The JWTToken in the previous example can be used to inspect the claims, however it is also possible to inject the specific claim. + +The following imports should be added to the “SampleEndPoint” class: - + +[source,java] +---- +import java.time.LocalDate; +import java.time.Period; +import java.util.Optional; + +import org.eclipse.microprofile.jwt.Claims; +import org.eclipse.microprofile.jwt.Claim; +---- + +And then the following new endpoint can be added: - + +[source,java] +---- +@Inject +@Claim(standard = Claims.birthdate) +Optional birthdate; + +@GET() +@Path("/birthday") +@RolesAllowed({ "Subscriber" }) +public String birthday() { + if (birthdate.isPresent()) { + LocalDate birthdate = LocalDate.parse(this.birthdate.get().toString()); + LocalDate today = LocalDate.now(); + LocalDate next = birthdate.withYear(today.getYear()); + if (today.equals(next)) { + return "Happy Birthday"; + } + if (next.isBefore(today)) { + next = next.withYear(next.getYear() + 1); + } + Period wait = today.until(next); + return String.format("%d months and %d days until your next birthday.", wait.getMonths(), wait.getDays()); + } + return "Sorry, we don't know your birthdate."; +} +---- + +As with the previous endpoint the caller is required to have been granted the `Subscriber` role, if a `birthdate` claim is present within +the JWT token this endpoint will calculate how many days until the next birthday and wish you happy birthday it if is today. + +As before, build and deploy the example. + +[source] +---- +$ mvn package wildfly:deploy +---- + +Using a recently generated token the new endpoint can be called. + +[source] +---- +$ curl -H "Authorization: Bearer ey..59g" http://localhost:8080/microprofile-jwt/Sample/birthday +7 months and 19 days until your next birthday. +---- + +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +As demonstrated within this Quickstart the MicroProfile JWT specification provides an easy way to secure deployments without needing +to rely on managed server configuration. The techniques explored in this quickstart can be used to create your own MicroProfile JWT +secured enpoints or to add MicroProfile JWT authentication to your existing deployments. + diff --git a/microprofile-jwt/README.adoc b/microprofile-jwt/README.adoc index e6ce271857..7bc548db7d 100644 --- a/microprofile-jwt/README.adoc +++ b/microprofile-jwt/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-jwt +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = micro-profile-jwt: MicroProfile JWT QuickStart :author: Darran Lofthouse @@ -19,7 +216,7 @@ The `microprofile-jwt` quickstart demonstrates the use of the MicroProfile JWT specification in {productName}. Within the quickstart the following topics will be covered: - * Creation of a simple Rest deployment as the base of the quickstart. - * Initial calls to verify the endpoint is accessible. + * Initial calls to verify the endpoint is accessible. * Creation of public and private keys to enable generation and validation of JWT tokens. * Creation of a simple utility to generate JWT tokens. * Activation of `MP-JWT` authentication for the deployment. @@ -28,19 +225,155 @@ specification in {productName}. Within the quickstart the following topics will * Injection of claims from the JWT token. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: [[considerations_for_use_in_a_production_environment]] == Considerations for Use in a Production Environment -To make it possible to execute this quickstart out of the box the public and private key are included in the +To make it possible to execute this quickstart out of the box the public and private key are included in the quickstart, as both keys are published publicly they should never be used in a production environment. Although this quickstart demonstrates the functionality using a token generation utility, within a production environment it would be more appropriate to make use of an identity provider to issue the tokens. -include::../shared-doc/system-requirements.adoc[leveloffset=+1] -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +: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!: +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -50,8 +383,8 @@ for this reason no manual configuration of the server is required to execute the == Solution -We recommend that you follow the instructions in the next sections and create the application step by step as this will -provide a better foundation for creating your own MP-JWT secured deployment, however if you want to jump straight to +We recommend that you follow the instructions in the next sections and create the application step by step as this will +provide a better foundation for creating your own MP-JWT secured deployment, however if you want to jump straight to executing the quickstarts the steps here can be followed to execute the included code. The quickstart can be deployed to the running application server using the following command: - @@ -79,7 +412,7 @@ JWT Header - {"kid":"Test Key","typ":"jwt","alg":"RS256"} JWT Claims - {"sub":"testUser","upn":"testUser","iss":"quickstart-jwt-issuer","aud":"jwt-audience","groups":["Echoer","Subscriber"],"birthdate":"2017-09-15","jti":"3b89e56f-b8fd-4d5f-a1ed-080b958873f9","iat":1579886816,"exp":1579901216} -Generated JWT Token +Generated JWT Token eyJraWQiOiJUZXN0IEtleSIsInR5cCI6Imp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ0ZXN0VXNlciIsInVwbiI6InRlc3RVc2VyIiwiaXNzIjoicXVpY2tzdGFydC1qd3QtaXNzdWVyIiwiYXVkIjoiand0LWF1ZGllbmNlIiwiZ3JvdXBzIjpbIkVjaG9lciIsIlN1YnNjcmliZXIiXSwiYmlydGhkYXRlIjoiMjAxNy0wOS0xNSIsImp0aSI6IjNiODllNTZmLWI4ZmQtNGQ1Zi1hMWVkLTA4MGI5NTg4NzNmOSIsImlhdCI6MTU3OTg4NjgxNiwiZXhwIjoxNTc5OTAxMjE2fQ.srUrA3YwWg4V42Kdf5aLQzLiBO9u7ZCJ_bbNBrgU1XFhRBVzpLq4TJheN4ZFvTKDKFHFm2pa1_a_J70EONK9y8mzKnwiIfV1LbugophBE1xp7iDsBeOwGT8IKQVLaoniGGhqny_MkiMmcWt4tRzrTlJ4TOlCGKv3mZ_RzOj6xdWb12RK7-MTZYlRdnPD8kAfRT7QaJnRbuy5vIpqdz8cVg1y2KILBtg_yJB8s2jrx0ZYgTLDUH6yLpcxk43cLszDCfmdaZAoZFjAS9xUdAuk5eo7TBqt376q0BbE5DS8bHlo3ejWcNEwyo1dPD_TlKDJtNgeae89gru5Z2NOmc2XPA ---- @@ -91,7 +424,7 @@ $ curl -H "Authorization: Bearer eyJ...XPA" http://localhost:8080/microprofile-j Hello testUser ---- -The quickstart also contains an endpoint which requires the identity to be granted the `Subscriber` role, using a generated token this can be +The quickstart also contains an endpoint which requires the identity to be granted the `Subscriber` role, using a generated token this can be called using the following command: - [source] @@ -110,7 +443,7 @@ JWT Header - {"kid":"Test Key","typ":"jwt","alg":"RS256"} JWT Claims - {"sub":"testUser","upn":"testUser","iss":"quickstart-jwt-issuer","aud":"jwt-audience","groups":["Echoer"],"birthdate":"2017-09-15","jti":"4346874f-eb48-4d84-ab51-c6efd1cd22d5","iat":1580136970,"exp":1580151370} -Generated JWT Token +Generated JWT Token eyJraWQiOiJUZXN0IEtleSIsInR5cCI6Imp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ0ZXN0VXNlciIsInVwbiI6InRlc3RVc2VyIiwiaXNzIjoicXVpY2tzdGFydC1qd3QtaXNzdWVyIiwiYXVkIjoiand0LWF1ZGllbmNlIiwiZ3JvdXBzIjpbIkVjaG9lciJdLCJiaXJ0aGRhdGUiOiIyMDE3LTA5LTE1IiwianRpIjoiNDM0Njg3NGYtZWI0OC00ZDg0LWFiNTEtYzZlZmQxY2QyMmQ1IiwiaWF0IjoxNTgwMTM2OTcwLCJleHAiOjE1ODAxNTEzNzB9.NjWlGGi5iB2PW-g_fs74EgwiyOrgRSsHDym5PS7H3o6T3aEb3ZnMmx7W9uhT_pXvpAL_fboXxy7WMQHukGb_ywtxAmTlA7ecrsia-O9EYV2Gr1ZhlQ9kYVERwZdo5lFqphMvERJ1tClTR3Jk37tpu54HVgFquhUEXlEcldOSeRbYHF9fkiVD6_UPR9bfphhCdwzIbeDVnBJ3FuRl_ZuSxWCoWaRSLPGjuR3JzMlUWkRV8RXhRLTkFRgNowOx_uFFK6q7_aOVqQaHixRqT4ULcO9WiA7f6Up0NMscvq-aT3VFw64qEmn2S8pfX7PpSuAB71Z7w0dwhf4qx3iYklfAPw $ curl -H "Authorization: Bearer ey..APw" http://localhost:8080/microprofile-jwt/Sample/subscription @@ -131,12 +464,36 @@ please read through the next section where the process to generate this quicksta It is also possible to run each of these calls from the test case included in the quickstart. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: == Starting from Scratch -In this section we will go through the steps to create a new JAX-RS deployment from scratch and incrementally -add support for MicroProfile JWT including token generation, activation of authorization and the injection +In this section we will go through the steps to create a new JAX-RS deployment from scratch and incrementally +add support for MicroProfile JWT including token generation, activation of authorization and the injection of claims. === Project Generation @@ -154,12 +511,12 @@ mvn archetype:generate -DinteractiveMode=false \ cd microprofile-jwt ---- -The changes required on the project can be performed using a text editor, however you may prefer to import the +The changes required on the project can be performed using a text editor, however you may prefer to import the project into your favourite IDE. ==== pom.xml Updates -Next the project's `pom.xml` should be updated so the dependencies required by this quickstart are +Next the project's `pom.xml` should be updated so the dependencies required by this quickstart are available and so we have a plug-in installed which can deploy the quickstart directly to {productName}. Add the following properties to the `pom.xml`. @@ -275,7 +632,69 @@ Within the `` section of the project add the following plug-in de Once the project has been developed this plug-in will handle the deployment to the application server. // Setup required repositories -include::../shared-doc/setup-repositories.adoc[leveloffset=+1] +:leveloffset: +1 + +Setup the required Maven repositories (if you don't have them set up in Maven global settings): + +[source,xml] +---- + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + default + + true + never + + + true + never + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + default + + true + never + + + true + never + + + + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + + true + + + true + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + + true + + + true + + + +---- + +:leveloffset!: ==== JAX-RS Conversion @@ -328,7 +747,7 @@ public class SampleEndPoint { } ---- -At this stage the project contains a simple JAX-RS endpoint we can deploy to the server and invoke to verify +At this stage the project contains a simple JAX-RS endpoint we can deploy to the server and invoke to verify everything is working as expected before moving on to enable JWT based authentication and authorization. First build the example and deploy it to the previously started application server. @@ -399,7 +818,7 @@ Hello anonymous === Public / Private Key -Now that we have a deployable project our next step on the project will be to enable `MP-JWT` authentication, however before we can do this a couple of steps are +Now that we have a deployable project our next step on the project will be to enable `MP-JWT` authentication, however before we can do this a couple of steps are required the first being the generation of a public / private key pair for token signing and verification. For MicroProfile JWT we only require the keys, we do not require an X509Certificate so we can use openssl to generate the raw keys. @@ -477,7 +896,7 @@ public class TokenUtil { public static String generateJWT(final String principal, final String birthdate, final String...groups) throws Exception { PrivateKey privateKey = loadPrivateKey("private.pem"); - + JWSSigner signer = new RSASSASigner(privateKey); JsonArrayBuilder groupsBuilder = Json.createArrayBuilder(); for (String group : groups) { groupsBuilder.add(group); } @@ -505,7 +924,7 @@ public class TokenUtil { } public static void main(String[] args) throws Exception { - if (args.length < 2) throw new IllegalArgumentException("Usage TokenUtil {principal} {birthdate} {groups}"); + if (args.length < 2) throw new IllegalArgumentException("Usage TokenUtil {principal} {birthdate} {groups}"); String principal = args[0]; String birthdate = args[1]; String[] groups = new String[args.length - 2]; @@ -532,7 +951,7 @@ JWT Header - {"kid":"Test Key","typ":"jwt","alg":"RS256"} JWT Claims - {"sub":"testUser","upn":"testUser","iss":"quickstart-jwt-issuer","aud":"jwt-audience","groups":["Echoer","Subscriber"],"birthdate":"2017-09-15","jti":"3b89e56f-b8fd-4d5f-a1ed-080b958873f9","iat":1579886816,"exp":1579901216} -Generated JWT Token +Generated JWT Token eyJraWQiOiJUZXN0IEtleSIsInR5cCI6Imp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJ0ZXN0VXNlciIsInVwbiI6InRlc3RVc2VyIiwiaXNzIjoicXVpY2tzdGFydC1qd3QtaXNzdWVyIiwiYXVkIjoiand0LWF1ZGllbmNlIiwiZ3JvdXBzIjpbIkVjaG9lciIsIlN1YnNjcmliZXIiXSwiYmlydGhkYXRlIjoiMjAxNy0wOS0xNSIsImp0aSI6IjNiODllNTZmLWI4ZmQtNGQ1Zi1hMWVkLTA4MGI5NTg4NzNmOSIsImlhdCI6MTU3OTg4NjgxNiwiZXhwIjoxNTc5OTAxMjE2fQ.srUrA3YwWg4V42Kdf5aLQzLiBO9u7ZCJ_bbNBrgU1XFhRBVzpLq4TJheN4ZFvTKDKFHFm2pa1_a_J70EONK9y8mzKnwiIfV1LbugophBE1xp7iDsBeOwGT8IKQVLaoniGGhqny_MkiMmcWt4tRzrTlJ4TOlCGKv3mZ_RzOj6xdWb12RK7-MTZYlRdnPD8kAfRT7QaJnRbuy5vIpqdz8cVg1y2KILBtg_yJB8s2jrx0ZYgTLDUH6yLpcxk43cLszDCfmdaZAoZFjAS9xUdAuk5eo7TBqt376q0BbE5DS8bHlo3ejWcNEwyo1dPD_TlKDJtNgeae89gru5Z2NOmc2XPA ---- @@ -540,11 +959,11 @@ We now have everything we need to activate `MP-JWT` authentication on the deploy === Activating MicroProfile JWT -At this stage we have a basic JAX-RS deployment, a pair of keys for the generation of and validation of JWT tokens and a utility to generate JWT tokens. -Our next step is to activate MicroProfile JWT authentication for the deployment and we can then make use of some of the advanced features such as role +At this stage we have a basic JAX-RS deployment, a pair of keys for the generation of and validation of JWT tokens and a utility to generate JWT tokens. +Our next step is to activate MicroProfile JWT authentication for the deployment and we can then make use of some of the advanced features such as role based access control using the groups from within the token and access to individual claims within the token. -The configuration for JWT validation can be contained within a MicroProfile Config properties file, under `src/main/resources/META-INF` +The configuration for JWT validation can be contained within a MicroProfile Config properties file, under `src/main/resources/META-INF` add a `microprofile-config.properties` with the following content. [source] @@ -575,7 +994,7 @@ At this point our first endpoint now supports optional authentication making use === Authorization -Now that authentication has been activated we can add another endpoint that requires the caller to have been granted the +Now that authentication has been activated we can add another endpoint that requires the caller to have been granted the ‘Subscribers’ role which will be based on the groups in the incoming JWT token. The following imports should be added to the “SampleEndPoint” class: - @@ -711,14 +1130,495 @@ $ curl -H "Authorization: Bearer ey..59g" http://localhost:8080/microprofile-jwt ---- // Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: microprofile-jwt +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[] + + +[[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 + +// 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 + +:leveloffset!: == Conclusion As demonstrated within this Quickstart the MicroProfile JWT specification provides an easy way to secure deployments without needing to rely on managed server configuration. The techniques explored in this quickstart can be used to create your own MicroProfile JWT secured enpoints or to add MicroProfile JWT authentication to your existing deployments. - diff --git a/microprofile-jwt/charts/helm.yaml b/microprofile-jwt/charts/helm.yaml index 515e907085..fe48b8ceaf 100644 --- a/microprofile-jwt/charts/helm.yaml +++ b/microprofile-jwt/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-jwt deploy: replicas: 1 \ No newline at end of file diff --git a/microprofile-jwt/pom.xml b/microprofile-jwt/pom.xml index 756ff448c5..63ddf86b32 100644 --- a/microprofile-jwt/pom.xml +++ b/microprofile-jwt/pom.xml @@ -24,12 +24,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-jwt - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-jwt Example project making use of MicroProfile JWT @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} diff --git a/microprofile-lra/README-source.adoc b/microprofile-lra/README-source.adoc new file mode 100644 index 0000000000..a32da33411 --- /dev/null +++ b/microprofile-lra/README-source.adoc @@ -0,0 +1,854 @@ +include::../shared-doc/attributes.adoc[] + += microprofile-lra: MicroProfile LRA QuickStart +:author: Martin Stefanko +:level: Beginner +:technologies: MicroProfile LRA + +[abstract] +The `microprofile-lra` quickstart demonstrates the use of the MicroProfile LRA specification in {productName}. + +:standalone-server-type: microprofile +:configFileName: standalone-microprofile.xml +:archiveType: war +:archiveName: {artifactId} +:microprofile-lra: +:restoreScriptName: restore-configuration.cli +:openshift: true +:custom-bootable-jar-layers: +:custom-openshift-layers: +:extra-openshift-test-arguments: +:requires-http-route: + +== What is it? + +link:https://github.com/eclipse/microprofile-lra[MicroProfile LRA specification] aims to provide an API that the +applications utilize to cooperate actions in +distributed +transactions based on the saga pattern. The user applications enlist within the LRA which in turn notifies all enlisted +participants about the LRA (transaction) outcome. The saga pattern provides different transactional guarantees than ACID +transactions. Saga allows individual operations to execute right when they are invoked. Meaning together with the +enlistment in the LRA. It also requires each participant to define a compensating action which is a semantic undo of the +original operation. Note that this doesn't need to be opposite action. The compensation is required to put the state of +the system into the semantically same state as before the action invocation, not exactly same. If your action is for +instance sending an email, your compensation might be another email cancelling previous email. + +If all actions execute successfully, the LRA is closed and the optional Complete callbacks are invoked on enlisted +participants. If any action fails, then the LRA is cancelled and all compensation actions (Compensate callbacks) of all +enlisted participants are invoked. The state of the system is said to be eventually consistent, since if we don't start +any new LRAs, the state is bound to become consistent eventually. + +The implementation used in the {productName} is provided by the +link:https://github.com/jbosstm/narayana/tree/main/rts/lra[Narayana project]. + +== Architecture + +In this quickstart, we have a simple REST application that exposes several REST endpoints that enlist the application as +different LRA participants and provide callbacks for completions and compensations respectively. It's REST API consists +of the following +endpoints: + +- `GET /participant1/work` - work action of Participant 1 +- `GET /participant2/work` - work action of Participant 2 +- `PUT /participant1/compensate` - compensating action of Participant 1 +- `PUT /participant2/compensate` - compensating action of Participant 2 +- `PUT /participant1/complete` - complete action of Participant 1 +- `PUT /participant2/complete` - complete action of Participant 2 + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the Server + +You can configure the LRA extensions and subsystems (both for LRA coordinator and LRA participant respectively) by running CLI commands. +For your convenience, this quickstart batches the commands into a `enable-microprofile-lra.cli` script provided in the root directory +of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `enable-microprofile-lra.cli` file in the root of this quickstart directory. It enables two extensions and adds +two subsystems, one for LRA coordinator and one for LRA participant respectively. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-microprofile-lra.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/{configFileName}` file and review the changes. + +. The script added the following two extensions: ++ +[source,xml,options="nowrap"] +---- + + +---- ++ + +. And also the following two subsystems: ++ +[source,xml,options="nowrap"] +---- + + +---- + + +[[solution]] +== Solution + +We recommend that you follow the instructions that +<>. However, you can +also go right to the completed example which is available in this directory. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Restore the {productName} Standalone Server Configuration +:restoreScriptName: restore-configuration.cli +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Additional information about this script +This script removes the added extensions and subsystems for the LRA participant and the LRA coordinator. + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] + +//Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +[[creating-new-project]] +== Creating the Maven Project + +[source,options="nowrap"] +---- +mvn archetype:generate \ + -DgroupId=org.wildfly.quickstarts \ + -DartifactId=microprofile-lra \ + -DinteractiveMode=false \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-webapp +cd microprofile-lra +---- + +Open the project in your favourite IDE. + +Open the generated `pom.xml`. + +The first thing to do is to change the minimum JDK to Java 11 and set the other relevant version properties: + +[source,xml,subs="attributes+"] +---- +11 +11 + + +{versionServer} + +${version.server} +${version.server} +{versionPackCloud} +{versionPluginWildfly} +{versionPluginWildflyJar} +---- + +Next we need to setup our dependencies. Add the following section to your +`pom.xml`: + +[source,xml,subs="attributes+"] +---- + + + + org.wildfly.bom + wildfly-ee-with-tools + ${version.bom.ee} + pom + import + + + org.wildfly.bom + wildfly-microprofile + ${version.bom.microprofile} + pom + import + + + +---- + +Now we need to add the following dependencies: + +[source,xml] +---- + + org.eclipse.microprofile.lra + microprofile-lra-api + provided + + + jakarta.ws.rs + jakarta.ws.rs-api + provided + + + jakarta.enterprise + jakarta.enterprise.cdi-api + provided + + + org.jboss.logging + jboss-logging + provided + +---- + +NOTE: We need Jakarta REST (JAX-RS) since LRA exposes functionality over JAX-RS resources and uses HTTP as its +communication protocol. + +All dependencies can have provided scope. The versions are taken from the above +defined BOM. + +As we are going to be deploying this application to the {productName} server, let's +also add a maven plugin that will simplify the deployment operations (you can replace +the generated build section): + +[source,xml] +---- + + + ${project.artifactId} + + + + org.wildfly.plugins + wildfly-maven-plugin + ${version.plugin.wildfly} + + + org.wildfly.plugins + wildfly-jar-maven-plugin + ${version.plugin.wildfly-jar} + + + + +---- + +// Setup required repositories +include::../shared-doc/setup-repositories.adoc[leveloffset=+1] + +Now we are ready to start working with MicroProfile LRA. + +== Set up JAX-RS server and result wrapper + +LRA works on top of JAX-RS. To set up JAX-RS server in our service, we need to create a new application class +`org.wildfly.quickstarts.microprofile.lra.JaxRsApplication` in the file +`microprofile-lra/src/main/java/org/wildfly/quickstarts/microprofile/lra/JaxRsApplication.java` that looks like this: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.lra; + +import jakarta.ws.rs.ApplicationPath; +import jakarta.ws.rs.core.Application; + +@ApplicationPath("/") +public class JaxRsApplication extends Application { +} +---- + +Now we can declare our LRA JAX-RS resources. + +The LRAs we're going to create also accumulate results in a wrapper called `ParticipantResult` which we can create in `org.wildfly.quickstarts.microprofile.lra.ParticipantResult` class: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.lra; + +public class ParticipantResult { + + private String workLRAId; + private String workRecoveryId; + private String completeLRAId; + private String completeRecoveryId; + private String compensateLRAId; + private String compensateRecoveryId; + + public ParticipantResult() {} + + public ParticipantResult(String workLRAId, String workRecoveryId, + String completeLRAId, String completeRecoveryId, + String compensateLRAId, String compensateRecoveryId) { + this.workLRAId = workLRAId; + this.workRecoveryId = workRecoveryId; + this.completeLRAId = completeLRAId; + this.completeRecoveryId = completeRecoveryId; + this.compensateLRAId = compensateLRAId; + this.compensateRecoveryId = compensateRecoveryId; + } + + public String getWorkLRAId() { + return workLRAId; + } + + public void setWorkLRAId(String workLRAId) { + this.workLRAId = workLRAId; + } + + public String getWorkRecoveryId() { + return workRecoveryId; + } + + public void setWorkRecoveryId(String workRecoveryId) { + this.workRecoveryId = workRecoveryId; + } + + public String getCompleteLRAId() { + return completeLRAId; + } + + public void setCompleteLRAId(String completeLRAId) { + this.completeLRAId = completeLRAId; + } + + public String getCompleteRecoveryId() { + return completeRecoveryId; + } + + public void setCompleteRecoveryId(String completeRecoveryId) { + this.completeRecoveryId = completeRecoveryId; + } + + public String getCompensateLRAId() { + return compensateLRAId; + } + + public void setCompensateLRAId(String compensateLRAId) { + this.compensateLRAId = compensateLRAId; + } + + public String getCompensateRecoveryId() { + return compensateRecoveryId; + } + + public void setCompensateRecoveryId(String compensateRecoveryId) { + this.compensateRecoveryId = compensateRecoveryId; + } + + @Override + public String toString() { + return "ParticipantResult{" + + "workLRAId='" + workLRAId + '\'' + + ", workRecoveryId='" + workRecoveryId + '\'' + + ", completeLRAId='" + completeLRAId + '\'' + + ", completeRecoveryId='" + completeRecoveryId + '\'' + + ", compensateLRAId='" + compensateLRAId + '\'' + + ", compensateRecoveryId='" + compensateRecoveryId + '\'' + + '}'; + } +} +---- + +== Creating LRA participants + +In LRA, we define LRA execution and participation with the same `@LRA` annotation. If placed on a method, it acts +similarly to `@Transactional` annotation from JTA. By default, it uses the `REQUIRED` LRA type meaning new LRA is +started or existing LRA (if passed to the invocation) is joined before the method is started. The LRA is also closed +(success) or cancelled (failure/exception) at the end of the method. + +LRA currently works on top of the JAX-RS resources. We can place `@LRA` annotation on any JAX-RS method and the LRA +is already managed for us by {productName}. Let's create a simple JAX-RS resource that uses lra in `org.wildfly .quickstarts.microprofile.lra.LRAParticipant1`: + +[source,java] +---- +/* + * JBoss, Home of Professional Open Source. + * Copyright 2023, Red Hat, Inc., and individual contributors + * as indicated by the @author tags. See the copyright.txt file in the + * distribution for a full listing of individual contributors. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ + +package org.wildfly.quickstarts.microprofile.lra; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.HeaderParam; +import jakarta.ws.rs.PUT; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.QueryParam; +import jakarta.ws.rs.client.Client; +import jakarta.ws.rs.client.ClientBuilder; +import jakarta.ws.rs.core.Context; +import jakarta.ws.rs.core.MediaType; +import jakarta.ws.rs.core.Response; +import jakarta.ws.rs.core.UriInfo; +import org.eclipse.microprofile.lra.annotation.Compensate; +import org.eclipse.microprofile.lra.annotation.Complete; +import org.eclipse.microprofile.lra.annotation.ws.rs.LRA; +import org.jboss.logging.Logger; + +import java.net.URI; + +@Path("/participant1") +@ApplicationScoped +public class LRAParticipant1 { + + private static final Logger LOGGER = Logger.getLogger(LRAParticipant1.class); + + private String workLRAId; + private String workRecoveryId; + private String completeLRAId; + private String completeRecoveryId; + private String compensateLRAId; + private String compensateRecoveryId; + + @Context + UriInfo uriInfo; + + @LRA + @GET + @Path("/work") + public Response work(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId, + @QueryParam("failLRA") boolean failLRA) { + LOGGER.infof("Executing action of Participant 1 enlisted in LRA %s " + + "that was assigned %s participant Id.", lraId, participantId); + + workLRAId = lraId.toASCIIString(); + workRecoveryId = participantId.toASCIIString(); + compensateLRAId = null; + compensateRecoveryId = null; + completeLRAId = null; + completeRecoveryId = null; + + return failLRA ? Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(lraId.toASCIIString()).build() : + Response.ok(lraId.toASCIIString()).build(); + } + + @Compensate + @PUT + @Path("/compensate") + public Response compensateWork(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Compensating action for Participant 1 (%s) in LRA %s.", participantId, lraId); + + compensateLRAId = lraId.toASCIIString(); + compensateRecoveryId = participantId.toASCIIString(); + + return Response.ok().build(); + } + + @Complete + @PUT + @Path("/complete") + public Response completeWork(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Complete action for Participant 1 (%s) in LRA %s.", participantId, lraId); + + completeLRAId = lraId.toASCIIString(); + completeRecoveryId = participantId.toASCIIString(); + + return Response.ok().build(); + } + + @GET + @Path("/result") + @Produces(MediaType.APPLICATION_JSON) + public ParticipantResult getParticipantResult() { + return new ParticipantResult(workLRAId, workRecoveryId, + completeLRAId, completeRecoveryId, + compensateLRAId, compensateRecoveryId); + } +} +---- + +Let's look at it part by part. + +The most important method is called `work` and it looks like this: + +[source,java] +---- +@LRA +@GET +@Path("/work") +public Response work(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId, + @QueryParam("failLRA") boolean failLRA) { + LOGGER.infof("Executing action of Participant 1 enlisted in LRA %s " + + "that was assigned %s participant Id.", lraId, participantId); + + workLRAId = lraId.toASCIIString(); + workRecoveryId = participantId.toASCIIString(); + compensateLRAId = null; + compensateRecoveryId = null; + completeLRAId = null; + completeRecoveryId = null; + + return failLRA ? Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(lraId.toASCIIString()).build() : + Response.ok(lraId.toASCIIString()).build(); +} +---- + +In this `GET` JAX-RS method, we also use the `@LRA` annotation that either starts a new LRA or joins an existing one +which is defined by the default LRA type `REQUIRED`. This is decided based on the `LRA.LRA_HTTP_CONTEXT_HEADER` header +we called `lraId`. If the framework starts a new LRA, +this header is automatically populated with its ID. If the caller specifies this `LRA.LRA_HTTP_CONTEXT_HEADER` +manually in the request, the received LRA is joined. As you can see, the LRA context or ID is propagated in HTTP +headers. + +The second header parameter `LRA.LRA_HTTP_RECOVERY_HEADER` is considered a unique participant ID for a particular +enlistment within LRA. If we would like to enlist `LRAParticipant1` in the same LRA (`LRA.LRA_HTTP_CONTEXT_HEADER`) +multiple times, this recovery ID would be different so we can associate the invocations of compensate and complete +methods. + +Each LRA participant needs to define the `@Compensate` method that defines the compensating action. + +[source,java] +---- +@Compensate +@PUT +@Path("/compensate") +public Response compensateWork(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Compensating action for Participant 1 (%s) in LRA %s.", participantId, lraId); + + compensateLRAId = lraId.toASCIIString(); + compensateRecoveryId = participantId.toASCIIString(); + + return Response.ok().build(); +} +---- + +The compensation is defined by the `@Compensate` annotation which needs to be placed on the JAX-RS PUT method so the LRA +coordinator knows how to call it. For simplicity, we are just printing the messages to the console. The participant can +control how it finishes its participation in LRA via the returned status code. Please see the +link:https://github.com/eclipse/microprofile-lra/blob/main/spec/src/main/asciidoc/microprofile-lra-spec.asciidoc[specification] +for more details. + +The complete method looks similarly. It uses the `@Complete` annotation and it also needs to be the JAX-RS PUT method. + +[source,java] +---- +@Complete +@PUT +@Path("/complete") +public Response completeWork(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Complete action for Participant 1 (%s) in LRA %s.", participantId, lraId); + + completeLRAId = lraId.toASCIIString(); + completeRecoveryId = participantId.toASCIIString(); + + return Response.ok().build(); +} +---- + +The LRA coordinator invokes the `@Compensate` method when the LRA cancels on failure and it invokes the `@Complete` +method when the LRA closes successfully. + +NOTE: The `@Complete` and `@Compensate` methods don't need to be JAX-RS methods. See the specification for details. + +Now we are already able to start our first LRA. You can deploy the application to the {productName} as demonstrated in +the <> section. Remember that you need to enable the LRA extensions and subsystems with the +`enable-microprofile-lra.cli` script. + +Then you can invoke the `LRAParticipant1` JAX-RS resource as: + +[source,bash] +---- +$ curl http://localhost:8080/microprofile-lra/participant1/work +---- + +or if you want to simulate LRA failure as: + +[source,bash] +---- +$ curl "http://localhost:8080/microprofile-lra/participant1/work?failLRA=true" +---- + +In either case, you will see the LRA execution message printed in the {productName} console: + +[source,bash] +---- +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant1] (default task-1) Executing action of Participant 1 enlisted in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_48 that was assigned http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_48/0_ffff0aca949a_-4998614b_64e74427_4a participant Id. +---- + +And either the complete or compensate message depending on the `failLRA` paramater that can fail the LRA causing it +to cancel: + +[source,bash] +---- +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant1] (default task-4) Complete action for Participant 1 (http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_37/0_ffff0aca949a_-4998614b_64e74427_39) in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_37. + + +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant1] (default task-4) Compensating action for Participant 1 (http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_48/0_ffff0aca949a_-4998614b_64e74427_4a) in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_48. +---- + +== Multiple participants in the LRA + +One participant that starts and ends the LRA is probably enough to demonstrate the functionality, but it rarely makes +sense in distributed microservices architecture to only have one service that participates in a distributed +transaction. So let's add another participant into the LRA started in the `LRAParticipant1`. + +Copy the `LRAParticipant1` into a new class `LRAParticipant2` and change all references to `participant1` to +`participant2`. +The +full class is provided for convenience also here: + +[source,java] +---- +/* + * JBoss, Home of Professional Open Source. + * Copyright 2023, Red Hat, Inc., and individual contributors + * as indicated by the @author tags. See the copyright.txt file in the + * distribution for a full listing of individual contributors. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ + +package org.wildfly.quickstarts.microprofile.lra; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.HeaderParam; +import jakarta.ws.rs.PUT; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; +import jakarta.ws.rs.core.Response; +import org.eclipse.microprofile.lra.annotation.Compensate; +import org.eclipse.microprofile.lra.annotation.Complete; +import org.eclipse.microprofile.lra.annotation.ws.rs.LRA; +import org.jboss.logging.Logger; + +import java.net.URI; + +@Path("/participant2") +@ApplicationScoped +public class LRAParticipant2 { + + private static final Logger LOGGER = Logger.getLogger(LRAParticipant2.class); + + private String workLRAId; + private String workRecoveryId; + private String completeLRAId; + private String completeRecoveryId; + private String compensateLRAId; + private String compensateRecoveryId; + + @LRA(end = false) + @GET + @Path("/work") + public Response work(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Executing action of Participant 2 enlisted in LRA %s " + + "that was assigned %s participant Id.", lraId, participantId); + + workLRAId = lraId.toASCIIString(); + workRecoveryId = participantId.toASCIIString(); + compensateLRAId = null; + compensateRecoveryId = null; + completeLRAId = null; + completeRecoveryId = null; + + return Response.ok().build(); + } + + @Compensate + @PUT + @Path("/compensate") + public Response compensateWork(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Compensating action for Participant 2 (%s) in LRA %s.", participantId, lraId); + + compensateLRAId = lraId.toASCIIString(); + compensateRecoveryId = participantId.toASCIIString(); + + return Response.ok().build(); + } + + @Complete + @PUT + @Path("/complete") + public Response completeWork(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId) { + LOGGER.infof("Complete action for Participant 2 (%s) in LRA %s.", participantId, lraId); + + completeLRAId = lraId.toASCIIString(); + completeRecoveryId = participantId.toASCIIString(); + + return Response.ok().build(); + } + + @GET + @Path("/result") + @Produces(MediaType.APPLICATION_JSON) + public ParticipantResult getParticipantResult() { + return new ParticipantResult(workLRAId, workRecoveryId, + completeLRAId, completeRecoveryId, + compensateLRAId, compensateRecoveryId); + } + +} +---- + +The only notable change is the `LRA` annotation that now contains the `@LRA(end = false)`. This parameter states that +the LRA should not be ended when this business method ends. If we ended the LRA here, it would still invoke +compensate or complete callbacks on all enlisted participants (including `LRAParticipant1` which will propagate the +LRA into this class soon). However, it would also try to close/cancel LRA at the end of the `LRAParticipant1#work` +method and by this time the LRA would already be ended. This would be reported by the coordinator. + +We also need to add the call to the newly created JAX-RS resource to the `LRAParticipant1#work` method as showed in +this +snipped: + +[source,java] +---- +@LRA +@GET +@Path("/work") +public Response work(@HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) URI lraId, + @HeaderParam(LRA.LRA_HTTP_RECOVERY_HEADER) URI participantId, + @QueryParam("failLRA") boolean failLRA) { + LOGGER.infof("Executing action of Participant 1 enlisted in LRA %s " + + "that was assigned %s participant Id.", lraId, participantId); + + workLRAId = lraId.toASCIIString(); + workRecoveryId = participantId.toASCIIString(); + compensateLRAId = null; + compensateRecoveryId = null; + completeLRAId = null; + completeRecoveryId = null; + + // call Participant 2 to propagate the LRA + try (Client client = ClientBuilder.newClient()) { + client.target(uriInfo.getBaseUri() + "/participant2/work") + .request().get(); + } + + return failLRA ? Response.status(Response.Status.INTERNAL_SERVER_ERROR).entity(lraId.toASCIIString()).build() : + Response.ok(lraId.toASCIIString()).build(); +} +---- + +You might remember that we need to propagate the LRA id (LRA context) in the `LRA.LRA_HTTP_CONTEXT_HEADER`. However, if +we make the outgoing JAX-RS call in the JAX-RS method that already carries an active LRA context, the context is +automatically added to the outgoing call. So we don't need to pass it manually to each outgoing call. + +Now we are ready to propagate LRA started in Participant 1 to the Participant 2, enlist both in the newly started +LRA, and finish the LRA when the Participant 1 ends its `work` method. + +Redeploy the application into the {productName} as showed in <>. Then you can repeat the calls to the +`LRAParticipant1` JAX-RS resource as we used them previously: + +[source,bash] +---- +$ curl http://localhost:8080/microprofile-lra/participant1/work +---- + +or if you want to simulate LRA failure as: + +[source,bash] +---- +$ curl "http://localhost:8080/microprofile-lra/participant1/work?failLRA=true" +---- + +But this time, you will see the LRA is propagated to the `LRAParticipant2` and its (complete or compensate) callbacks +are invoked by the LRA coordinator in the same way as for `LRAParticipant1`: + +[source,bash] +---- +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant1] (default task-1) Executing action of Participant 1 enlisted in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_38b that was assigned http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_38b/0_ffff0aca949a_-4998614b_64e74427_38d participant Id. + +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant2] (default task-2) Executing action of Participant 2 enlisted in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_38b that was assigned http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_38b/0_ffff0aca949a_-4998614b_64e74427_38f participant Id. + +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant1] (default task-5) Compensating action for Participant 1 (http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_38b/0_ffff0aca949a_-4998614b_64e74427_38d) in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_38b. + +INFO [org.wildfly.quickstarts.microprofile.lra.LRAParticipant2] (default task-5) Compensating action for Participant 2 (http://localhost:8080/lra-coordinator/lra-coordinator/recoveryhttp%3A%2F%2Flocalhost%3A8080%2Flra-coordinator%2Flra-coordinator%2F0_ffff0aca949a_-4998614b_64e74427_38b/0_ffff0aca949a_-4998614b_64e74427_38f) in LRA http://localhost:8080/lra-coordinator/lra-coordinator/0_ffff0aca949a_-4998614b_64e74427_38b. +---- + +== Conclusion + +MicroProfile LRA provides a simple API for the distributed transactions based on the saga pattern. To use it on {productName} we need to enable the appropriate extensions and subsystems for the LRA Coordinator (a service that +manages LRAs) and the LRA participant (client API). The LRAs are controlled through annotations provided by the +specification. + +Congratulations! You have reached the end of this tutorial. You can find more information +about the MicroProfile LRA in the specification https://github.com/eclipse/microprofile-lra[github repository]. diff --git a/microprofile-lra/README.adoc b/microprofile-lra/README.adoc index 6968628d77..53224db737 100644 --- a/microprofile-lra/README.adoc +++ b/microprofile-lra/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-lra +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-lra: MicroProfile LRA QuickStart :author: Martin Stefanko @@ -57,19 +254,268 @@ endpoints: - `PUT /participant2/complete` - complete action of Participant 2 // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the Server @@ -135,17 +581,200 @@ We recommend that you follow the instructions that also go right to the completed example which is available in this directory. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration :restoreScriptName: restore-configuration.cli -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script removes the added extensions and subsystems for the LRA participant and the LRA coordinator. @@ -157,13 +786,567 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: //Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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] +---- +include::{docdir}/charts/helm.yaml[] +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: [[creating-new-project]] == Creating the Maven Project @@ -185,19 +1368,19 @@ Open the generated `pom.xml`. The first thing to do is to change the minimum JDK to Java 11 and set the other relevant version properties: -[source,xml] +[source,xml,subs="attributes+"] ---- 11 11 -31.0.0.Beta1 +{versionServer} ${version.server} ${version.server} -5.0.0.Final -4.2.1.Final -10.0.0.Final +{versionPackCloud} +{versionPluginWildfly} +{versionPluginWildflyJar} ---- Next we need to setup our dependencies. Add the following section to your @@ -284,7 +1467,69 @@ the generated build section): ---- // Setup required repositories -include::../shared-doc/setup-repositories.adoc[leveloffset=+1] +:leveloffset: +1 + +Setup the required Maven repositories (if you don't have them set up in Maven global settings): + +[source,xml] +---- + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + default + + true + never + + + true + never + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + default + + true + never + + + true + never + + + + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + + true + + + true + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + + true + + + true + + + +---- + +:leveloffset!: Now we are ready to start working with MicroProfile LRA. diff --git a/microprofile-lra/charts/helm.yaml b/microprofile-lra/charts/helm.yaml index 67598c049f..94906bb652 100644 --- a/microprofile-lra/charts/helm.yaml +++ b/microprofile-lra/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-lra deploy: replicas: 1 diff --git a/microprofile-lra/pom.xml b/microprofile-lra/pom.xml index f1acf25671..08910ee775 100644 --- a/microprofile-lra/pom.xml +++ b/microprofile-lra/pom.xml @@ -8,18 +8,18 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-lra - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-lra - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} @@ -152,6 +152,21 @@ + + + org.asciidoctor + asciidoctor-maven-plugin + + + + ${version.server} + ${version.pack.cloud} + ${version.plugin.wildfly} + ${version.plugin.wildfly-jar} + + + + diff --git a/microprofile-openapi/README-source.adoc b/microprofile-openapi/README-source.adoc new file mode 100644 index 0000000000..03432cc0d4 --- /dev/null +++ b/microprofile-openapi/README-source.adoc @@ -0,0 +1,158 @@ +include::../shared-doc/attributes.adoc[] + += microprofile-openapi: MicroProfile OpenAPI QuickStart +:author: Paul Ferraro +:level: Beginner +:technologies: MicroProfile OpenAPI + +[abstract] +This guide demonstrate how to use the MicroProfile OpenAPI functionality in {productName} to expose an OpenAPI document for a simple REST application. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] + +:standalone-server-type: microprofile +:archiveType: war +:archiveName: {artifactId} + +== Prerequisites + +To complete this guide, you will need: + +* less than 15 minutes +* JDK 11+ installed with `JAVA_HOME` configured appropriately +* Apache Maven 3.5.3+ + + + +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Steps + +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +=== Access the OpenAPI documentation of the quickstart application + +Run following command in your terminal: + +[source, shell] +---- +$ curl http://localhost:8080/openapi +---- + +It should return a YAML document conforming to the http://spec.openapis.org/oas/v3.0.3[OpenAPI specification]: + +[source, yaml] +---- +openapi: 3.0.1 +info: + title: Store inventory + description: Application for tracking store inventory + version: "1.0" +servers: +- url: /microprofile-openapi +paths: + /: + get: + responses: + "200": + description: OK + content: + text/plain: + schema: + type: string + /fruit: + get: + responses: + "200": + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Fruit' + post: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Fruit' + responses: + "200": + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Fruit' + delete: + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Fruit' + responses: + "200": + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Fruit' +components: + schemas: + Fruit: + type: object + properties: + description: + type: string + name: + type: string +---- + +=== Enhance OpenAPI documentation with annotations + +You can further enhance/complete your OpenAPI documentation by adding https://github.com/eclipse/microprofile-open-api/tree/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations[MicroProfile OpenAPI annotations]. +You will need to rebuild/redeploy for those changes to be reflected in the OpenAPI document. + +=== Finalizing OpenAPI documentation + +Rather than processing JAX-RS and MicroProfile OpenAPI annotations every time an application is deployed, {productName} can be configured to serve a static OpenAPI document. +When serving a static document, typically, we also want to disable annotation processing. +This is generally suggested for production environments, to ensure an immutable/versioned API contract for integrators. + +. Save the generated document to the source tree. Feel free to use JSON, if you prefer that over YAML. ++ +[source, shell] +---- +$ mkdir src/main/webapp/META-INF +$ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json +---- + +. Reconfigure the application to skip annotation scanning when processing the OpenAPI document model. ++ +[source, shell] +---- +$ echo "mp.openapi.scan.disable=true" > src/main/webapp/META-INF/application.properties +---- + +. Rebuild and redeploy the modified sample application. + ++ +The OpenAPI document model will now be built from the static content rather than annotation processing. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] diff --git a/microprofile-openapi/README.adoc b/microprofile-openapi/README.adoc index 721cd30d0a..dcc7f83b2c 100644 --- a/microprofile-openapi/README.adoc +++ b/microprofile-openapi/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-openapi +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-openapi: MicroProfile OpenAPI QuickStart :author: Paul Ferraro @@ -10,7 +207,13 @@ include::../shared-doc/attributes.adoc[] This guide demonstrate how to use the MicroProfile OpenAPI functionality in {productName} to expose an OpenAPI document for a simple REST application. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: :standalone-server-type: microprofile :archiveType: war @@ -26,13 +229,267 @@ To complete this guide, you will need: -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: == Steps -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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::[] -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +// 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!: + +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the OpenAPI documentation of the quickstart application @@ -148,12 +605,537 @@ $ echo "mp.openapi.scan.disable=true" > src/main/webapp/META-INF/application.pro The OpenAPI document model will now be built from the static content rather than annotation processing. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: + +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: microprofile-openapi +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/microprofile-openapi/charts/helm.yaml b/microprofile-openapi/charts/helm.yaml index e539344a2f..a8bf829806 100644 --- a/microprofile-openapi/charts/helm.yaml +++ b/microprofile-openapi/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-openapi deploy: replicas: 1 \ No newline at end of file diff --git a/microprofile-openapi/pom.xml b/microprofile-openapi/pom.xml index 115cb68419..04ada5f4ce 100644 --- a/microprofile-openapi/pom.xml +++ b/microprofile-openapi/pom.xml @@ -9,19 +9,19 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-openapi - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-openapi - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} diff --git a/microprofile-reactive-messaging-kafka/README-source.adoc b/microprofile-reactive-messaging-kafka/README-source.adoc new file mode 100644 index 0000000000..9a65fc779a --- /dev/null +++ b/microprofile-reactive-messaging-kafka/README-source.adoc @@ -0,0 +1,978 @@ +include::../shared-doc/attributes.adoc[] + += microprofile-reactive-messaging-kafka: MicroProfile Reactive Messaging with Kafka QuickStart +:author: Kabir Khan +:level: Beginner +:technologies: MicroProfile Reactive Messaging + +[abstract] +The `microprofile-reactive-messaging-kafka` quickstart demonstrates the use of the MicroProfile Reactive Messaging specification backed by Apache Kafka in {productName}. + +:standalone-server-type: microprofile +:archiveType: war +:archiveName: {artifactId} +:helm-install-prerequisites: ../microprofile-reactive-messaging-kafka/helm-install-prerequisites.adoc +:helm-app-name: mp-rm-qs +:strimzi-version: v1beta2 + + +== What is it? + +link:https://microprofile.io/project/eclipse/microprofile-reactive-messaging[MicroProfile Reactive Messaging] is a framework for building event-driven, data streaming, and event-sourcing applications using CDI. It lets your application interact using messaging technologies such as link:https://kafka.apache.org[Apache Kafka]. + +The implementation of MicroProfile Reactive Messaging is built on top of link:https://microprofile.io/project/eclipse/microprofile-reactive-streams[MicroProfile Reactive Streams Operators]. Reactive Streams Operators extends the link:https://www.reactive-streams.org[Reactive Streams] specification, by adding operators such as `map()`, `filter()` and others. + +== Architecture + +In this quickstart, we have a CDI bean that demonstrates the functionality of the MicroProfile Reactive Messaging specification. Currently, we support Reactive Messaging 1.0. Connections to external messaging systems such as Apache Kafka are configured via MicroProfile Config. We will also use Reactive Streams Operators to modify the data relayed in these streams in the methods handling the Reactive Messaging streams. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +== Solution + +We recommend that you follow the instructions that +<>. However, you can +also go right to the completed example which is available in this directory. + +CAUTION: Kafka must be running before attempting to deploy the Quickstart application. See <> for how to do this in your local environment. + + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +[[creating-new-project]] +== Creating the Maven Project + +[source,options="nowrap"] +---- +mvn archetype:generate \ + -DgroupId=org.wildfly.quickstarts \ + -DartifactId=microprofile-reactive-messaging-kafka \ + -DinteractiveMode=false \ + -DarchetypeGroupId=org.apache.maven.archetypes \ + -DarchetypeArtifactId=maven-archetype-webapp +cd microprofile-reactive-messaging-kafka +---- + +Open the project in your favourite IDE. + +The project needs to be updated to use Java 8 as the minimum: + +[source,options="nowrap"] +---- +1.8 +1.8 +---- + +Next set up our dependencies. Add the following section to your +`pom.xml`: + +[source,xml,subs="attributes+"] +---- + + + + + org.wildfly.bom + wildfly-ee-with-tools + {versionServerBom} + pom + import + + + + + org.wildfly.bom + wildfly-microprofile + {versionMicroprofileBom} + pom + import + + + +---- +By using boms the majority of dependencies used within this quickstart align with the version used by the application server. + +Now we need to add the dependencies which are needed by what is the focus of this QuickStart (CDI, MicroProfile Reactive Messaging, Reactive Streams Operators, Reactive Streams and the Apache Kafka Client). Additionally we need to add dependencies for 'supporting' functionality (JPA, JTA and JAX-RS): + +[source,xml] +---- + + + + + + jakarta.enterprise + jakarta.enterprise.cdi-api + provided + + + + org.apache.kafka + kafka-clients + provided + + + + io.smallrye.reactive + smallrye-reactive-messaging-kafka-api + provided + + + + org.eclipse.microprofile.reactive.messaging + microprofile-reactive-messaging-api + provided + + + + org.eclipse.microprofile.reactive-streams-operators + microprofile-reactive-streams-operators-api + provided + + + + org.reactivestreams + reactive-streams + provided + + + + + + + jakarta.persistence + jakarta.persistence-api + provided + + + + jakarta.annotation + jakarta.annotation-api + provided + + + + jakarta.transaction + jakarta.transaction-api + provided + + + + jakarta.ws.rs + jakarta.ws.rs-api + provided + + + + org.jboss.resteasy + resteasy-jaxrs + provided + + +---- + + +All dependencies have the 'provided' scope. + +As we are going to be deploying this application to the {productName} server, let's +also add a maven plugin that will simplify the deployment operations (you can replace +the generated build section): + +[source,xml] +---- + + + ${project.artifactId} + + + + org.wildfly.plugins + wildfly-maven-plugin + + + +---- + +// Setup required repositories +include::../shared-doc/setup-repositories.adoc[leveloffset=+1] + +Now we are ready to start working with MicroProfile Reactive Messaging. + +== Preparing the Application + +This will walk you through the steps to write our application. They are: + +* Create a generator for the generated messages. We will create something which mocks a call to an asynchnronous resource. +* Add a data object which wraps the generated messages and adds a timestamp. We will use JPA annotations on this to make it persistable. +* Create our CDI bean interfacing with the Kafka streams via annotated methods. For the streams that are managed by Kafka we will provide a MicroProfile Config file to configure how to interact with Kafka. It will log, filter and store entries to a RDBMS. +* Create a CDI bean that will be used to store and retrieve entries from a RDBMS. +* Create a JAX-RS endpoint to return the data that was stored in the RDBMS to the user. + +=== Adding our Data Generator +Copy across the `microprofile-reactive-messaging-kafka/src/main/java/org/wildfly/quickstarts/microprofile/reactive/messaging/MockExternalAsyncResource.java` file to your project. This class mocks a call to an asynchronous external resource. The details of how it is implemented are not important for this QuickStart. + +`MockExternalAsyncResource` has one callable method: + +[source,java] +---- +public CompletionStage getNextValue() +---- + +The `CompletionStage` returned by this method will complete with a String when ready. A String is ready every two seconds. It will emit the following Strings in the given order: + +* `Hello` +* `World` +* `Reactive` +* `Messaging` +* `with` +* `Kafka` + +After this initial sequence the returned `CompletionStage` will complete with a random entry from the above list. A new entry is available every two seconds. + +=== Adding a Data Object +Later we will wrap the strings in a `TimedEntry` object which contains the String and a timestamp. Since we will be storing it in a database, we add JPA annotations to it: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.sql.Timestamp; + +import jakarta.persistence.Entity; +import jakarta.persistence.GeneratedValue; +import jakarta.persistence.Id; + +@Entity +public class TimedEntry { + private Long id; + private Timestamp time; + private String message; + + public TimedEntry() { + + } + + public TimedEntry(Timestamp time, String message) { + this.time = time; + this.message = message; + } + + @Id + @GeneratedValue + public Long getId() { + return id; + } + + public void setId(Long id) { + this.id = id; + } + + public Timestamp getTime() { + return time; + } + + public void setTime(Timestamp time) { + this.time = time; + } + + public String getMessage() { + return message; + } + + public void setMessage(String message) { + this.message = message; + } + + @Override + public String toString() { + String s = "TimedEntry{"; + if (id != null) { + s += "id=" + id + ", "; + } + s += "time=" + time + + ", message='" + message + '\'' + + '}'; + return s; + } +} +---- + +=== Adding our Messaging CDI Bean + +MicroProfile Reactive Messaging is based on CDI, so all interaction with the MicroProfile Reactive Messaging streams must happen from a CDI beans. **Note:** The beans must have either the `@ApplicationScoped` or `@Dependent` scopes. + +Then within these beans we have a set of methods using the `@Incoming` and `@Outgoing` annotations from the MicroProfile Reactive Messaging specification to map the underlying streams. For an `@Outgoing` annotation its `value` specifies the Reactive Messaging stream to send data to, and for an `@Incoming` annotation its `value` specifies the Reactive Messaging stream to read data from. Although in this QuickStart we are putting all these methods into one CDI bean class, they could be spread over several beans. + +The MicroProfile Reactive Messaging specification contains a full list of all the valid method signatures for such `@Incoming`/`@Outging` methods. We will use a few of them, and see how they make different use-cases easier. + +Our bean looks as follows, and this is the main focus for the functionality in this QuickStart. We will also be using some other technologies, but they are secondary to this section. Explanations of each method will be given in line. + +[source, java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.sql.Timestamp; +import java.util.concurrent.CompletionStage; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; + +import org.eclipse.microprofile.reactive.messaging.Incoming; +import org.eclipse.microprofile.reactive.messaging.Outgoing; +import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder; +import org.eclipse.microprofile.reactive.streams.operators.ReactiveStreams; +import org.reactivestreams.Publisher; + + +@ApplicationScoped +public class MessagingBean { +---- +First we inject our mock asynchronous external data producer, which produces a string every two seconds. We explained this class in a previous section. +[source, java] +---- + + @Inject + MockExternalAsyncResource producer; +---- +We inject a bean that will be used to persist entries to a RDBMS later on. +[source, java] +---- + @Inject + DatabaseBean dbBean; +---- +Now we get to the reactive messaging part. + +Our first method is a 'producer' method, since is annotated with the `@Outgoing` annotation. It simply relays the output of our mock producer bean to the reactive messaging system. It uses the channel `source` (as indicated in the `@Outgoing` annotation's value) as the target stream to send the data to. You can think of 'producer' methods as the entry point to push data into the reactive messaging streams. +[source, java] +---- + + @Outgoing("source") + public CompletionStage sendInVm() { + return producer.getNextValue(); + } +---- +Next we have a 'processor' method. It is annotated with both `@Incoming` and `@Outgoing` annotations so it gets data from the reactive messaging streams and then pushes it to another stream. Essentially it simply relays data. + +In this case we get data from the `source` stream, so it will receive the entries made available by the `sendInVm()` method above, and forwards everything onto the `filter` stream. + +In this case, since we just want to log the strings that were emitted, we are using a simple method signature receiving and returning the raw string provided. The Reactive Messaging implementation has unwrapped the `CompletionStage` from the previous method for us. + +Note that there is no Kafka involved yet. Since the `@Incoming` and `@Outgoing` values match up, Reactive Messaging will use internal, in-memory streams. +[source, java] +---- + @Incoming("source") + @Outgoing("filter") + public String logAllMessages(String message) { + System.out.println("Received " + message); + return message; + } +---- +Now we have another 'processor' method. We get the data from the `filter` stream (what was relayed by the previous `logAllMessages()` method) and forward it on to the `sender` stream. + +In this method we want to do something a bit more advanced, namely apply a filter to the messages. We use a method receiving and returning a Reactive Stream, in this case we use `PublisherBuilder` from the MicroProfile Reactive Streams Operators specification. `PublisherBuilder` extends the `Publisher` interface from the Reactive Streams specification, and provides us with the `filter()` methods we will use here. + +Again the Reactive Messaging implementation does all the wrapping for us. + +Our filter method tells us to only relay messages that match `Hello` or `Kafka`, and drop everything else. In other words, later methods in the stream will only receive occurrences of `Hello` or `Kafka`. + +[source, java] +---- + @Incoming("filter") + @Outgoing("sender") + public PublisherBuilder filter(PublisherBuilder messages) { + return messages + .filter(s -> s.equals("Hello") || s.equals("Kafka")); + } +---- +Next we have another 'processor' method, which receives data from the `sender` stream and forwards it on to the `to-kafka` stream. It's parameter is a simple `String`, MicroProfile Reactive Messaging will unwrap the stream from the `PublisherBuilder` returned in the previous method and call this next method with the individual entries. + +In this method we want to wrap up the data into the `TimedEntry` class we defined earlier, so we have tuple of the message and a timestamp. + +Additionally we want to set a Kafka key for the entries so that we can take advantage of Kafka's querying capabilities (not done in this quickstart). In order to do this, we do the following steps: + +* Create an instance of `Message` from the MicroProfile Reactive Messaging API. A `Message` is a simple wrapper around the payload. In our case we use the `TimedEntry` instance we created. +* We create the key for the `TimedEntry`. In this case we just use a hash of the message. +* Use the `OutgoingKafkaRecordMetadata` builder to create an instance of `OutgoingKafkaRecordMetadata` with the key +* Next we call `KafkaMetadataUtil.writeOutgoingKafkaMetadata()` to augment the `Message` with the `OutgoingKafkaRecordMetadata`. Note that the `Message` passed in to `KafkaMetadataUtil.writeOutgoingKafkaMetadata()` is not modified, we need the returned one. +* We return the augmented `Message` to the stream which is backed by Kafka + +[source, java] +---- + @Incoming("sender") + @Outgoing("to-kafka") + public Message sendToKafka(String msg) { + // Simpler example for debugging + TimedEntry te = new TimedEntry(new Timestamp(System.currentTimeMillis()), msg); + Message m = Message.of(te); + // Just use the hash as the Kafka key for this example + int key = te.getMessage().hashCode(); + + // Create Metadata containing the Kafka key + OutgoingKafkaRecordMetadata md = OutgoingKafkaRecordMetadata + .builder() + .withKey(key) + .build(); + + // The returned message will have the metadata added + return KafkaMetadataUtil.writeOutgoingKafkaMetadata(m, md); + } +---- +Our final method is a 'consumer' method, as it has only an `@Incoming` annotation. You can think of this as a 'final destination' for the data in your application. We are using a `Message` as our method parameter. We are using this signature since we want to access the `IncomingKafkaRecordMetadata`, which contains the key we added in the previous method and additional information such as the Kafka partition and topic the message was sent on. Since we are using the signature taking a `Message` as the parameter, we need to `ack()` the message and return the resulting `CompletionStage`. (If we don't want to ack the receipt of the message and are not interested in the `IncomingKafkaRecordMetadata`, we could have used a simpler signature such as `void receiveFromKafka(TimedEntry message)`.) + +The methid calls through to our `dbBean` to store the received data in a RDBMS. We will look at this briefly later. +[source, java] +---- + @Incoming("from-kafka") + public CompletionStage receiveFromKafka(Message message) { + TimedEntry payload = message.getPayload(); + + IncomingKafkaRecordMetadata md = + KafkaMetadataUtil.readIncomingKafkaMetadata(message).get(); + String msg = + "Received from Kafka, storing it in database\n" + + "\t%s\n" + + "\tkey: %d; partition: %d, topic: %s"; + msg = String.format(msg, payload, md.getKey(), md.getPartition(), md.getTopic()); + System.out.println(msg); + dbBean.store(payload); + return message.ack(); + }} // MessagingBean - END +---- +You might have noticed that up to, and including, the `sendToKafka()` method the `@Incoming.value()` matches the `@Outgoing.value()` of the prior method. This indicates that these streams (`source`, `filter` and `sender`) are handled in memory by the Reactive Messaging implementation. + +For the last two methods this is different and there is no such pairing. The `sendToKafka()` method sends its data to the `to-kafka` stream: +[source, java] +---- + ... + @Outgoing("to-kafka") + public Publisher sendToKafka(Publisher messages) { + ... + } +---- +However, there are no methods annotated with `@Incoming("to-kafka)`. + +And the `receiveFromKafka()` method is expecting to receive data from the `from-kafka` stream: +[source, java] +---- + @Incoming("from-kafka") + public void receiveFromKafka(TimedEntry message) { + ... + } +---- +Again, there are no methods annotated with `@Outgoing("from-kafka")`. + +These 'unpaired' sets of methods indicate that we do not want to use an in-memory stream, and want to use an external system for these streams. If we were try to deploy the MessagingBean in this state the application would fail to deploy. To fix this, and tell it what to map onto, we need to provide some configuration. + +NOTE: `IncomingKafkaRecordMetadata` is only available on incoming streams coming from Kafka. `OutgoingKafkaRecordMetadata` will only have effect on outgoing streams going to Kafka. + +==== Mapping Streams to Kafka using MicroProfile Config +To map 'unpaired' streams onto Kafka we need to add a MicroProfile Config file to configure these streams. + +Create a file called `src/main/resources/META-INF/microprofile-config.properties` and add the following: + +[source,properties] +---- +mp.messaging.connector.smallrye-kafka.bootstrap.servers=localhost:9092 + +mp.messaging.outgoing.to-kafka.connector=smallrye-kafka +mp.messaging.outgoing.to-kafka.topic=testing +mp.messaging.outgoing.to-kafka.key.serializer=org.apache.kafka.common.serialization.IntegerSerializer +mp.messaging.outgoing.to-kafka.value.serializer=org.wildfly.quickstarts.microprofile.reactive.messaging.TimedEntrySerializer + +# Configure the Kafka source (we read from it) +mp.messaging.incoming.from-kafka.connector=smallrye-kafka +mp.messaging.incoming.from-kafka.topic=testing +mp.messaging.incoming.from-kafka.value.deserializer=org.wildfly.quickstarts.microprofile.reactive.messaging.TimedEntryDeserializer +mp.messaging.incoming.from-kafka.key.deserializer=org.apache.kafka.common.serialization.IntegerDeserializer +---- + +The MicroProfile Reactive Messaging specification mandates the following pre-fixes: + +* `mp.messaging.connector.` - used to set overall configuration for your application. +* `mp.messaging.outgoing.` - used to configure streams we are writing to from methods annotated with `@Outgoing`. The next element determines the name of the stream as identified in the `@Outgoing` annotation so all the properties starting with `mp.messaging.outgoing.to-kafka` are used to configure the writing done by the `sendToKafka()` method which is annotated with `@Outgoing("to-kafka")`. +* `mp.messaging.incoming.` - used to configure streams we are reading from in methods annotated with `@Incoming`. The next element determines the name of the stream as identified in the `@Incoming` annotation so all the properties starting with `mp.messaging.incoming.from-kafka` are used to configure the reading done by the `receiveFromKafka()` method which is annotated with `@Incoming("from-kafka")`. + +What comes after these prefixes is vendor dependent. We use the SmallRye implementation of MicroProfile Reactive Messaging. + +At the application level, the `mp.messaging.connector.smallrye-kafka.bootstrap.servers` property says that all conections to Kafka in this application should go to `localhost:9092`. This is not strictly necessary, since this value is the default that would be used if not specified. If we wanted to override this for say the `@Outgoing("to-kafka")` annotated `sendToKafka()` method we could specify this with a property such as: + +[source, properties] +---- +mp.messaging.outgoing.to-kafka.bootstrap.servers=otherhost:9092 +---- + +For the incoming and outgoing properties we can see that they all specify that they should use the `smallrye-kafka` connector and that the outgoing one writes to the same topic, `testing`, as the incoming one reads from. + +We see that the outgoing configuration uses a `TimedEntrySerializer` while the incoming one uses `TimedEntryDeserializer` for the values. Kafka just deals with byte streams, so we need to tell it how to serialize the data we are sending and how to deserialize the data we are receiving. As seen is configured with properties of the form `mp.messaging.outgoing..value.serializer` and `mp.messaging.incoming..value.deserializer`. The link:https://kafka.apache.org/27/javadoc/org/apache/kafka/common/serialization/package-summary.html[org.apache.kafka.common.serialization] package contains implementations of serializers and deserializers for simple data types and constructs such as maps. + +Finally, since the Kafka key is an `Integer`, we use `IntegerSerializer` and `IntegerDeserializer` for the keys. The concept is exactly the same as for the value (de)serializers, but is instead configured with the properties `mp.messaging.outgoing..key.serializer` and `mp.messaging.incoming..key.deserializer`. + + +===== Custom (De)Serializers +In our case the data we are sending to and receiving from Kafka is not a simple object. It is an object of a class defined in our application, so we need to define our own serialization and deserialization. Luckily, this is easy. We just need to implement the link:https://kafka.apache.org/27/javadoc/org/apache/kafka/common/serialization/Serializer.html[org.apache.kafka.common.serialization.Serializer] and link:https://kafka.apache.org/27/javadoc/org/apache/kafka/common/serialization/Deserializer.html[org.apache.kafka.common.serialization.Deserializer] interfaces. + +Here is our `TimedEntrySerializer`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.ObjectOutputStream; + +import org.apache.kafka.common.serialization.Serializer; + +public class TimedEntrySerializer implements Serializer { + @Override + public byte[] serialize(String topic, TimedEntry data) { + if (data == null) { + return null; + } + + try { + ByteArrayOutputStream bout = new ByteArrayOutputStream(); + ObjectOutputStream out = new ObjectOutputStream(bout); + out.writeLong(data.getTime().getTime()); + out.writeUTF(data.getMessage()); + out.close(); + return bout.toByteArray(); + } catch (IOException e) { + e.printStackTrace(); + throw new RuntimeException(e); + } + + } +} +---- + +And here is our `TimedEntryDeserializer`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.io.ByteArrayInputStream; +import java.io.IOException; +import java.io.ObjectInputStream; +import java.sql.Timestamp; + +import org.apache.kafka.common.serialization.Deserializer; + +public class TimedEntryDeserializer implements Deserializer { + + @Override + public TimedEntry deserialize(String topic, byte[] data) { + if (data == null) { + return null; + } + try (ObjectInputStream in = new ObjectInputStream(new ByteArrayInputStream(data))){ + Timestamp time = new Timestamp(in.readLong()); + String message = in.readUTF(); + return new TimedEntry(time, message); + } catch (IOException e){ + e.printStackTrace(); + throw new RuntimeException(e); + } + } +} +---- + +As you can see the serializer writes the time as a Long, and the message as a string, and the deserializer reads them in the same order. Then in our `microprofile-config.properties` above we saw how to make Kafka use our classes for serialization and deserialization. + +### Storing Data in an RDBMS +We have covered all the reactive messaging parts, but have missed out how the `MessagingBean.receiveFromKafka()` stores data via the `DatabaseBean`. This is not the focus of this QuickStart, so we will just mention how this works quickly. + +This is the definition of `DatabaseBean`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.util.List; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.persistence.EntityManager; +import jakarta.persistence.PersistenceContext; +import jakarta.persistence.TypedQuery; +import jakarta.transaction.Transactional; + +@ApplicationScoped +public class DatabaseBean { + + @PersistenceContext(unitName = "test") + EntityManager em; + + @Transactional + public void store(Object entry) { + em.persist(entry); + } + + public List loadAllTimedEntries() { + TypedQuery query = em.createQuery("SELECT t from TimedEntry t", TimedEntry.class); + List result = query.getResultList(); + return result; + } +} +---- +It injects an `EntityManager` for the persitence context `test`, which is defined in the `src/main/resources/META-INF/persistence.xml` file: +[source, xml] +---- + + + + java:jboss/datasources/ExampleDS + + + + + +---- +The `DatabaseBean.store()` method saves the `TimedEntry` and the `DatabaseBean.loadAllTimedEntries()` method loads all the ones we stored. + +It is worth pointing out that the `@Incoming` and `@Outgoing` annotated methods called by the Reactive Messaging implementation (such as `MessagingBean.receiveFromKafka()`) happen outside of user space, so there is no @Transaction associated with them. So we need to annotated the `DatabaseBean.store()` method with `@Transactional` in order to save our entry to the database. + +### Viewing the Data Stored in the RDBMS +Finally, we would like to be able to view the data that was stored in the database. To do this we will add a JAX-RS endpoint that queries the database by calling `DatabaseBean.loadAllTimedEntries()`. + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.util.List; + +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; + +@Path("/") +public class RootResource { + + @Inject + DatabaseBean dbBean; + + @GET + @Path("/db") + @Produces(MediaType.TEXT_PLAIN) + public String getDatabaseEntries() { + List entries = dbBean.loadAllTimedEntries(); + StringBuffer sb = new StringBuffer(); + for (TimedEntry t : entries) { + sb.append(t); + sb.append("\n"); + } + return sb.toString(); + } +} + +---- +We expose our JAX-RS application at the context path: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import jakarta.ws.rs.ApplicationPath; +import jakarta.ws.rs.core.Application; + +@ApplicationPath("/") +public class JaxRsApplication extends Application { +} + +---- + +### Interaction with User Initiated Code +So far what we have seen is really happening in the back-end with little user interaction. +The MicroProfile Reactive Messaging 2.0 specification adds a `@Channel` annotation and an `Emitter` interface which makes it easier to send data to MicroProfile Reactive Messaging streams from user initiated code and to receive data from Reactive Messaging streams. + +To showcase this functionality we add another CDI bean called `UserMessagingBean`: +[source, java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import java.util.concurrent.CopyOnWriteArraySet; + +import jakarta.annotation.PreDestroy; +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; +import jakarta.ws.rs.FormParam; +import jakarta.ws.rs.POST; +import jakarta.ws.rs.core.Response; + +import org.eclipse.microprofile.reactive.messaging.Channel; +import org.eclipse.microprofile.reactive.messaging.Emitter; +import org.reactivestreams.Publisher; +import org.reactivestreams.Subscriber; +import org.reactivestreams.Subscription; + +@ApplicationScoped +public class UserMessagingBean { + + @Inject + @Channel("user") + private Emitter emitter; + + private BroadcastPublisher broadcastPublisher; + + public UserMessagingBean() { + //Needed for CDI spec compliance + //The @Inject annotated one will be used + } + + @Inject + public UserMessagingBean(@Channel("user") Publisher receiver) { + this.broadcastPublisher = new BroadcastPublisher(receiver); + } + + @PreDestroy + public void destroy() { + broadcastPublisher.close(); + } + + public Response send(String value) { + System.out.println("Sending " + value); + emitter.send(value); + return Response.accepted().build(); + } + + public Publisher getPublisher() { + return broadcastPublisher; + } + + private class BroadcastPublisher implements Publisher { + // See source code for more details + } +} +---- + +Looking at this in more detail, the following field +[source, java] +---- + @Inject + @Channel("user") + private Emitter emitter; +---- +is used to send data to the MicroProfile Reactive Messagin stream called `user`, which is done in the following method +[source, java] +---- + public Response send(String value) { + System.out.println("Sending " + value); + emitter.send(value); + return Response.accepted().build(); + } +---- + +`@Inject @Channel` on an `Emitter` can be considered similiar to an `@Outgoing` annotated method but with the data coming from code paths invoked by user interaction. In this case we are not using Kafka to back the stream but if we wanted to, for this example, the MicroProfile Config properties would be prefixed with the `mp.messaging.outgoing.user.` prefix. + +Next we have the constructor where we inject a `Publisher` (We could also have used a MicroProfile Reactive Streams Operators `PublisherBuiilder`) to define the receiving side. + +[source, java] +---- + @Inject + public UserMessagingBean(@Channel("user") Publisher receiver) { + this.broadcastPublisher = new BroadcastPublisher(receiver); + } +---- +We store this injected `Publisher` in the `broadcastPublisher` field. We will come back to why we are wrapping it in a `BroadcastPublisher` in a second. So an `@Inject @Channel` on a `Publisher` (or `PublisherBuilder`) can be considered equivalent to use of the `@Incoming` annotation. In this case we are listening to the `user` in memory stream so messages sent via the `Emitter` will be received on this `Publisher`. If instead we wanted to configure it to send via Kafka we would use MicroProfile Config properties prefixed with the `mp.messaging.incoming.user.` prefix. + +There are a few caveats on this mechanism though: + +1. There must be an active `Subscription` (from the Reactive Streams specification) on the channel before the `Emitter.send()` method is called. +2. There can only be one `Subscription` on the injected `Publisher`. This means that we cannot simply return this `Publisher` as is via an asynchronous JAX-RS endpoint as each client request would result in a separate `Subscription`. + +The above two points will hopefully be fixed in a future version of the specification. For the purposes of this quickstart we are bypassing the above limitations by creating the `BroadcastPublisher` class and wrapping the original `Publisher` in that instead. Note that implementing `Publisher` is hard, and that `BroadcastPublisher` should be considered a 'proof of concept'. For more details about the `BroadcastPublisher` see the source code of the `UserMessagingBean` class. In a nutshell what it does is: + +* Its constructor subscribes to the injected `Publisher` to avoid the first problem +* When code subscribes to it, it handles the `Subscription` on its own level, and forwards on code received on the ' a separate level and forwards on data received from the base `Subsciption` created in the constructor. + +Finally we have a JAX-RS endpoint +[source, java] +---- +package org.wildfly.quickstarts.microprofile.reactive.messaging; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; +import jakarta.ws.rs.Consumes; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.POST; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.PathParam; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; +import jakarta.ws.rs.core.Response; + +import org.jboss.resteasy.annotations.Stream; +import org.reactivestreams.Publisher; + +@ApplicationScoped +@Path("/user") +@Produces(MediaType.TEXT_PLAIN) +public class UserResource { + @Inject + UserMessagingBean bean; + + @POST + @Path("{value}") + @Consumes(MediaType.TEXT_PLAIN) + public Response send(@PathParam("value") String value) { + bean.send(value); + return Response.ok().build(); + } + + @GET + @Produces(MediaType.SERVER_SENT_EVENTS) + @Stream + public Publisher get() { + return bean.getPublisher(); + } +} +---- +It simply delegates the values received from `POST` requests under `/user/` onto the bean which sends them via the `Emitter`. + +Then `GET` requests for `/user` return the `BroadCastPublisher` to the user who will then receive data received on the MicroProfile Reactive Messaging channel. + +--- + +Now you should be able to compile the application and prepare it for deployment. + + + +=== Running the Application on a Standalone {productName} Server + +We need to first start Apache Kafka. Then we will run the {productName} server and deploy our application to the server. + + +[[running-the-apache-kafka-service]] +== Running the Apache Kafka Service + +// As Kafka is strictly backwards compatible, I don't think we need to specify the version for users to download +To run Apache Kafka locally you will need to https://kafka.apache.org/downloads[download] it first. Extract the zip to a location, and +enter that directory in a terminal window. Then enter the following command to start Apache Zookeeper: +[source, shell] +---- +$ ./bin/zookeeper-server-start.sh config/zookeeper.properties +---- +Then open a new terminal window and go to the same directory. In this terminal, to start a Kafka instance, enter the command: +[source, shell] +---- +$ ./bin/kafka-server-start.sh config/server.properties +---- + +NOTE: Zookeeper and Kafka must be left running, so use a new terminal for other commands outlined in this quickstart. + +== Build and Deploy the Initial Application +Let's check that our application works! + +. Make sure xref:start_the_eap_standalone_server[the {productName} server is started] as described above. +. {productName} ships with all the modules to run MicroProfile Reactive Messaging applications with Kafka, but the functionality is not enabled out of the box, so we need to enable it. Run: `$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-reactive-messaging.cli` to set everything up. The `enable-reactive-messaging.cli` file used can be found link:enable-reactive-messaging.cli[here]. +*NOTE*: This is only required if running against the downloaded server. If the `microprofile-reactive-messaging-kafka` layer is provisioned, as is done by the `openshift` and `bootable-jar` maven profiles, the Kafka functionality is there +. Open new terminal and navigate to the root directory of your project. +. Type the following command to build and deploy the project: + +[source,options="nowrap"] +---- +$ mvn clean package wildfly:deploy +---- + +Now we should see output in the server console. First, we see output for the ones in the determined order: +[source, options="nowrap"] +---- +14:24:39,197 INFO [stdout] (vert.x-eventloop-thread-0) Received from Kafka, storing it in database +14:24:39,197 INFO [stdout] (vert.x-eventloop-thread-0) TimedEntry{time=2021-08-06 14:24:39.183, message='Hello'} +14:24:39,197 INFO [stdout] (vert.x-eventloop-thread-0) key: 69609650; partition: 0, topic: testing +14:24:41,185 INFO [stdout] (pool-22-thread-1) Received world +14:24:43,183 INFO [stdout] (pool-22-thread-1) Received Reactive +14:24:45,183 INFO [stdout] (pool-22-thread-1) Received Messaging +14:24:47,183 INFO [stdout] (pool-22-thread-1) Received with +14:24:49,182 INFO [stdout] (pool-22-thread-1) Received Kafka +14:24:49,188 INFO [stdout] (vert.x-eventloop-thread-0) Received from Kafka, storing it in database +14:24:49,188 INFO [stdout] (vert.x-eventloop-thread-0) TimedEntry{time=2021-08-06 14:24:49.183, message='Kafka'} +14:24:49,188 INFO [stdout] (vert.x-eventloop-thread-0) key: 72255238; partition: 0, topic: testing +14:24:51,184 INFO [stdout] (pool-22-thread-1) Received Kafka +---- +Then we get another section where it is using the randomised order +[source, options="nowrap"] +---- +14:24:51,184 INFO [stdout] (pool-22-thread-1) Received Kafka +14:24:51,190 INFO [stdout] (vert.x-eventloop-thread-0) Received from Kafka, storing it in database +14:24:51,190 INFO [stdout] (vert.x-eventloop-thread-0) TimedEntry{time=2021-08-06 14:24:51.184, message='Kafka'} +14:24:51,190 INFO [stdout] (vert.x-eventloop-thread-0) key: 72255238; partition: 0, topic: testing +14:24:53,184 INFO [stdout] (pool-22-thread-1) Received world +14:24:55,184 INFO [stdout] (pool-22-thread-1) Received world +14:24:57,184 INFO [stdout] (pool-22-thread-1) Received Reactive +14:24:59,181 INFO [stdout] (pool-22-thread-1) Received Hello +14:24:59,187 INFO [stdout] (vert.x-eventloop-thread-0) Received from Kafka, storing it in database +14:24:59,187 INFO [stdout] (vert.x-eventloop-thread-0) TimedEntry{time=2021-08-06 14:24:59.182, message='Hello'} +14:24:59,187 INFO [stdout] (vert.x-eventloop-thread-0) key: 69609650; partition: 0, topic: testing +---- + +In both parts of the log we see that all messages reach the `logAllMessages()` method, while only `Hello` and `Kafka` reach the `receiveFromKafka()` method which saves them to the RDBMS. + +To inspect what was stored in the database, go to http://localhost:8080/microprofile-reactive-messaging-kafka/db in your browser and you should see something like: + +[source, options="nowrap"] +---- +TimedEntry{id=1, time=2021-08-06 14:24:39.183, message='Hello'} +TimedEntry{id=2, time=2021-08-06 14:24:49.183, message='Kafka'} +TimedEntry{id=3, time=2021-08-06 14:24:51.184, message='Kafka'} +TimedEntry{id=4, time=2021-08-06 14:24:59.182, message='Hello'} +---- +The timestamps of the entries in the browser match the ones we saw in the server logs. + +=== Interaction with User Initiated Code +With the application still running, open two terminal windows. Enter the following `curl` command in both of them +``` +$curl -N http://localhost:8080/microprofile-reactive-messaging-kafka/user +``` +The `-N` option keeps the connection open, so we receive data as it becomes available on the publisher. + +In a third terminal window enter the commands: +``` +$curl -X POST http://localhost:8080/microprofile-reactive-messaging-kafka/user/one +$curl -X POST http://localhost:8080/microprofile-reactive-messaging-kafka/user/two +$curl -X POST http://localhost:8080/microprofile-reactive-messaging-kafka/user/three +``` +In the first two terminal windows you should see these entries appear as they are posted: +``` +data: one + +data: two + +data: three +``` + +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +MicroProfile Reactive Messaging and Reactive Streams Operators allow you to publish to, process and consume streams, optionally backed by Kafka, by adding `@Incoming` and `@Outgoing` annotations to your methods. 'Paired' streams work in memory. To map 'un-paired' streams to be backed by Kafka you need to provide configuration via MicroProfile Config. diff --git a/microprofile-reactive-messaging-kafka/README.adoc b/microprofile-reactive-messaging-kafka/README.adoc index 03b7d12651..49d04816e4 100644 --- a/microprofile-reactive-messaging-kafka/README.adoc +++ b/microprofile-reactive-messaging-kafka/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-reactive-messaging-kafka +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-reactive-messaging-kafka: MicroProfile Reactive Messaging with Kafka QuickStart :author: Kabir Khan @@ -28,15 +225,184 @@ The implementation of MicroProfile Reactive Messaging is built on top of link:ht In this quickstart, we have a CDI bean that demonstrates the functionality of the MicroProfile Reactive Messaging specification. Currently, we support Reactive Messaging 1.0. Connections to external messaging systems such as Apache Kafka are configured via MicroProfile Config. We will also use Reactive Streams Operators to modify the data relayed in these streams in the methods handling the Reactive Messaging streams. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: == Solution @@ -48,17 +414,187 @@ CAUTION: Kafka must be running before attempting to deploy the Quickstart applic // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: [[creating-new-project]] == Creating the Maven Project @@ -215,7 +751,69 @@ the generated build section): ---- // Setup required repositories -include::../shared-doc/setup-repositories.adoc[leveloffset=+1] +:leveloffset: +1 + +Setup the required Maven repositories (if you don't have them set up in Maven global settings): + +[source,xml] +---- + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + default + + true + never + + + true + never + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + default + + true + never + + + true + never + + + + + + jboss-public-maven-repository + JBoss Public Maven Repository + https://repository.jboss.org/nexus/content/groups/public + + true + + + true + + + + redhat-ga-maven-repository + Red Hat GA Maven Repository + https://maven.repository.redhat.com/ga/ + + true + + + true + + + +---- + +:leveloffset!: Now we are ready to start working with MicroProfile Reactive Messaging. @@ -239,7 +837,7 @@ Copy across the `microprofile-reactive-messaging-kafka/src/main/java/org/wildfly public CompletionStage getNextValue() ---- -The `CompletionStage` returned by this method will complete with a String when ready. A String is ready every two seconds. It will emit the following Strings in the given order: +The `CompletionStage` returned by this method will complete with a String when ready. A String is ready every two seconds. It will emit the following Strings in the given order: * `Hello` * `World` @@ -969,10 +1567,574 @@ data: three ``` // Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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]] +:leveloffset: +1 + +=== Install AMQ Streams on OpenShift + +The functionality of this quickstart depends on a running instance of the +https://access.redhat.com/products/red-hat-amq#streams[AMQ Streams] Operator. AMQ Streams is a Red Hat project based on Apache Kafka. To deploy AMQ Streams in the Openshift environment: + +. Log in into the Openshift console as `kubeadmin` user (or any cluster administrator). +. Navigate to `Operators` -> `OperatorHub`. +. Search for `AMQ Streams` - click on the 'AMQ Streams' operator. ++ +Install it with the default values and wait for the message telling you it has been installed and is ready for use. +. In your terminal, run the following command to set up a Kafka cluster called `my-cluster` in your project: ++ +[options="nowrap",subs="+attributes"] +---- +$ oc apply -f - < - 7 + 8 microprofile-reactive-messaging-kafka - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-reactive-messaging-kafka - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} diff --git a/microprofile-rest-client/README-source.adoc b/microprofile-rest-client/README-source.adoc new file mode 100644 index 0000000000..cf18b222af --- /dev/null +++ b/microprofile-rest-client/README-source.adoc @@ -0,0 +1,183 @@ +include::../shared-doc/attributes.adoc[] + += microprofile-rest-client: MicroProfile REST Client QuickStart +:author: Martin Stefanko +:level: Beginner +:technologies: MicroProfile REST Client + +[abstract] +The `microprofile-rest-client` quickstart demonstrates the use of the MicroProfile REST Client specification in {productName}. + +:standalone-server-type: microprofile +:archiveType: jar +:archiveName: {artifactId} +:rest-client-qs: + +== What is it? + +MicroProfile REST Client provides a type-safe approach to invoke RESTful services +over HTTP. It relies on Jakarta REST APIs for consistency and easier reuse. + +== Architecture + +In this quickstart we have a country server and a country client used in the test. The server provides a simple REST +interface providing information about some countries. The test creates a client that consumes this API through the +MicroProfile REST Client specification. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Country Server Application +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +You can verify that the server is responding by accessing +`http://localhost:8080/{artifactId}/name/France` +endpoint using your browser or +`curl http://localhost:8080/{artifactId}/name/France` +to get some information about `France`. + +== The Country REST Client + +Using the MicroProfile REST Client is as simple as creating an interface which uses the +proper Jakarta REST and MicroProfile annotations. In this case, the `org.wildfly.quickstarts.microprofile.rest.client.CountriesServiceClient` +interface may be found in `src/test/java`: + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.rest.client; + +import org.eclipse.microprofile.rest.client.inject.RegisterRestClient; +import org.wildfly.quickstarts.microprofile.rest.client.model.Country; + +import jakarta.ws.rs.GET; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.PathParam; +import jakarta.ws.rs.Produces; + +@Path("/") +public interface CountriesServiceClient { + + @GET + @Path("/name/{name}") + @Produces("application/json") + Country getByName(@PathParam("name") String name); + + @GET + @Path("/name/{name}") + @Produces("application/json") + CompletionStage getByNameAsync(@PathParam("name") String name); +} +---- + +The `getByName` method gives our code the ability to query a country by name +from the REST Countries API, while the `getByNameAsync` method is an asynchronous alternative. The client will handle all the networking and +marshalling leaving our code clean of such technical details. + +As you can see, all that our REST client interface uses for now are standard +Jakarta REST annotations. + +Regarding integrating the REST Client in your application, there are two options, the CDI lookup and the programmatic lookup, and both may be found in the `org.wildfly.quickstarts.microprofile.rest.client.CountriesResource` +class, respectively in use by `cdiName(String)` and `programmaticName(String)` methods. + +[source,java] +---- +package org.wildfly.quickstarts.microprofile.rest.client; + +import jakarta.ws.rs.WebApplicationException; +import org.eclipse.microprofile.config.inject.ConfigProperty; +import org.eclipse.microprofile.rest.client.RestClientBuilder; +import org.eclipse.microprofile.rest.client.inject.RestClient; + +import jakarta.enterprise.context.ApplicationScoped; +import jakarta.inject.Inject; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.NotFoundException; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.PathParam; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.core.MediaType; +import org.wildfly.quickstarts.microprofile.Country; + +import java.net.MalformedURLException; +import java.net.URL; +import java.util.concurrent.CompletionStage; +import java.util.concurrent.TimeUnit; + +@Path("/country") +@ApplicationScoped +public class CountriesResource { + + @Inject + @RestClient + private CountriesServiceClient countriesServiceClient; + + @Inject + @ConfigProperty(name = "server.host") + private String serverHost; + + @GET + @Path("/cdi/{name}") + @Produces(MediaType.APPLICATION_JSON) + public Country cdiName(@PathParam("name") String name) { + try { + return countriesServiceClient.getByName(name); + } catch (NotFoundException e) { + return null; + } + } + + @GET + @Path("/programmatic/{name}") + @Produces(MediaType.APPLICATION_JSON) + public Country programmaticName(@PathParam("name") String name) throws MalformedURLException { + CountriesServiceClient client = RestClientBuilder.newBuilder() + .baseUrl(new URL(serverHost)) + .build(CountriesServiceClient.class); + return client.getByName(name); + } + + @GET + @Path("/name-async/{name}") + @Produces(MediaType.APPLICATION_JSON) + public CompletionStage nameAsync(@PathParam("name") String name) { + CompletionStage completionStage = countriesServiceClient.getByNameAsync(name); + try { + TimeUnit.SECONDS.sleep(1L); + } catch (InterruptedException e) { + throw new WebApplicationException(e); + } + return completionStage; + } +} +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +//Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +MicroProfile REST Client provides you with an option to define REST clients in a +clear, declarative, and intuitive way using the same annotations as for your +Jakarta REST resources. It also allows you to make the HTTP communication on the background +transparent for your services with the direct data conversions and exception mappers. +You can find more information about the MicroProfile REST Client specification at +https://github.com/eclipse/microprofile-rest-client. diff --git a/microprofile-rest-client/README.adoc b/microprofile-rest-client/README.adoc index 0e6b555ae9..dadef6d435 100644 --- a/microprofile-rest-client/README.adoc +++ b/microprofile-rest-client/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: microprofile-rest-client +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = microprofile-rest-client: MicroProfile REST Client QuickStart :author: Martin Stefanko @@ -26,18 +223,294 @@ interface providing information about some countries. The test creates a client MicroProfile REST Client specification. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Country Server Application The application will be running at the following URL: http://localhost:8080/{artifactId}/. @@ -164,15 +637,540 @@ public class CountriesResource { ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: //Bootable JAR -include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: microprofile-rest-client +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[] + + +[[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 + +// 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 + +:leveloffset!: == Conclusion diff --git a/microprofile-rest-client/charts/helm.yaml b/microprofile-rest-client/charts/helm.yaml index 16a15af18f..75b14eca27 100644 --- a/microprofile-rest-client/charts/helm.yaml +++ b/microprofile-rest-client/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: microprofile-rest-client deploy: replicas: 1 \ No newline at end of file diff --git a/microprofile-rest-client/pom.xml b/microprofile-rest-client/pom.xml index b9b17fc6b3..8977a36874 100644 --- a/microprofile-rest-client/pom.xml +++ b/microprofile-rest-client/pom.xml @@ -24,11 +24,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 microprofile-rest-client - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: microprofile-rest-client @@ -42,20 +42,15 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} ${version.server} 5.0.0.Beta2 - + 6.2.6.Final 5.10.1 - - 3.4.3 - 2.1.4.Final - ${project.build.directory}/server http://localhost:8080/microprofile-rest-client @@ -167,15 +162,14 @@ io.smallrye.config smallrye-config - ${version.io.smallrye.smallrye-config} test org.jboss.resteasy.microprofile microprofile-rest-client - ${version.org.jboss.resteasy.microprofile} test + org.jboss.logging commons-logging-jboss-logging diff --git a/numberguess/README-source.adoc b/numberguess/README-source.adoc new file mode 100644 index 0000000000..5ff1c57a3e --- /dev/null +++ b/numberguess/README-source.adoc @@ -0,0 +1,47 @@ +include::../shared-doc/attributes.adoc[] + += numberguess: Example Using CDI and JSF +:author: Pete Muir +:level: Beginner +:technologies: CDI, JSF +:openshift: true + +[abstract] +The `numberguess` quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in {productName}. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `numberguess` quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in {productNameFull}. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/numberguess/README.adoc b/numberguess/README.adoc index 52e94537c2..fb1f3721f2 100644 --- a/numberguess/README.adoc +++ b/numberguess/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: numberguess +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = numberguess: Example Using CDI and JSF :author: Pete Muir @@ -18,31 +215,920 @@ The `numberguess` quickstart demonstrates the use of CDI (Contexts and Dependen The `numberguess` quickstart demonstrates the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in {productNameFull}. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application The application will be running at the following URL: http://localhost:8080/{artifactId}/. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + contextDir: numberguess +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/numberguess/charts/helm.yaml b/numberguess/charts/helm.yaml index 716217e700..b6c0b22ee7 100644 --- a/numberguess/charts/helm.yaml +++ b/numberguess/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: numberguess deploy: replicas: 1 \ No newline at end of file diff --git a/numberguess/pom.xml b/numberguess/pom.xml index fa5f9c9650..0a8ca3ded0 100644 --- a/numberguess/pom.xml +++ b/numberguess/pom.xml @@ -25,11 +25,11 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 numberguess - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: numberguess The numberguess project demonstrates the use of CDI and JSF in JBoss EAP @@ -44,7 +44,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/opentelemetry-tracing/README-source.adoc b/opentelemetry-tracing/README-source.adoc new file mode 100644 index 0000000000..e05c062d83 --- /dev/null +++ b/opentelemetry-tracing/README-source.adoc @@ -0,0 +1,240 @@ +include::../shared-doc/attributes.adoc[] + += opentelemetry-tracing: OpenTelemetry Tracing QuickStart +:author: Jason Lee +:level: Beginner +:technologies: OpenTelemetry Tracing +:openshift: true + +[abstract] +The `opentelemetry-tracing` quickstart demonstrates the use of the OpenTelemetry tracing specification in {productName}. + +:standalone-server-type: default +:archiveType: war +:archiveName: {artifactId} +:restoreScriptName: restore-configuration.cli + + +== What is it? + +OpenTelemetry is a set of APIs, SDKs, tooling and integrations that are designed for the creation and management of +telemetry data such as traces, metrics, and logs. OpenTelemetry support in {productName} is limited to traces only. +{productName}'s support of OpenTelemetry provides out of the box tracing of Jakarta REST calls, as well as +container-managed Jakarta REST Client invocations. Additionally, applications can have injected a `Tracer` instance +in order to create and manage custom `Span`s as a given application may require. These traces are exported +to an OpenTelemetry Collector instance listening on the same host. + +== Architecture + +In this quickstart, we have a collection of CDI beans and REST endpoints that expose functionalities of the OpenTelemetry support in {productName}. + +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Prerequisites + +To complete this guide, you will need: + +* less than 15 minutes +* JDK 11+ installed with `JAVA_HOME` configured appropriately +* Apache Maven 3.5.3+ +* Docker Compose, or alternatively Podman Compose + +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +== Steps + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +=== Configure the Server + +You enable OpenTelemetry by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-opentelemtry.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-opentelemtry.cli` file in the root of this quickstart directory. This script adds the configuration that enables OpenTelemetry for the quickstart components. Comments in the script describe the purpose of each block of commands. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-opentelemetry.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +. You'll need to reload the configuration after that: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --commands=reload +---- + +[[start_opentelemetry_collector]] +=== Starting the OpenTelemetry Collector + +By default, {productName} will publish traces every 10 seconds, so you will soon start seeing errors about a refused connection. + +This is because we told {productName} to publish to a server that is not there, so we need to fix that. To make that as simple as possible, you can use Docker Compose to start an instance of the OpenTelemetry Collector. + +The Docker Compose configuration file is `docker-compose.yaml`: + +[source,yaml] +---- +include::docker-compose.yaml[] +---- + +The Collector server configuration file is `otel-collector-config.yaml`: + +[source,yaml] +---- +include::otel-collector-config.yaml[] +---- + +We can now bring up the collector instance: + +[source,bash] +---- +$ docker-compose up +---- + +The service should be available almost immediately, which you can verify by looking for the log entry `Everything is ready. Begin running and processing data.`. + +[NOTE] +==== +You may use Podman as alternative to Docker if you prefer, in such case the command should be `podman-compose up`. +==== + +[NOTE] +==== +If your environment does not support Docker or Podman, please refer to +https://opentelemetry.io/docs/collector/installation[Otel Collector documentation] for alternatives on how to install +and run the OpenTelemetry Collector. +==== + +[NOTE] +===== +Part of the value of OpenTelemetry is its vendor-agnostic approach to exporting its various supported signals. As such, +this demo will only log the incoming traces, leaving the relaying of those signals to a downstream aggregation platform +as an exercise for the reader. +===== + +Now we can start adding our custom spans from our application. + +=== Creating traces + +==== Implicit tracing of REST resources + +The OpenTelemetry support in {productName} provides an implicit tracing of all Jakarta REST resources. That means that +for all applications, {productName} will automatically: + +* extract the Span context from the incoming Jakarta REST request +* start a new Span on incoming Jakarta REST request and close it when the request is completed +* inject Span context to any outgoing Jakarta REST request +* start a Span for any outgoing Jakarta REST request and finish the Span when the request is completed + +==== Explicit tracing + +The OpenTelemetry API also supports explicit tracing should your application required it: + +[source,java] +----- +include::src/main/java/org/wildfly/quickstarts/opentelemetry/ExplicitlyTracedBean.java[] +----- + +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the quickstart application + +You can either access the application via your browser at http://localhost:8080/opentelemetry-tracing/implicit-trace[], or http://localhost:8080/opentelemetry-tracing/explicit-trace[]. You can also access it from the command line: + +[source,bash] +---- +$ curl http://localhost:8080/opentelemetry-tracing/implicit-trace +$ curl http://localhost:8080/opentelemetry-tracing/explicit-trace +---- + +Either endpoint should return a simple document: + +[source] +----- +hello +----- + +=== View the traces + +You can view the traces by looking at the Collector's log. You should see something like this: + +[source] +----- +otel-collector_1 | 2023-12-13T21:05:28.002Z info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "logging", "resource spans": 1, "spans": 1} +otel-collector_1 | 2023-12-13T21:05:28.002Z info ResourceSpans #0 +otel-collector_1 | Resource SchemaURL: https://opentelemetry.io/schemas/1.20.0 +otel-collector_1 | Resource attributes: +otel-collector_1 | -> service.name: Str(opentelemetry-tracing.war) +otel-collector_1 | -> telemetry.sdk.language: Str(java) +otel-collector_1 | -> telemetry.sdk.name: Str(opentelemetry) +otel-collector_1 | -> telemetry.sdk.version: Str(1.29.0) +otel-collector_1 | ScopeSpans #0 +otel-collector_1 | ScopeSpans SchemaURL: +otel-collector_1 | InstrumentationScope io.smallrye.opentelemetry 2.6.0 +otel-collector_1 | Span #0 +otel-collector_1 | Trace ID : c761e8fadec36d222adac36dcff1f4b1 +otel-collector_1 | Parent ID : +otel-collector_1 | ID : 08f93dd25f75b5cd +otel-collector_1 | Name : GET /opentelemetry-tracing/implicit-trace +otel-collector_1 | Kind : Server +otel-collector_1 | Start time : 2023-12-13 21:05:20.560054393 +0000 UTC +otel-collector_1 | End time : 2023-12-13 21:05:20.621635685 +0000 UTC +otel-collector_1 | Status code : Unset +otel-collector_1 | Status message : +otel-collector_1 | Attributes: +otel-collector_1 | -> net.host.port: Int(8080) +otel-collector_1 | -> http.scheme: Str(http) +otel-collector_1 | -> http.method: Str(GET) +otel-collector_1 | -> http.status_code: Int(200) +otel-collector_1 | -> net.transport: Str(ip_tcp) +otel-collector_1 | -> user_agent.original: Str(curl/8.2.1) +otel-collector_1 | -> net.host.name: Str(localhost) +otel-collector_1 | -> http.route: Str(/opentelemetry-tracing/implicit-trace) +otel-collector_1 | -> http.target: Str(/opentelemetry-tracing/implicit-trace) +otel-collector_1 | -> net.sock.host.addr: Str(127.0.0.1) +otel-collector_1 | {"kind": "exporter", "data_type": "traces", "name": "logging"} +----- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +// Bootable JAR +include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +== Conclusion + +OpenTelemetry Tracing provides the mechanisms for your application to participate +in the distributed tracing with minimal effort on the application side. The Jakarta REST +resources are always traced by default, but the specification allows you to create +individual spans directly with the CDI injection of the `io.opentelemetry.api.trace.Tracer`. diff --git a/opentelemetry-tracing/README.adoc b/opentelemetry-tracing/README.adoc index e05c062d83..1b7c783a99 100644 --- a/opentelemetry-tracing/README.adoc +++ b/opentelemetry-tracing/README.adoc @@ -1,4 +1,205 @@ +<<<<<<< HEAD include::../shared-doc/attributes.adoc[] +======= +ifdef::env-github[] +:artifactId: opentelemetry-tracing +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 = opentelemetry-tracing: OpenTelemetry Tracing QuickStart :author: Jason Lee @@ -29,7 +230,44 @@ to an OpenTelemetry Collector instance listening on the same host. In this quickstart, we have a collection of CDI beans and REST endpoints that expose functionalities of the OpenTelemetry support in {productName}. // Use of {jbossHomeName} +<<<<<<< HEAD include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +======= +: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!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 == Prerequisites @@ -40,12 +278,167 @@ To complete this guide, you will need: * Apache Maven 3.5.3+ * Docker Compose, or alternatively Podman Compose +<<<<<<< HEAD include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +======= +: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!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 == Steps // Start the {productName} Standalone Server +<<<<<<< HEAD include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +======= +:leveloffset: +1 + +[[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!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 [[configure_the_server]] === Configure the Server @@ -94,14 +487,65 @@ The Docker Compose configuration file is `docker-compose.yaml`: [source,yaml] ---- +<<<<<<< HEAD include::docker-compose.yaml[] +======= +version: "3" +volumes: + shared-volume: + # - logs:/var/log +services: + otel-collector: + image: otel/opentelemetry-collector + command: [--config=/etc/otel-collector-config.yaml] + volumes: + - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:Z + ports: + - 1888:1888 # pprof extension + - 13133:13133 # health_check extension + - 4317:4317 # OTLP gRPC receiver + - 4318:4318 # OTLP http receiver + - 55679:55679 # zpages extension +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 ---- The Collector server configuration file is `otel-collector-config.yaml`: [source,yaml] ---- +<<<<<<< HEAD include::otel-collector-config.yaml[] +======= +extensions: + health_check: + pprof: + endpoint: 0.0.0.0:1777 + zpages: + endpoint: 0.0.0.0:55679 + +receivers: + otlp: + protocols: + grpc: + http: + +processors: + batch: + +exporters: + logging: + verbosity: detailed + +service: + pipelines: + traces: + receivers: [otlp] + processors: [] + exporters: [logging] + + extensions: [health_check, pprof, zpages] + +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 ---- We can now bring up the collector instance: @@ -152,10 +596,154 @@ The OpenTelemetry API also supports explicit tracing should your application req [source,java] ----- +<<<<<<< HEAD include::src/main/java/org/wildfly/quickstarts/opentelemetry/ExplicitlyTracedBean.java[] ----- include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +======= +package org.wildfly.quickstarts.opentelemetry; + +import jakarta.enterprise.context.RequestScoped; +import jakarta.inject.Inject; + +import io.opentelemetry.api.trace.Span; +import io.opentelemetry.api.trace.Tracer; + +@RequestScoped +public class ExplicitlyTracedBean { + + @Inject + private Tracer tracer; + + public String getHello() { + Span prepareHelloSpan = tracer.spanBuilder("prepare-hello").startSpan(); + prepareHelloSpan.makeCurrent(); + + String hello = "hello"; + + Span processHelloSpan = tracer.spanBuilder("process-hello").startSpan(); + processHelloSpan.makeCurrent(); + + hello = hello.toUpperCase(); + + processHelloSpan.end(); + prepareHelloSpan.end(); + + return hello; + } +} +----- + +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 == Access the quickstart application @@ -216,6 +804,7 @@ otel-collector_1 | {"kind": "exporter", "data_type": "traces", "name": "log ----- // Server Distribution Testing +<<<<<<< HEAD include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] // Undeploy the Quickstart include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] @@ -231,6 +820,917 @@ endif::[] include::../shared-doc/build-and-run-the-quickstart-with-bootable-jar.adoc[leveloffset=+1] // OpenShift include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +======= +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: +// Restore the {productName} Standalone Server Configuration +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: +// Restore the {productName} Standalone Server Configuration Manually +:leveloffset: +3 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +: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: ] + +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} +---- + +. 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::[] +// Bootable JAR +:leveloffset: +1 + +[[build_and_run_the_quickstart_with_bootable_jar]] += Building and running the quickstart application in a bootable JAR + +You can use the WildFly JAR Maven plug-in to build a {productName} bootable JAR to run this quickstart. + +The quickstart `pom.xml` file contains a Maven profile named *bootable-jar* which configures the bootable JAR building: + +[source,xml,subs="attributes+"] +---- + + bootable-jar + + + + org.wildfly.plugins + wildfly-jar-maven-plugin + + wildfly@maven(org.jboss.universe:community-universe)#${version.server} + ... + + true + + + + + + package + + + + + ... + + + +---- + +.Procedure + +. Build the quickstart bootable JAR with the following command: ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Run the quickstart application contained in the bootable JAR: ++ +[source,subs="attributes+",options="nowrap"] +---- +ifdef::uses-jaeger[] +$ JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1 java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +ifndef::uses-jaeger[] +$ java -jar target/{artifactId}-bootable.jar +endif::uses-jaeger[] +---- + +. You can now interact with the quickstart application. + +[NOTE] +==== +After the quickstart application is deployed, the bootable JAR includes the application in the root context. Therefore, any URLs related to the application should not have the `/{artifactId}` path segment after `HOST:PORT`. +==== + +// Bootable Jar Testing +:leveloffset: +1 + +[[run_the_integration_tests_with_bootable_jar_]] += Run the Integration Tests with a bootable jar + +//****************************************************************************** +// 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::server_provisioning_server_host[:server_provisioning_server_host: http://localhost:8080] + +The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a bootable jar. + +Follow these steps to run the integration tests. + +. Make sure the bootable jar is provisioned. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn clean package -Pbootable-jar +---- + +. Start the {productName} bootable jar, this time using the {productName} Maven Jar Plugin, which is recommend for testing due to simpler automation. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn wildfly-jar:start -Djar-file-name=target/{artifactId}-bootable.jar +---- + +. 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 bootable jar by default is `{server_provisioning_server_host}`. ++ +[source,subs="attributes+",options="nowrap"] +---- +$ mvn verify -Pintegration-testing -Dserver.host={server_provisioning_server_host} +---- + +. Shutdown the {productName} bootable jar, this time using the {productName} Maven Jar Plugin too. ++ +[source,options="nowrap"] +---- +$ mvn wildfly-jar:shutdown +---- + +:leveloffset: 1 + +:leveloffset!: +// OpenShift +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: opentelemetry-tracing +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[] + + +[[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 + +// 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 + +:leveloffset!: +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 == Conclusion diff --git a/opentelemetry-tracing/charts/helm.yaml b/opentelemetry-tracing/charts/helm.yaml index 44a27be81b..6e044a49fe 100644 --- a/opentelemetry-tracing/charts/helm.yaml +++ b/opentelemetry-tracing/charts/helm.yaml @@ -1,6 +1,10 @@ build: uri: https://github.com/wildfly/quickstart.git +<<<<<<< HEAD ref: main +======= + ref: 31.x +>>>>>>> b4ca9a43b66d96aff01d3da9f9714b65b9bb38b0 contextDir: opentelemetry-tracing deploy: replicas: 1 diff --git a/opentelemetry-tracing/pom.xml b/opentelemetry-tracing/pom.xml index 6f509d046d..bf27fafbfc 100644 --- a/opentelemetry-tracing/pom.xml +++ b/opentelemetry-tracing/pom.xml @@ -8,24 +8,24 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 opentelemetry-tracing - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: opentelemetry-tracing - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 4.2.1.Final 10.0.0.Final - 5.0.0.Final + 6.0.0.Final diff --git a/pom.xml b/pom.xml index 5201fe1e7e..ef5b9a29d9 100644 --- a/pom.xml +++ b/pom.xml @@ -30,7 +30,7 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom @@ -54,7 +54,7 @@ 2.1.0 4.2.0.Final 1.0.7.Final - 2.3.0.Final + 2.4.0.Final 3.0 8.5 @@ -447,7 +447,9 @@ false . - README.adoc + + README-source.adoc + README-source.adoc @@ -477,7 +479,7 @@ article . - README.adoc + README-source.adoc README.html . diff --git a/remote-helloworld-mdb/README-source.adoc b/remote-helloworld-mdb/README-source.adoc new file mode 100644 index 0000000000..97bcd4aa06 --- /dev/null +++ b/remote-helloworld-mdb/README-source.adoc @@ -0,0 +1,178 @@ +include::../shared-doc/attributes.adoc[] + += remote-helloworld-mdb: Helloworld Using an MDB (Message-Driven Bean) and a Remote Artemis broker +:author: Serge Pagop, Andy Taylor, Jeff Mesnil +:level: Intermediate +:technologies: JMS, EJB, MDB +:openshift: true + +:standalone-server-type: full +:archiveType: war +:restoreScriptName: remove-remote-broker.cli +ifdef::ProductRelease,EAPXPRelease[] +:BrokerImageName: registry.redhat.io/amq7/amq-broker-rhel8:7.10 +:BrokerProductName: Red Hat AMQ +endif::[] +ifndef::ProductRelease,EAPXPRelease[] +:BrokerImageName: quay.io/artemiscloud/activemq-artemis-broker-kubernetes +:BrokerProductName: Apache Artemis +endif::[] + +[abstract] +The `remote-helloworld-mdb` quickstart demonstrates the use of JMS and EJB Message-Driven Bean in {productName} with a remote broker. + +== What is it? + +The `remote-helloworld-mdb` quickstart demonstrates the use of JMS and EJB Message-Driven Bean in {productNameFull} with a remote {BrokerProductName} broker. + +This project uses two JMS resources on a remote broker: + +* A queue named `HELLOWORLDMDBQueue` bound in JNDI as `java:/queue/HELLOWORLDMDBQueue` +* A topic named `HELLOWORLDMDBTopic` bound in JNDI as `java:/topic/HELLOWORLDMDBTopic` + +//************************************************* +// Product Release content only +//************************************************* + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +//Start the {BrokerProductName} broker. + +// 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 + +=== Run the {BrokerProductName} broker locally + +You can run {BrokerProductName} broker locally using docker or podman: + +[source,options="nowrap",subs="+attributes"] +---- +$ docker run --rm --name artemis -e AMQ_USER=admin -e AMQ_PASSWORD=admin -p8161:8161 -p61616:61616 -e AMQ_DATA_DIR=/home/jboss/data {BrokerImageName} +---- + +You can access the console of {BrokerProductName} at the URL: http://localhost:8161/console with *admin/admin* to authenticate. + +[[configure_the_server]] +=== Configure the {productName} Server + +You configure the JMS connection factory to the remote broker by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-remote-broker.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone full profile] as described above. + +. Review the `configure-remote-broker.cli` file in the root of this quickstart directory. This script adds the `test` queue to the `messaging-activemq` subsystem in the server configuration file. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-remote-broker.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +. You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +"outcome" => "success", +"response-headers" => {"process-state" => "reload-required"} +---- + +. Stop the {productName} server. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file and review the changes. + +The following `testQueue` jms-queue was configured in the configuration of the `messaging-activemq` subsystem. + +[source,xml,options="nowrap"] +---- + + +---- + +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +=== Investigate the Server Console Output + +Look at the {productName} console or Server log and you should see log messages like the following: + +[source,options="nowrap"] +---- +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 2 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-7 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 3 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-5 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 4 +INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5 +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] + +// Additional information about this script +This script removes the remote broker connection from the `messaging-activemq` subsystem and restore the `default` internal broker. You should see the following result when you run the script: + +[source,options="nowrap"] +---- +"outcome" => "success", +"response-headers" => { + "operation-requires-reload" => true, + "process-state" => "reload-required" +} +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] + +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +[NOTE] +==== +The integration tests expect a running {BrokerProductName} broker, so make sure you have started the broker before you begin. +==== +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] + +endif::[] + +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +=== Deploy a {BrokerProductName} instance on OpenShift + +[source,options="nowrap",subs="+attributes"] +---- +$ oc run artemis --env AMQ_USER=admin --env AMQ_PASSWORD=admin --image={BrokerImageName} --port=61616 --expose=true +---- + +This will create a broker instance named `artemis` on OpenShift that can be accessed on the port `61616` on the service `artemis` with the account *admin/admin*. +//Prepare Helm for Quickstart Deployment + +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +==== Clean Up + +The broker instance can be deleted from OpenShift by running the command: + +[source,options="nowrap"] +---- +$ oc delete service artemis +service "artemis" deleted +$ oc delete pod artemis +pod "artemis" deleted +---- + diff --git a/remote-helloworld-mdb/README.adoc b/remote-helloworld-mdb/README.adoc index 419c1f884d..c7260b98b0 100644 --- a/remote-helloworld-mdb/README.adoc +++ b/remote-helloworld-mdb/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: remote-helloworld-mdb +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = remote-helloworld-mdb: Helloworld Using an MDB (Message-Driven Bean) and a Remote Artemis broker :author: Serge Pagop, Andy Taylor, Jeff Mesnil @@ -36,11 +233,66 @@ This project uses two JMS resources on a remote broker: //************************************************* // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: //Start the {BrokerProductName} broker. // build and run with standard server distribution @@ -101,9 +353,230 @@ The following `testQueue` jms-queue was configured in the configuration of the ` ---- // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -123,7 +596,31 @@ INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveM ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Additional information about this script This script removes the remote broker connection from the `messaging-activemq` subsystem and restore the `default` internal broker. You should see the following result when you run the script: @@ -138,9 +635,105 @@ This script removes the remote broker connection from the `messaging-activemq` s ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] +:leveloffset: +3 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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::[] -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +// 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: + +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: [NOTE] ==== @@ -148,11 +741,587 @@ The integration tests expect a running {BrokerProductName} broker, so make sure ==== // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: remote-helloworld-mdb +deploy: + replicas: 1 + env: + # Env vars to connect to Artemis + - name: JBOSS_MESSAGING_CONNECTOR_HOST + value: "artemis" + - name: JBOSS_MESSAGING_CONNECTOR_PORT + value: "61616" +---- +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[] + + +[[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 + +// 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[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +[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 + +:leveloffset!: === Deploy a {BrokerProductName} instance on OpenShift [source,options="nowrap",subs="+attributes"] @@ -163,7 +1332,324 @@ $ oc run artemis --env AMQ_USER=admin --env AMQ_PASSWORD=admin --image={BrokerIm This will create a broker instance named `artemis` on OpenShift that can be accessed on the port `61616` on the service `artemis` with the account *admin/admin*. //Prepare Helm for Quickstart Deployment -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: remote-helloworld-mdb +deploy: + replicas: 1 + env: + # Env vars to connect to Artemis + - name: JBOSS_MESSAGING_CONNECTOR_HOST + value: "artemis" + - name: JBOSS_MESSAGING_CONNECTOR_PORT + value: "61616" +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: ==== Clean Up @@ -176,4 +1662,3 @@ service "artemis" deleted $ oc delete pod artemis pod "artemis" deleted ---- - diff --git a/remote-helloworld-mdb/charts/helm.yaml b/remote-helloworld-mdb/charts/helm.yaml index ee322eddb0..6cb1ee62b9 100644 --- a/remote-helloworld-mdb/charts/helm.yaml +++ b/remote-helloworld-mdb/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: remote-helloworld-mdb deploy: replicas: 1 diff --git a/remote-helloworld-mdb/pom.xml b/remote-helloworld-mdb/pom.xml index eb901c6119..c98560bf6b 100644 --- a/remote-helloworld-mdb/pom.xml +++ b/remote-helloworld-mdb/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 remote-helloworld-mdb - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: remote-helloworld-mdb This project demonstrates a hello world Message-Driven Bean with Servlet 6.0 as client to a remote Artemis instance @@ -45,9 +45,9 @@ - 31.0.0.Beta1 + 31.0.0.Final - ${version.server} + ${version.server} 5.0.0.Beta2 5.10.0 diff --git a/security-domain-to-domain/README-source.adoc b/security-domain-to-domain/README-source.adoc new file mode 100644 index 0000000000..75d727716f --- /dev/null +++ b/security-domain-to-domain/README-source.adoc @@ -0,0 +1,272 @@ +include::../shared-doc/attributes.adoc[] + += security-domain-to-domain: Identity propagation to an EJB using different security domains +:author: Darran Lofthouse +:level: Advanced +:technologies: Servlet, EJB, Security + +[abstract] +The `security-domain-to-domain` quickstart demonstrates the propagation of an identity across two different deployments using different security domains. + +:standalone-server-type: default +:archiveType: war +:uses-h2: +:restoreScriptName: restore-configuration.cli + + +== What is it? + +The `security-domain-to-domain` quickstart demonstrates the propagation of an identity across two different deployments using different security domains. + +When you deploy this example, one user is automatically created for you: user `quickstartUser` with password `quickstartPwd1!` This data is located in the `web/src/main/resources/import.sql` file. + +This quickstart takes the following steps to implement Servlet security: + +Web Application:: + +* Adds a security constraint to the Servlet using the `@ServletSecurity` and `@HttpConstraint` annotations. +* Adds a security domain reference to `WEB-INF/jboss-web.xml`. +* Adds a `login-config` that sets the `auth-method` to `BASIC` in the `WEB-INF/web.xml`. + +EJB Application:: + +* Adds a security domain reference using the @org.jboss.ejb3.annotation.SecurityDomain annotation. + +Application Server (`standalone.xml`):: + +* Defines a security domain in the `elytron` subsystem that uses the JDBC security realm to obtain the security data used to authenticate and authorize users. +* Defined a second security domain in the `elytron` subsystem similar to the first but with different role mappings. +* Adds an `application-security-domain` mapping in the `undertow` subsystem to map the Servlet security domain to the security domain defined in step 1. +* Adds an `application-security-domain` mapping in the `ejb3` subystem to map the EJBs security domain to the security domain defined in step 2. +Database Configuration:: + +* Adds an application user with access rights to the application. ++ +[source,options="nowrap"] +---- +User Name: quickstartUser +Password: quickstartPwd1! +---- ++ +When used with the `entry-domain`, this user will have the role `Users`. When used with the `business-domain`, this user will have the role `Manager`. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// Additional add user instructions + +When used with the `entry-domain` this will have the role `Users`, when used with the `business-domain` this will have the role `Manager`. + +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] + +[[configure_the_server]] +== Configure the {productName} Server + +You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server] with the standalone default profile as described above. + +. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds security domains to the `elytron` subsystem in the server configuration and also configures the `undertow` and `ejb3` subsystems to use the configured security domains for the Web application and for EJBs. +. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing __{jbossHomeName}__ with the path to your server: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. ++ + +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following datasource was added to the `datasources` subsystem. ++ +[source,xml,options="nowrap"] +---- + + jdbc:h2:mem:servlet-security;DB_CLOSE_ON_EXIT=FALSE + h2 + + sa + sa + + +---- + +. The following security realms were added to the `elytron` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + + + + + + + + +---- + +. The `entry-realm` security realm is responsible for verifying the credentials for a given principal and for obtaining security attributes (like roles) that are associated with the authenticated identity. ++ +[source, xml] +[source,xml,options="nowrap"] +---- + + + + + + + + + + +---- + +. The `business-realm` security realm is just used for loading the identity as it accesses the EJB. + +. The JDBC realms in this quickstart store the roles associated with a principal in an attribute named `Roles`. ++ +Other realms might use different attributes for roles (such as `group`). +If an attribute name other than "Roles" is used to store the roles, a `role-decoder` can be configured as follows: ++ +``` +/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=ATTRIBUTE_NAME) +``` ++ +The commands to create the security domains could then be updated to reference this `role-decoder`: ++ +``` +/subsystem=elytron/security-domain=entry-security-domain:add(default-realm=entry-realm, realms=[{realm=entry-realm, role-decoder=from-roles-attribute}], permission-mapper=default-permission-mapper, outflow-security-domains=[business-security-domain]) + +/subsystem=elytron/security-domain=business-security-domain:add(default-realm=business-realm, realms=[{realm=business-realm, role-decoder=from-roles-attribute}], trusted-security-domains=[entry-security-domain]) +``` ++ +The purpose of a `role-decoder` is to instruct the security domain how roles are to be retrieved from an authorized identity. +. The following security domains were added to the `elytron` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + + + + + +---- ++ +The `entry-security-domain` is configured to automatically outflow any identities to the `business-security-domain` and in return the `business-security-domain` is configured to trust any identities coming from the `entry-security-domain`. + +. The following `application-security-domain` was added to the `undertow` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +This configuration tells `Undertow` that applications with the `EntryDomain` security domain, as defined in the `jboss-web.xml` or by using the `@SecurityDomain` annotation in the Servlet class, should use the `security-domain` named `entry-security-domain`. + +. The following `application-security-domain` was added to the `ejb3` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + +---- ++ +This configuration tells `EJB3` that applications with the `BusinessDomain` security domain, as defined in the `jboss.xml` or by using the `@SecurityDomain` annotation in the EJB class, should use the `security-domain` named `business-security-domain`. + +. When you have finished reviewing the configuration changes, xref:start_the_eap_standalone_server[start the {productName} server] with the standalone default profile as described above before you build and deploy the quickstart. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/ + +When you access the application, you should get a browser login challenge. + +Log in using the username `quickstartUser` and password `quickstartPwd1!`. The browser will display the following security info: + +[source,options="nowrap"] +---- +Successfully called Secured Servlet +Identity as visible to servlet. + +Principal : quickstartUser + +Remote User : quickstartUser + +Authentication Type : BASIC + +Caller Has Role 'User'=true + +Caller Has Role 'Manager'=false +Identity as visible to EJB. + +Principal : quickstartUser + +Caller Has Role 'User'=false + +Caller Has Role 'Manager'=true +---- + +This shows that the user `quickstartUser` calls the servlet and has role `User` but does not have the role `Manager`, as the call reaches the EJB the principal is still `quickstartUser` but now the identity does not have the role `User` and instead has the role `Manager`. + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional JBDS instructions + +* Be sure to configure the server by running the JBoss CLI commands as described above under xref:configure_the_server[Configure the {productName} Server]. Stop the server at the end of that step. +* Be sure to xref:restore_the_standalone_server_configuration[Restore the Server Configuration] when you have completed testing this quickstart. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/security-domain-to-domain/README.adoc b/security-domain-to-domain/README.adoc index 75d727716f..4753e0ef14 100644 --- a/security-domain-to-domain/README.adoc +++ b/security-domain-to-domain/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: security-domain-to-domain +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = security-domain-to-domain: Identity propagation to an EJB using different security domains :author: Darran Lofthouse @@ -51,20 +248,269 @@ Password: quickstartPwd1! When used with the `entry-domain`, this user will have the role `Users`. When used with the `business-domain`, this user will have the role `Manager`. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Additional add user instructions When used with the `entry-domain` this will have the role `Users`, when used with the `business-domain` this will have the role `Manager`. // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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!: [[configure_the_server]] == Configure the {productName} Server @@ -207,7 +653,114 @@ This configuration tells `EJB3` that applications with the `BusinessDomain` secu . When you have finished reviewing the configuration changes, xref:start_the_eap_standalone_server[start the {productName} server] with the standalone default profile as described above before you build and deploy the quickstart. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -243,15 +796,164 @@ Caller Has Role 'Manager'=true This shows that the user `quickstartUser` calls the servlet and has role `User` but does not have the role `Manager`, as the call reaches the EJB the principal is still `quickstartUser` but now the identity does not have the role `User` and instead has the role `Manager`. // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +:leveloffset: +1 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional JBDS instructions @@ -259,7 +961,33 @@ include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[levelof * Be sure to xref:restore_the_standalone_server_configuration[Restore the Server Configuration] when you have completed testing this quickstart. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -269,4 +997,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/security-domain-to-domain/ear/pom.xml b/security-domain-to-domain/ear/pom.xml index 07fc17d52a..b767dc6f2c 100644 --- a/security-domain-to-domain/ear/pom.xml +++ b/security-domain-to-domain/ear/pom.xml @@ -26,7 +26,7 @@ org.wildfly.quickstarts security-domain-to-domain - 31.0.0.Final-SNAPSHOT + 31.0.0.Final security-domain-to-domain-ear ear @@ -65,7 +65,7 @@ - 7 + 8 diff --git a/security-domain-to-domain/ejb/pom.xml b/security-domain-to-domain/ejb/pom.xml index f47366e3b0..868b78c312 100644 --- a/security-domain-to-domain/ejb/pom.xml +++ b/security-domain-to-domain/ejb/pom.xml @@ -26,7 +26,7 @@ org.wildfly.quickstarts security-domain-to-domain - 31.0.0.Final-SNAPSHOT + 31.0.0.Final security-domain-to-domain-ejb Quickstart: security-domain-to-domain - ejb diff --git a/security-domain-to-domain/pom.xml b/security-domain-to-domain/pom.xml index 8b57d8319c..f998bcb65d 100644 --- a/security-domain-to-domain/pom.xml +++ b/security-domain-to-domain/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 security-domain-to-domain - 31.0.0.Final-SNAPSHOT + 31.0.0.Final pom Quickstart: security-domain-to-domain This project demonstrates identity propagation between different security domains diff --git a/security-domain-to-domain/web/pom.xml b/security-domain-to-domain/web/pom.xml index 37ffb9665e..31fae3dc9a 100644 --- a/security-domain-to-domain/web/pom.xml +++ b/security-domain-to-domain/web/pom.xml @@ -26,7 +26,7 @@ org.wildfly.quickstarts security-domain-to-domain - 31.0.0.Final-SNAPSHOT + 31.0.0.Final ../pom.xml security-domain-to-domain-web diff --git a/servlet-async/README-source.adoc b/servlet-async/README-source.adoc new file mode 100644 index 0000000000..bfbe219b74 --- /dev/null +++ b/servlet-async/README-source.adoc @@ -0,0 +1,51 @@ +include::../shared-doc/attributes.adoc[] + += servlet-async: How to Write an Asynchronous Servlet +:author: Christian Sadilek +:level: Intermediate +:technologies: Asynchronous Servlet, CDI, EJB +:openshift: true + +[abstract] +The `servlet-async` quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `servlet-async` quickstart is a sample project showing the use of asynchronous servlets in {productNameFull}. + +It shows how to detach the execution of a long-running task from the request processing thread, so the thread is free to serve other client requests. The long-running tasks are executed using a dedicated thread pool and create the client response asynchronously. + +A long-running task in this context does not refer to a computation intensive task executed on the same machine but could for example be contacting a third-party service that has limited resources or only allows for a limited number of concurrent connections. Moving the calls to this service into a separate and smaller sized thread pool ensures that less threads will be busy interacting with the long-running service and that more requests can be served that do not depend on this service. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL http://localhost:8080/{artifactId}/. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/servlet-async/README.adoc b/servlet-async/README.adoc index b25d1f48f7..1317571a93 100644 --- a/servlet-async/README.adoc +++ b/servlet-async/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: servlet-async +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = servlet-async: How to Write an Asynchronous Servlet :author: Christian Sadilek @@ -22,31 +219,920 @@ It shows how to detach the execution of a long-running task from the request pro A long-running task in this context does not refer to a computation intensive task executed on the same machine but could for example be contacting a third-party service that has limited resources or only allows for a limited number of concurrent connections. Moving the calls to this service into a separate and smaller sized thread pool ensures that less threads will be busy interacting with the long-running service and that more requests can be served that do not depend on this service. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application The application will be running at the following URL http://localhost:8080/{artifactId}/. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + contextDir: servlet-async +deploy: + replicas: 2 +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/servlet-async/charts/helm.yaml b/servlet-async/charts/helm.yaml index 7aac2f622d..01fdecbd0a 100644 --- a/servlet-async/charts/helm.yaml +++ b/servlet-async/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: servlet-async deploy: replicas: 2 \ No newline at end of file diff --git a/servlet-async/pom.xml b/servlet-async/pom.xml index c0eaa5275a..53c58ba4e0 100644 --- a/servlet-async/pom.xml +++ b/servlet-async/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 servlet-async - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: servlet-async This project demonstrates an asynchronous Servlet @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/servlet-filterlistener/README-source.adoc b/servlet-filterlistener/README-source.adoc new file mode 100644 index 0000000000..2322bd1ff7 --- /dev/null +++ b/servlet-filterlistener/README-source.adoc @@ -0,0 +1,98 @@ +include::../shared-doc/attributes.adoc[] + += servlet-filterlistener: How to Write Servlet Filters and Listeners +:author: Jonathan Fuerth +:level: Intermediate +:technologies: Servlet Filter, Servlet Listener +:openshift: true + +[abstract] +The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in an application. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in {productNameFull}. + +This example contains the following classes: + +* `FilterExampleServlet`: A simple servlet that prints a form that contains an input field and a _Send_ button. +* `VowelRemoverFilter`: A servlet filter that removes the vowels from the text entered in the form. +* `ParameterDumpingRequestListener`: A simple servlet request listener that creates a map of the original HTTP request parameter values before the filter is applied. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL http://localhost:8080/{artifactId}/. + +You are presented with a form containing an input field and a _Send_ button. To test the quickstart: + +. Enter some text in the field, for example: ++ +[source,options="nowrap"] +---- +This is only a test! +---- + +. Click _Send_. +. The servlet filter intercepts and removes the vowels from the text entered in the form and displays: ++ +[source,options="nowrap"] +---- +You Typed: Ths s nly tst! +---- + +. The server console displays the following log messages. ++ +The following messages appear in the log when you access the application URL. This is because the ParameterDumpingRequestListener, which is a ServletRequestListener, and the VowelRemoverFilter both map to the application context and print logs for every request. Note that the VowelRemoveFilter contains logic to handle empty input field arguments. ++ +[source,options="nowrap"] +---- +INFO [io.undertow.servlet] (default task-46) ParameterDumpingRequestListener: request has been initialized. It has 0 parameters: +INFO [io.undertow.servlet] (default task-46) VowelRemoverFilter initialized +INFO [io.undertow.servlet] (default task-46) VowelRemoverFilter invoking filter chain... +INFO [io.undertow.servlet] (default task-46) VowelRemoverFilter done filtering request +INFO [io.undertow.servlet] (default task-46) ParameterDumpingRequestListener: request has been destroyed +INFO [io.undertow.servlet] (default task-48) ParameterDumpingRequestListener: request has been initialized. It has 0 parameters: +INFO [io.undertow.servlet] (default task-48) VowelRemoverFilter invoking filter chain... +INFO [io.undertow.servlet] (default task-48) VowelRemoverFilter done filtering request +INFO [io.undertow.servlet] (default task-48) ParameterDumpingRequestListener: request has been destroyed +---- ++ +The following messages appear in the log when you type "This is only a test!" in the input field and click `Send`. ++ +[source,options="nowrap"] +---- +INFO [io.undertow.servlet] (default task-50) ParameterDumpingRequestListener: request has been initialized. It has 1 parameters: +INFO [io.undertow.servlet] (default task-50) userInput=This is only a test! +INFO [io.undertow.servlet] (default task-50) VowelRemoverFilter invoking filter chain... +INFO [io.undertow.servlet] (default task-50) VowelRemoverFilter done filtering request +INFO [io.undertow.servlet] (default task-50) ParameterDumpingRequestListener: request has been destroyed +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/servlet-filterlistener/README.adoc b/servlet-filterlistener/README.adoc index 53acc4f786..0e2baedd62 100644 --- a/servlet-filterlistener/README.adoc +++ b/servlet-filterlistener/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: servlet-filterlistener +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = servlet-filterlistener: How to Write Servlet Filters and Listeners :author: Jonathan Fuerth @@ -24,19 +221,295 @@ This example contains the following classes: * `ParameterDumpingRequestListener`: A simple servlet request listener that creates a map of the original HTTP request parameter values before the filter is applied. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -88,12 +561,625 @@ INFO [io.undertow.servlet] (default task-50) ParameterDumpingRequestListener: r ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file + +ifdef::ProductRelease,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: servlet-filterlistener +deploy: + replicas: 2 +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/servlet-filterlistener/charts/helm.yaml b/servlet-filterlistener/charts/helm.yaml index dca2e1b81e..fbab31ea12 100644 --- a/servlet-filterlistener/charts/helm.yaml +++ b/servlet-filterlistener/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: servlet-filterlistener deploy: replicas: 2 \ No newline at end of file diff --git a/servlet-filterlistener/pom.xml b/servlet-filterlistener/pom.xml index f5fef339dc..ed6813c2d9 100644 --- a/servlet-filterlistener/pom.xml +++ b/servlet-filterlistener/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 servlet-filterlistener - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: servlet-filterlistener This project demonstrates a Servlet Filter and Listener @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/servlet-security/README-source.adoc b/servlet-security/README-source.adoc new file mode 100644 index 0000000000..234aae9d87 --- /dev/null +++ b/servlet-security/README-source.adoc @@ -0,0 +1,223 @@ +include::../shared-doc/attributes.adoc[] + += servlet-security: Using Jakarta EE Declarative Security to Control Servlet Access +:author: Sherif F. Makary, Pedro Igor, Stefan Guilhen +:level: Intermediate +:technologies: Servlet, Security +:openshift: true + +[abstract] +The `servlet-security` quickstart demonstrates the use of Jakarta EE declarative security to control access to Servlets and Security in {productName}. + +:standalone-server-type: default +:archiveType: war +:uses-h2: +:restoreScriptName: restore-configuration.cli + +== What is it? + +The `servlet-security` quickstart demonstrates the use of Jakarta EE declarative security to control access to Servlets and Security in {productNameFull}. + +When you deploy this example, two users are automatically created for you: user `quickstartUser` with password `quickstartPwd1!` and user `guest` with password `guestPwd1!`. This data is located in the `src/main/resources/import.sql` file. + +This quickstart takes the following steps to implement Servlet security: + +. Web Application: +** Adds a security constraint to the Servlet using the `@ServletSecurity` and `@HttpConstraint` annotations. +** Adds a security domain reference to `WEB-INF/jboss-web.xml`. +** Adds a `login-config` that sets the `auth-method` to `BASIC` in the `WEB-INF/web.xml`. +. Application Server (`standalone.xml`): +** Defines a security domain in the `elytron` subsystem that uses the JDBC security realm to obtain the security data used to authenticate and authorize users. +** Adds an `application-security-domain` mapping in the `undertow` subsystem to map the Servlet security domain to the security domain defined in step 1. +. Database Configuration: +** Adds an application user with access rights to the application. ++ +[source,options="nowrap"] +---- +User Name: quickstartUser +Password: quickstartPwd1! +Role: quickstarts +---- + +** Adds another user with no access rights to the application. ++ +[source,options="nowrap"] +---- +User Name: guest +Password: guestPwd1! +Role: notauthorized +---- + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +// Back Up the {productName} Standalone Server Configuration +include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] + +[[configure_the_server]] +=== Configure the Server + +You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above. + +. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds security domain and HTTP authentication factory to the `elytron` subsystem in the server configuration and also configures the `undertow` subsystem to use the configured HTTP authentication factory for the Web application. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following datasource was added to the `datasources` subsystem. ++ +[source,xml,options="nowrap"] +---- + + jdbc:h2:mem:servlet-security;DB_CLOSE_ON_EXIT=FALSE + h2 + + sa + sa + + +---- + +. The following `security-realm` was added to the `elytron` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + + + + + + + + +---- ++ +The `security-realm` is responsible for verifying the credentials for a given principal and for obtaining security attributes (like roles) that are associated with the authenticated identity. + +. The `jdbc-realm` in this quickstart stores the roles associated with a principal in an attribute named `Roles`. ++ +Other realms might use different attributes for roles (such as `group`). +If an attribute name other than "Roles" is used to store the roles, a `role-decoder` can be configured as follows: ++ +``` +/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=ATTRIBUTE_NAME) +``` ++ +The command to create a `security-domain` could then be updated to reference this `role-decoder`: ++ +``` +/subsystem=elytron/security-domain=servlet-security-quickstart-sd:add(default-realm=servlet-security-jdbc-realm, realms=[{realm=servlet-security-jdbc-realm, role-decoder=from-roles-attribute}], permission-mapper=default-permission-mapper) +``` ++ +The purpose of a `role-decoder` is to instruct the security domain how roles are to be retrieved from an authorized identity. + + +. The following `security-domain` was added to the `elytron` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +. The following `application-security-domain` was added to the `undertow` subsystem. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +This configuration tells `Undertow` that applications with the `servlet-security-quickstart` security domain, as defined in the `jboss-web.xml` or by using the `@SecurityDomain` annotation in the Servlet class, should use the `security-domain` named `servlet-security-quickstart-sd`. + +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL http://localhost:8080/{artifactId}/. + +When you access the application, you should get a browser login challenge. + +Log in using the username `quickstartUser` and password `quickstartPwd1!`. The browser will display the following security info: + +[source,options="nowrap"] +---- +Successfully called Secured Servlet + +Principal : quickstartUser +Remote User : quickstartUser +Authentication Type : BASIC +---- + +Now close the browser. Open a new browser and log in with username `guest` and password `guestPwd1!`. The browser will display the following error: + +[source,options="nowrap"] +---- +Forbidden +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] + +// Additional information about this script +This script removes the `application-security-domain` configuration from the `undertow` subsystem, the `http-authentication-factory`, `security-domain`, `security-realm` and `role-decoder` configuration from the `elytron` subsystem and it also removes the datasource used for this quickstart. You should see the following result when you run the script: + +[source,options="nowrap"] +---- +The batch executed successfully +process-state: reload-required +---- + +// Restore the {productName} Standalone Server Configuration Manually +include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] diff --git a/servlet-security/README.adoc b/servlet-security/README.adoc index fad6e780c2..ed630f1167 100644 --- a/servlet-security/README.adoc +++ b/servlet-security/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: servlet-security +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = servlet-security: Using Jakarta EE Declarative Security to Control Servlet Access :author: Sherif F. Makary, Pedro Igor, Stefan Guilhen @@ -50,21 +247,299 @@ Role: notauthorized ---- // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 // Back Up the {productName} Standalone Server Configuration -include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[back_up_standalone_server_configuration]] += Back Up the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart runs in a standalone server and +// needs to back up the server configuration file before running +// a CLI script to modify the server. +//****************************************************************************** +// Define the attributes needed for this topic. +//****************************************************************************** +// 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[] + +Before you begin, back up your server configuration file. + +. If it is running, stop the {productName} server. +. Back up the `__{jbossHomeName}__/{configFileName}` file. + +After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. + +:leveloffset!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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!: [[configure_the_server]] === Configure the Server @@ -171,7 +646,114 @@ The purpose of a `role-decoder` is to instruct the security domain how roles are This configuration tells `Undertow` that applications with the `servlet-security-quickstart` security domain, as defined in the `jboss-web.xml` or by using the `@SecurityDomain` annotation in the Servlet class, should use the `security-domain` named `servlet-security-quickstart-sd`. // Build and Deploy the Quickstart -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -198,12 +780,88 @@ Forbidden ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Additional information about this script This script removes the `application-security-domain` configuration from the `undertow` subsystem, the `http-authentication-factory`, `security-domain`, `security-realm` and `role-decoder` configuration from the `elytron` subsystem and it also removes the datasource used for this quickstart. You should see the following result when you run the script: @@ -215,10 +873,657 @@ process-state: reload-required ---- // Restore the {productName} Standalone Server Configuration Manually -include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3] +:leveloffset: +3 + +[[restore_standalone_server_configuration_manually]] += Restore the {productName} Standalone Server Configuration Manually +//****************************************************************************** +// Include this template if your quickstart does a normal manual restoration +// of a single standalone 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[] + +When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. + +. If it is running, stop the {productName} server. +. Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. + +:leveloffset!: // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +[[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: 31.x + contextDir: servlet-security +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/servlet-security/charts/helm.yaml b/servlet-security/charts/helm.yaml index 6d710d083a..195afdbcaa 100644 --- a/servlet-security/charts/helm.yaml +++ b/servlet-security/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: servlet-security deploy: replicas: 1 diff --git a/servlet-security/pom.xml b/servlet-security/pom.xml index 3c021d48c3..7aa43971ec 100644 --- a/servlet-security/pom.xml +++ b/servlet-security/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 servlet-security - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: servlet-security This project demonstrates servlet security in JBoss EAP @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/shared-doc/attributes.adoc b/shared-doc/attributes.adoc index 18d6dbae8e..c7fae8bffb 100644 --- a/shared-doc/attributes.adoc +++ b/shared-doc/attributes.adoc @@ -62,7 +62,7 @@ ifndef::ProductRelease,EAPXPRelease[] :productImageVersion: 31.0 :githubRepoUrl: https://github.com/wildfly/quickstart/ :githubRepoCodeUrl: https://github.com/wildfly/quickstart.git -:WildFlyQuickStartRepoTag: 31.0.0.Beta1 +:WildFlyQuickStartRepoTag: 31.0.0.Final :DocInfoProductName: Red Hat JBoss Enterprise Application Platform :DocInfoProductNameURL: red_hat_jboss_enterprise_application_platform // Do not update the following until after the 7.4 docs are published! diff --git a/spring-resteasy/README-source.adoc b/spring-resteasy/README-source.adoc new file mode 100644 index 0000000000..f2ddc0be25 --- /dev/null +++ b/spring-resteasy/README-source.adoc @@ -0,0 +1,77 @@ +include::../shared-doc/attributes.adoc[] + += spring-resteasy: Example Using Resteasy Spring Integration +:author: Weinan Li , Paul Gier +:level: Beginner +:technologies: Resteasy, Spring +:openshift: true +:buildRequirements: Java 17 (Java SDK 17) or later and Maven 3.3.1 or later + +[abstract] +The `spring-resteasy` quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration. + +:standalone-server-type: default +:archiveType: war +:jbds-not-supported: + +== What is it? + +The `spring-resteasy` quickstart demonstrates how to package and deploy a web application, which includes resteasy-spring integration, in +{productNameFull}. + + +//************************************************* +// Product Release content only +//************************************************* + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +This page provides links to the following URLs that demonstrate various path and parameter configurations. + +* http://localhost:8080/{artifactId}/hello?name=yourname[{artifactId}/hello?name=yourname] +* http://localhost:8080/{artifactId}/basic[{artifactId}/basic] +* http://localhost:8080/{artifactId}/queryParam?param=query[{artifactId}/queryParam?param=query] +* http://localhost:8080/{artifactId}/matrixParam;param=matrix[{artifactId}/matrixParam;param=matrix] +* http://localhost:8080/{artifactId}/uriParam/789[{artifactId}/uriParam/789] + +It also provides the set of URLs that use the `locating` path. + +* http://localhost:8080/{artifactId}/locating/hello?name=yourname[{artifactId}/locating/hello?name=yourname] +* http://localhost:8080/{artifactId}/locating/basic[{artifactId}/locating/basic] +* http://localhost:8080/{artifactId}/locating/queryParam?param=query[{artifactId}/locating/queryParam?param=query] +* http://localhost:8080/{artifactId}/locating/matrixParam;param=matrix[{artifactId}/locating/matrixParam;param=matrix] +* http://localhost:8080/{artifactId}/locating/uriParam/789[{artifactId}/locating/uriParam/789] + +== Server Log: Expected Warnings and Errors + +You will see the following warnings in the server log. You can ignore these warnings. + +[source,options="nowrap"] +---- +WARN [org.jboss.as.ee] (MSC service thread 1-5) WFLYEE0007: Not installing optional component org.springframework.http.server.ServletServerHttpAsyncRequestControl due to an exception (enable DEBUG log level to see the cause) +WARN [org.jboss.as.ee] (MSC service thread 1-5) WFLYEE0007: Not installing optional component org.springframework.web.context.request.async.StandardServletAsyncWebRequest due to an exception (enable DEBUG log level to see the cause) +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] diff --git a/spring-resteasy/README.adoc b/spring-resteasy/README.adoc index ce8656365f..81844871d9 100644 --- a/spring-resteasy/README.adoc +++ b/spring-resteasy/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: spring-resteasy +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = spring-resteasy: Example Using Resteasy Spring Integration :author: Weinan Li , Paul Gier @@ -26,15 +223,291 @@ The `spring-resteasy` quickstart demonstrates how to package and deploy a web ap //************************************************* // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -67,12 +540,625 @@ WARN [org.jboss.as.ee] (MSC service thread 1-5) WFLYEE0007: Not installing opti ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: spring-resteasy +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/spring-resteasy/charts/helm.yaml b/spring-resteasy/charts/helm.yaml index 4d1d940e24..57fa81e435 100644 --- a/spring-resteasy/charts/helm.yaml +++ b/spring-resteasy/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: spring-resteasy deploy: replicas: 1 \ No newline at end of file diff --git a/spring-resteasy/pom.xml b/spring-resteasy/pom.xml index 6aeda2d566..062448c9f9 100644 --- a/spring-resteasy/pom.xml +++ b/spring-resteasy/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 spring-resteasy - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: spring-resteasy This project demonstrates Spring with a JAX-RS RestEasy client @@ -49,7 +49,7 @@ 17 - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/tasks-jsf/README-source.adoc b/tasks-jsf/README-source.adoc new file mode 100644 index 0000000000..4fd0c92201 --- /dev/null +++ b/tasks-jsf/README-source.adoc @@ -0,0 +1,99 @@ +include::../shared-doc/attributes.adoc[] + += tasks-jsf: JSF, JPA quickstart +:author: Lukas Fryc +:level: Intermediate +:technologies: JSF, JPA +:openshift: true + +[abstract] +The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. + +:standalone-server-type: default +:archiveType: war +:uses-h2: +:uses-ds-xml: +:performance-scalability: + +== What is it? + +The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as view layer in an application deployed to {productNameFull}. It provides a JSF front end for the link:../tasks/README.adoc[tasks] quickstart. + +The theme of this application is simple Task management with simple login. The project contains two entities - a `user` and a `task`. + +This sample includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. Persistence code is covered by tests to help you write business logic without the need to use any view layer. + +JSF is used to present the user two views. + +* authentication form: This provides the simple login +* task view: This view contains the task list, a task detail, and a task addition form. The task view uses AJAX. + +//************************************************* +// Product Release content only +//************************************************* + +ifndef::EAPCDRelease[] + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +// Start the {productName} Standalone Server +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] + +== Access the Application + +The application will be running at the following URL http://localhost:8080/{artifactId}/. + +== Server Log: Expected Warnings and Errors + +You will see the following warnings in the server log. You can ignore these warnings. + +[source,options="nowrap"] +---- +WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. + +HHH000431: Unable to determine H2 database version, certain features may not work +---- + +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +// Run the Arquillian Tests +include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +== Debug the Application + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +---- +endif::[] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Getting Started with OpenShift +include::../shared-doc/openshift-getting-started.adoc[leveloffset=+1] +//Prepare OpenShift for Quickstart Deployment +include::../shared-doc/openshift-create-project.adoc[leveloffset=+1] +// Import the Latest {xpaasproduct-shortname} Image Streams and Templates +include::../shared-doc/openshift-import-imagestreams-templates.adoc[leveloffset=+1] +// Deploy the {ProductShortName} Source-to-Image (S2I) Quickstart to OpenShift +include::../shared-doc/openshift-deploy-project.adoc[leveloffset=+1] +// Openshift post deployment tasks +include::../shared-doc/openshift-post-deployment-tasks.adoc[leveloffset=+1] + + +endif::[] \ No newline at end of file diff --git a/tasks-jsf/README.adoc b/tasks-jsf/README.adoc index 4fd0c92201..899ff9badc 100644 --- a/tasks-jsf/README.adoc +++ b/tasks-jsf/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: tasks-jsf +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = tasks-jsf: JSF, JPA quickstart :author: Lukas Fryc @@ -35,17 +232,322 @@ JSF is used to present the user two views. ifndef::EAPCDRelease[] // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: // Start the {productName} Standalone Server -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: == Access the Application @@ -63,11 +565,101 @@ HHH000431: Unable to determine H2 database version, certain features may not wor ---- // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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!: // Run the Arquillian Tests -include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_arquillian_tests]] += Run the Arquillian Tests +//****************************************************************************** +// Include this template if your quickstart provides standard Arquillian tests. +//****************************************************************************** + +This quickstart provides Arquillian tests. By default, these tests are configured to be skipped since Arquillian tests require the use of a container. + +NOTE: The Arquillian tests deploy the application, so make sure you undeploy the quickstart before you begin. + +ifdef::arq-prerequisities[] +== Arquillian Tests prerequisities + +{arq-prerequisities} +endif::[] + +Follow these steps to run the tests. + +ifdef::standalone-server-type[] +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +endif::[] + +ifdef::managed-domain-type[] +. xref:start_the_eap_managed_domain[Start the {productName} server] as described above. +endif::[] + +. Open a terminal and navigate to the root directory of this quickstart. +. Type the following command to run the `verify` goal with the `arq-remote` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn clean verify -Parq-remote +---- +ifdef::arquillianTestResults[] +You should see the following results: ++ +[source,subs=attributes+,options="nowrap"] +---- +Results : + +{arquillianTestResults} +---- +endif::[] + +[NOTE] +==== +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile, meaning the tests will start the server for you. This profile requires that you provide Arquillian with the location of the {productName} server, either by setting the `JBOSS_HOME` environment variable, or by setting the `jbossHome` property in the `arquillian.xml` file. For more information, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. +==== + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: == Debug the Application @@ -96,4 +688,4 @@ include::../shared-doc/openshift-deploy-project.adoc[leveloffset=+1] include::../shared-doc/openshift-post-deployment-tasks.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/tasks-jsf/pom.xml b/tasks-jsf/pom.xml index 2851a552d3..578554b347 100644 --- a/tasks-jsf/pom.xml +++ b/tasks-jsf/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 tasks-jsf - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: tasks-jsf This project demonstrates how to use JPA persistence to manage tasks with JSF as view layer diff --git a/temperature-converter/README-source.adoc b/temperature-converter/README-source.adoc new file mode 100644 index 0000000000..b4f2750221 --- /dev/null +++ b/temperature-converter/README-source.adoc @@ -0,0 +1,61 @@ +include::../shared-doc/attributes.adoc[] + += temperature-converter: Stateless Session EJB (SLSB) +:author: Bruce Wolfe +:level: Beginner +:technologies: CDI, JSF, SLSB EJB +:openshift: true + +[abstract] +The `temperature-converter` quickstart does temperature conversion using an EJB Stateless Session Bean (SLSB), CDI, and a JSF front-end client. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `temperature-converter` example demonstrates the use of an EJB Stateless Session Bean (SLSB) and CDI, accessed using a JSF, and deployed to {productNameFull} using a WAR archive. + +The application does the following: + +. The User Interface is a JSF page that asks for a temperature and a scale (Fahrenheit or Celsius). +. When you click on `Convert`, the temperature string is passed to the TemperatureConverter controller (managed) bean. +. The managed bean then invokes the `convert()` method of the injected TemperatureConvertEJB (notice the field annotated with @Inject). +. The response from TemperatureConvertEJB is stored in the `temperature` field of the managed bean. +. The managed bean is annotated as @SessionScoped, so the same managed bean instance is used for the entire session. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +You will be presented with a simple form for temperature conversion. + +. Optionally, Select a scale: Celsius or Fahrenheit. +. Enter a temperature. +. Press the `Convert` button to see the results. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/temperature-converter/README.adoc b/temperature-converter/README.adoc index 8b9b2d8e4f..631e1a4c2a 100644 --- a/temperature-converter/README.adoc +++ b/temperature-converter/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: temperature-converter +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = temperature-converter: Stateless Session EJB (SLSB) :author: Bruce Wolfe @@ -26,19 +223,295 @@ The application does the following: . The managed bean is annotated as @SessionScoped, so the same managed bean instance is used for the entire session. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -51,12 +524,625 @@ You will be presented with a simple form for temperature conversion. . Press the `Convert` button to see the results. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + contextDir: temperature-converter +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/temperature-converter/charts/helm.yaml b/temperature-converter/charts/helm.yaml index 629e4ca523..a439698fb9 100644 --- a/temperature-converter/charts/helm.yaml +++ b/temperature-converter/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: temperature-converter deploy: replicas: 1 \ No newline at end of file diff --git a/temperature-converter/pom.xml b/temperature-converter/pom.xml index d1123a6e5e..bba89bf92b 100644 --- a/temperature-converter/pom.xml +++ b/temperature-converter/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 temperature-converter - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: temperature-converter This project is a temperature converter. Given Celsius return Fahrenheit; Given Fahrenheit return Celsius @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/template/README-source.adoc b/template/README-source.adoc new file mode 100644 index 0000000000..28e9ac4a38 --- /dev/null +++ b/template/README-source.adoc @@ -0,0 +1,473 @@ +include::../shared-doc/attributes.adoc[] + += How to Structure and Write a Quickstart README.adoc File + +== Introduction + +This document describes how to write a quickstart `README.adoc` file. It describes the attributes you must define and the sections needed in the correct order. + +IMPORTANT: The instructions in this template only describe how to create the default instructions to run the quickstart on the WildFly or the JBoss EAP server. If the quickstart will also be deployed to OpenShift, the OpenShift instructions must be added to to this file, and you must use the `EAPCDRelease` flag to determine how to generate the `README.html` file. You can use an existing quickstart `README.adoc` file as a template. + +Many instructions are common across all quickstarts. These have been moved to files located in the `shared-doc/` directory. Rather than write them again, you can just include those files in your `README.adoc` file. Some of these included files have conditional logic and require that you define a document attribute to determine how the instructions should print for your quickstart. + +* You must first xref:define_the_heading[define the heading or title] for your quickstart. +* Next, you must xref:define_the_metadata[define the metadata] that defines the quickstart. +* determine what will display information about the quickstart and how the instructions will look. +* Finally, you must determine which sections are needed for your quickstart and include or write them as needed. + +TIP: Find an existing quickstart that is similar to the one you are creating and make a copy of its `README.adoc` file to use for your own quickstart project. Then update the file as needed. + +[[define_the_heading]] +== Define the Heading + +This is the first line of the `README.adoc` file and it defines the quickstart name and provides a short description. + +* Start the heading with "= ". +* This is followed by the __QUICKSTART_NAME__, which should match the folder name. +* Try to limit the decription to 55 characters as it is displayed in a table and also used in search engines. + +.Example: Quickstart Heading +[source,subs="+quotes",options="nowrap"] +---- += __QUICKSTART_NAME__: Brief Description of the Quickstart (try to limit the description to 55 characters) +---- + +[[define_the_metadata]] +== Define the Metadata for the Quickstart + +. Copy in the following standard metadata attributes and modify where needed. ++ +.Example: Basic Attributes +---- +:author: __YOUR_NAME__ and optional CONTACT_INFO +:productName: WildFly +:productNameFull: WildFly Application Server +:jbossHomeName: WILDFLY_HOME +:productVersion: 19 +:buildRequirements: Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later +---- + +. Include the following shared attribute file. ++ +.Example: Include the attributes.adoc File +---- + include::../shared-doc/attributes.adoc[] +---- + +. Define additional attributes for this quickstart. ++ +Define the following attributes that provide information about the level of expertise required and the technologies used by the quickstart. They are used when building the quickstart table in the root `README.html` file. ++ +.Example: Quickstart Informational Attributes +---- +:level: (one of the following: Beginner, Intermediate, or Advanced) +:technologies: (list technologies used here) +:source: (The URL for the repository that is the source of record for this quickstart) +:prerequisites: (list any quickstarts that must be deployed prior to running this one) +---- + +. Create the abstract. This is also used in the quickstart table in the root `README.html` file. ++ +.Example: Quickstart Abstract +---- +[abstract] +Create a brief description of the quickstart. This description appears in the table and in Google search SEO results. Try to limit the description to 155 characters. +---- + +== Define Conditional Attributes for the Quickstart + +Many commonly used instructions are defined in shared topic files located in the `shared-doc/` folder. Some require that you set attribute values specific to your quickstart that can be used for conditional text. Examples include the following. + +.Example: Attributes Need by Included Shared Topics +[source,subs="+quotes",options="nowrap"] +---- +:standalone-server-type: The server type. valid values are `default`, `full`, `full-ha`, `ha`, `custom`. +:managed-domain-type: Valid values are `default`. +:archiveName: Defaults to `{artifactId}`. Override it if this quickstart is different. +:archiveType: Type of archive. Valid values are `war`, `ear`, and `jar`. +:archiveDir: The archive directory. Override if the other than the default. +:mavenCommand: The command to build and deploy the archive. Override it if it is different. +:configFileName: The name of the management CLI file used for configuration. +:uses-h2: Define this attribute if the quickstart uses the H2 database. +:uses-ds-xml: Define this attribute if the quickstart uses an `*-ds.xml` file. +:performance-scalability: Define this attribute if the user needs to consider scalability when using this quickstart example. +:requires-multiple-servers: Define this attribute if you must start 2 servers. +:optional-domain-or-multiple-servers: Define this attribute if the quickstart requires that you configure and start multiple servers. +:jbds-not-supported: Define this attribute if the quickstart does not run in {JBDSProductName} +:openshift: Define this attribute if the quickstart is compatible with Openshift S2i templates. Valid values are `true` and `false`. +---- + +[[what_is_it]] +== What is it? + +Start the text with "The `__QUICKSTART_NAME__` quickstart demonstrates … in {productNameFull}." + + * You should list the technologies demonstrated by the quickstart. + * You should explain how it works and what to expect when you run it? + +You should include any information that would help the user understand the quickstart. + +If possible, give an overview, including any code they should look at to understand how it works.. + +[[considerations_for_use_in_a_production_environment]] +== Considerations for Use in a Production Environment (optional) + +Add this section only if this quickstart uses the h2 database, an `*-ds.xml` file, or has performance and scalability concerns. This topic is defined in the `shared-doc/development-shortcuts.adoc` file. Define the appropriate attributes: + +* `uses-h2`: The quickstart uses the h2 database. +* `uses-ds-xml`: The quickstart uses an `*-ds.xml` file. +* `performance-scalability`: Performance and scalability are of concern. + +Include this file using the following syntax. + +.Example: include::../shared-doc/development-shortcuts.adoc +[source,options="nowrap"] +---- +//*************************************** +// Add notes about use in a production environment. +//*************************************** +// == Considerations for Use in a Production Environment +// :uses-h2: +// :uses-ds-xml: +// :performance-scalability: + include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +---- + +[[system_requirements]] +== System Requirements + +Always add the system requirements. This topic is defined in the `shared-doc/system-requirements.adoc` file. +Include this file using the following syntax. + +.Example: include::../shared-doc/system-requirements.adoc +[source,options="nowrap"] +---- +//************************************************* +// Add System Requirements +//************************************************* +// == System Requirements + include::../shared-doc/system-requirements.adoc[leveloffset=+1] +---- + +[[use_of_jboss_home_name]] +== Use of {jbossHomeName} + +Add this section if your README file refers to the `__{jbossHomeName}__` variable. + +This topic is located in the `shared-docs/use-of-jboss-home-name.adoc` file. If your quickstart uses 2 servers, make sure to define the `requires-multiple-servers` attribute. + +Include this file using the following syntax. + +.Example: include::../shared-doc/use-of-jboss-home-name.adoc +[source,subs="attributes+",options="nowrap"] +---- +//************************************************* +// Add Use of JBoss Home Name +//************************************************* +// == Use of {jbossHomeName} +:requires-multiple-servers: + include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +---- + +[[configure_optional_components]] +== Configure Optional Components + +* If the quickstart uses a secured management interface and requires that you create a management or application user to access the running application, provide instructions to set up a management or application user. ++ +If you require the standard `quickstartUser`/`quickstartPwd1!` user for the `ApplicationRealm` and the `quickstartAdmin`/`adminPwd1!` for the `ManagementRealm`, you can just include one of the following files: ++ +** include::../shared-doc/add-application-user.adoc[leveloffset=+1] + +** include::../shared-doc/add-application-and-management-users.adoc[leveloffset=+1] ++ +If you require other users, follow the standard format of one of those files. + +* If the quickstart requires the PostgreSQL database, provide instructions to install and configure PostgreSQL. Provide a link to the instructions here here: link:{configurePostgresDocUrl}[Configure the PostgreSQL Database for Use with the Quickstarts] + +* If the quickstart uses Byteman to help demonstrate crash recovery, let them know that instructions to install and configure Byteman can be found here: link:{configureBytemanQuickstartsDocUrl}[Configure Byteman for Use with the Quickstarts] + +[[back_up_standalone_server_configuration]] +== Back Up the {productName} Standalone Server Configuration (optional) + +Add this section if your quickstart uses a standalone server and modifies the standalone server configuration files. Make sure you have defined the `standalone-server-type` attribute. + +This topic is located in the `shared-docs/back-up-server-standalone-configuration.adoc` file. + +Include this file using the following syntax. + +.Example: include::../shared-doc/back-up-server-standalone-configuration.adoc +[source,options="nowrap"] +---- +//************************************************* +// Back up the server configuration files +//************************************************* +// == Back Up the {productName} Standalone Server Configuration +// include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1] +---- + +[[back_up_managed_domain_configuration]] +== Back Up the {productName} Managed Domain Configuration (optional) + +Add this section if your quickstart uses a managed domain and modifies the domain configuration files. + +This topic is located in the `shared-docs/back-up-managed-domain-configuration.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/back-up-managed-domain-configuration.adoc +[source,options="nowrap"] +---- +//************************************************* +// Back up the server configuration files +//************************************************* +// == Back Up the {productName} Managed Domain Configuration + include::../shared-doc/back-up-managed-domain-configuration.adoc[leveloffset=+1] +---- + +[[start_the_eap_standalone_server]] +== Start the {productName} Standalone Server (optional) + +Add this section if your quickstart uses a standalone server. Make sure you have defined the `standalone-server-type` attribute. + +This topic is located in the `shared-docs/start-the-standalone-server.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/start-the-standalone-server.adoc +[source,options="nowrap"] +---- +//************************************************* +// Start the server +//************************************************* +// == Start the {productName} Standalone Server + include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1] +---- + +[[start_the_eap_managed_domain]] +== Start the {productName} Managed Domain (optional) + +Add this section if your quickstart uses a managed domain. + +This topic is located in the `shared-docs/start-the-managed-domain.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/start-the-managed-domain.adoc +[source,options="nowrap"] +---- +//************************************************* +// Start the managed domain +//************************************************* +// == Start the {productName} Managed Domain + include::../shared-doc/start-the-managed-domain.adoc[leveloffset=+1] +---- + +[[configure_the_server]] +== Configure the Server (optional) + +Add this section if your quickstart provides a CLI script to modify the server configuration file. + +* Provide the name of the script and provide an overview of what it does. +* Remind them to back up the current configuration and start the server. +* Suggest that they review the script and describe any details of importance. +* Provide instructions for running the script. You can use examples from other quickstarts that configure the server. +* Let the user know what the result output will look like. +* Stop the {productName} server if you plan to review the resulting XML configuration changes. + +== Review the Modified Server Configuration (optional) + +Add this section if your quickstart provides a CLI script to modify the server configuration file and you plan to review the XML changes. + +Point out the changes made after running the CLI script. + +== Build and Deploy the Quickstart (optional) + +Add this section if your quickstart deploys a normal JAR, WAR, or EAR to a __{jbossHomeName}__ server. + +* Make sure you define the `archiveType` attribute. Valid types are: +** :archiveType: ear +** :archiveType: war +** :archiveType: jar + +* You can override the archive name, which defaults to the `{artifactId)` by defining the `{archiveName}`. For example: ++ +[source,options="nowrap"] +---- +:archiveName: {artifactId}-service +---- +* You can override the archive path by defining the `{archiveDir}`. For example: ++ +[source,options="nowrap"] +---- +:archiveDir: {artifactId}/service/target +---- + +This topic is located in the `shared-docs/build-and-deploy-the-quickstart.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/build-and-deploy-the-quickstart.adoc +[source,options="nowrap"] +---- +//************************************************* +// Build and deploy the quickstart +//************************************************* +// == Build and Deploy the Quickstart + include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1] +---- + +[[access_the_application]] +== Access the Application (optional) + +Add this section if you can access your running quickstart using a browser. For example: +[source,options="nowrap"] +---- +Access the running application in a browser at the following URL: http://localhost:8080/{artifactId} +---- + +Describe what the user should look for in the running application. + +[[undeploy_the_quickstart]] +== Undeploy the Quickstart (optional) + +Add this section if your quickstart deploys a normal JAR, WAR, or EAR to a __{jbossHomeName}__ server. + +This topic is located in the `shared-docs/undeploy-the-quickstart.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/undeploy-the-quickstart.adoc +[source,options="nowrap"] +---- +//************************************************* +// Undeploy the quickstart archive +//************************************************* +// == Undeploy the Quickstart + include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1] +---- + +[[run_the_arquillian_tests]] +== Run the Arquillian Tests (optional) + +Add this section if your quickstart provides Arquillian tests. + +This topic is located in the `shared-docs/run-arquillian-tests.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/run-arquillian-tests.adoc +[source,options="nowrap"] +---- +//************************************************* +// Run the Arquillian tests +//************************************************* +// == Run the Arquillian Tests + include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +---- + +You can add additional information if required. + +[[investigate_the_console_output]] +== Investigate the Console Output + +If Arquillian tests provide meaningful output, add this section where you can decribe it. If applicable, copy and paste output from the JUnit tests to show what to expect in the console from the tests. + + +[[investigate_the_server_log]] +== Investigate the Server Log (optional) + +If the quickstart provides interesting information in the server log, include this section. If applicable, copy and paste log messages output by the application to show what to expect in the server log when running the tests. + + +[[run_the_arquillian_functional_tests]] +== Run the Arquillian Functional Tests (optional) + +Add this section if your quickstart provides Arquillian functional tests. + +This topic is located in the `shared-docs/run-arquillian-functional-tests.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/run-arquillian-functional-tests.adoc +[source,options="nowrap"] +---- +//************************************************* +// Run the Arquillian functional tests +//************************************************* +// == Run the Arquillian Functional Tests + include::../shared-doc/run-arquillian-functional-tests.adoc[leveloffset=+1] +---- + +[[restore_the_standalone_server_configuration]] +== Restore the {productName} Standalone Server Configuration (optional) + +Add this section if your quickstart uses a standalone server and modifies the standalone server configuration files. Make sure you define the `restoreScriptName` attribute. + +This topic is located in the `shared-docs/restore-standalone-server-configuration.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/restore-standalone-server-configuration.adoc +[source,options="nowrap"] +---- +//************************************************************ +// Restore the {productName} Standalone Server Configuration +//************************************************************ +// == Restore the {productName} Standalone Server Configuration +:restoreScriptName: __RESTORE_CONFIGURATION_SCRIPT__.cli + include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1] +---- + +You can add additional content about the results after the include. + +[[restore_standalone_server_configuration_manually]] +== Restore the {productName} Standalone Server Configuration Manually (optional) + +Add this section if your quickstart uses a standalone server and modifies the standalone server configuration files. + +.Example: include::../shared-doc/restore-standalone-server-configuration-manual.adoc +[source,options="nowrap"] +---- +//****************************************************** +// Restore the standalone server configuration manually +//****************************************************** +// == Restore the {productName} Standalone Server Configuration Manually + include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2] +---- + +[[restore_managed_domain_configuration_manually]] +== Restore the {productName} Managed Domain Configuration Manually (optional) + +Add this section if your quickstart uses a managed domain and modifies the managed domain configuration files. + +This topic is located in the `shared-docs/restore_managed_domain_configuration_manually.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/restore_managed_domain_configuration_manually.adoc +[source,options="nowrap"] +---- +//****************************************************** +// Restore the domain configuration manually +//****************************************************** +// == Restore the {productName} Managed Domain Configuration Manually + include::../shared-doc/restore-managed-domain-configuration-manual.adoc[leveloffset=+1] +---- + + +== Run the Quickstart in {JBDSProductName} or Eclipse + +Add this section to add instructions for running the quickstart or the Arquillian tests from {JBDSProductName} or from Eclipse using JBoss tools. + +This topic is located in the `shared-docs/run-the-quickstart-in-jboss-developer-studio.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc +[source,options="nowrap"] +---- +//************************************************* +// Add {JBDSProductName} instructions +//************************************************* +// == Run the Quickstart in {JBDSProductName} or Eclipse + include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +---- + +Add additional instructions specific to running this quickstart in an IDE here. + +[[debug_the_application]] +== Debug the Application + +Add this section about how to debug the application source. + +This topic is located in the `shared-docs/debug-the-application.adoc` file. Include this file using the following syntax. + +.Example: include::../shared-doc/debug-the-application.adoc +[source,options="nowrap"] +---- +//************************************************* +// Add info to debug the application +//************************************************* +// == Debug the Application + include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +---- diff --git a/template/README.adoc b/template/README.adoc index 28e9ac4a38..702c823120 100644 --- a/template/README.adoc +++ b/template/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: template +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = How to Structure and Write a Quickstart README.adoc File diff --git a/template/pom.xml b/template/pom.xml index cbac69e957..53dcd32248 100644 --- a/template/pom.xml +++ b/template/pom.xml @@ -20,7 +20,7 @@ org.wildfly.quickstarts QUICKSTART_NAME - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: QUICKSTART_NAME - OPTIONAL_SUBFOLDER_NAME A short description of this quickstart diff --git a/thread-racing/README-source.adoc b/thread-racing/README-source.adoc new file mode 100644 index 0000000000..0c489d72f0 --- /dev/null +++ b/thread-racing/README-source.adoc @@ -0,0 +1,74 @@ +include::../shared-doc/attributes.adoc[] + += thread-racing: A Jakarta EE thread racing web application +:author: Eduardo Martins +:level: Beginner +:technologies: Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets +:openshift: true + +[abstract] +A thread racing web application that demonstrates technologies introduced or updated in the latest Jakarta EE specification. + +:standalone-server-type: full +:archiveType: war +:uses-h2: + +== What is it? + +The `thread-racing` quickstart is a web application that demonstrates new and updated technologies introduced by the {javaVersion} specification through simple use cases. + +The web application allows the user to trigger a race between 4 threads and follow, in real time, the progress of each thread until the race ends. + +The race itself consists of multiple stages, each demonstrating the usage of a specific new or updated {javaVersion} technology: + +* Batch 2.1 +* EE Concurrency 3.0 +* JAX-RS 3.1 +* JMS 3.1 +* JSON 2.1 + +WebSockets 2.1 is one of the most relevant new technologies introduced by {javaVersion}. Instead of being used in a race stage, a WebSockets 2.1 ServerEndpoint provides the remote application interface. +A new race is run when a client establishes a session. That session is then used to update the client in real time, with respect to the race progress and results. The `src/main/java/org/jboss/as/quickstarts/threadracing/WebSocketRace.java` file is the WebSocket server endpoint class and is a good entry point when studying how the application code works. + +JPA 3.1 is also present in the application code. Specifically it is used to store race results in the default data source instance, which is also new to Jakarta EE. Further details are included in the `src/main/java/org/jboss/as/quickstarts/threadracing/results/RaceResults.java` class. + + +//************************************************* +// Product Release content only +//************************************************* + +ifndef::EAPCDRelease[] + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// Considerations for Use in a Production Environment +include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the application + +The application will be running at the following URL http://localhost:8080/{artifactId}/. + +To start a race press the `Insert Coin` button. The page displays the names of the threads as they join the race. It then tracks the progress of each thread through the Batch, EE Concurrency, JAX-RS, JMS, and JSON stages of the race. Finally, it displays the official race results and championship standings. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/thread-racing/README.adoc b/thread-racing/README.adoc index 63c6f5c0e6..c5a3ef1d74 100644 --- a/thread-racing/README.adoc +++ b/thread-racing/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: thread-racing +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = thread-racing: A Jakarta EE thread racing web application :author: Eduardo Martins @@ -41,21 +238,326 @@ JPA 3.1 is also present in the application code. Specifically it is used to stor ifndef::EAPCDRelease[] // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // Considerations for Use in a Production Environment -include::../shared-doc/development-shortcuts.adoc[leveloffset=+1] +:leveloffset: +1 + +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment +//****************************************************************************** +// Include this template if your quickstart: +// * Uses the h2 database: Be sure to define the `uses-h2` attribute. +// * Uses an `*-ds.xml file`: Be sure to define the `uses-ds-xml` attribute. +// * Has performance or scalability concerns: Be sure to define the `uses-ds-xml` attribute. +//****************************************************************************** + +ifdef::uses-h2[] + +H2 Database:: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. + +endif::uses-h2[] + +ifdef::uses-ds-xml[] + +Datasource Configuration File:: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the {LinkConfigGuide}[__{ConfigBookName}__]. + +endif::uses-ds-xml[] + +ifdef::performance-scalability[] + +Performance and Scalability:: A Jakarta EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. + +endif::performance-scalability[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the application @@ -64,12 +566,625 @@ The application will be running at the following URL http://localhost:8080/{arti To start a race press the `Insert Coin` button. The page displays the names of the threads as they join the race. It then tracks the progress of each thread through the Batch, EE Concurrency, JAX-RS, JMS, and JSON stages of the race. Finally, it displays the official race results and championship standings. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + contextDir: thread-racing +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/thread-racing/charts/helm.yaml b/thread-racing/charts/helm.yaml index 4ed9f36167..e6f316b589 100644 --- a/thread-racing/charts/helm.yaml +++ b/thread-racing/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: thread-racing deploy: replicas: 1 \ No newline at end of file diff --git a/thread-racing/pom.xml b/thread-racing/pom.xml index 130a839575..3adc294884 100644 --- a/thread-racing/pom.xml +++ b/thread-racing/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 thread-racing - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: thread-racing A web application that triggers a thread race to complete Jakarta EE related tasks @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/todo-backend/README-source.adoc b/todo-backend/README-source.adoc new file mode 100644 index 0000000000..0684565431 --- /dev/null +++ b/todo-backend/README-source.adoc @@ -0,0 +1,294 @@ +include::../shared-doc/attributes.adoc[] + += todo-backend: quickstart for backend deployment on OpenShift +:toc: left +:icons: font +:idprefix: +:idseparator: - +:keywords: openshift,galleon,helm +:level: Intermediate +:technologies: JPA, JAX-RS, OpenShift, Galleon +:openshift: true +:archiveType: war +:useHelmChartDir: true +:helm-install-prerequisites: ../todo-backend/helm-install-prerequisites.adoc + +[abstract] +The `todo-backend` quickstart demonstrates how to implement a backend that exposes a HTTP API with JAX-RS +to manage a list of ToDo which are persisted in a database with JPA. + +ifndef::ProductRelease[] +This quickstart shows how to setup a local deployment of this backend as well as a deployment on OpenShift to connect +to a PostgreSQL database also hosted on OpenShift. +endif::[] +ifdef::ProductRelease[] +This quickstart shows how to deploy a {productName} application on OpenShift that connects +to a PostgreSQL database also hosted on OpenShift. +endif::[] + + +== What is it? + +The `todo-backend` quickstart demonstrates how to implement a backend that exposes a HTTP API with `JAX-RS` +to manage a list of ToDo which are persisted in a database with `JPA`. + +* The backend exposes a HTTP API to manage a list of todos that complies with the specs defined at https://todobackend.com/specs/index.html[todobackend.com]. +* It requires a connection to a PostgreSQL database to persist the todos. +ifndef::ProductRelease[] +* It uses the Server Provisioning for local and cloud deployment +endif::[] +* It can be build with {productName} S2I images for cloud deployment +ifndef::ProductRelease[] +* It is deployed on OpenShift using the https://docs.wildfly.org/wildfly-charts/[Helm Chart for {productName}]. +endif::[] +ifdef::ProductRelease[] +* It is deployed on OpenShift using the https://jbossas.github.io/eap-charts//[Helm Chart for {productName}]. +endif::[] + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] + +== Architecture + +=== Architecture with S2I + +This backend is built using {productName} S2I Builder and Runtime images. + +ifndef::ProductRelease[] +When the image is built, `org.wildfly.plugins:wildfly-maven-plugin` plugin provisions the {productName} application server and all the feature packs it needs for its features. +The layers are defined in the `pom.xml` file in the `` section of the `org.wildfly.plugins:wildfly-maven-plugin` plugin: + +[source,xml] +---- + + cloud-server + postgresql-datasource + +---- +endif::[] + +ifdef::ProductRelease[] +When the image is built, `org.jboss.eap.plugins:eap-maven-plugin` plugin provisions the {productName} application server and all the feature packs it needs for its features. +The layers are defined in the `pom.xml` file in the `` section of the `org.jboss.eap.plugins:eap-maven-plugin` plugin: + +[source,xml] +---- + + cloud-server + postgresql-datasource + +---- +endif::[] + +The `cloud-server` layer provides everything needed to run the backend on OpenShift. This also includes access to +Jakarta EE APIs such as CDI, JAX-RS, JPA, etc. These two layers comes from the {productName} feature pack provided in the +{productName} S2I builder image. + +ifndef::ProductRelease[] +The `postgresql-datasource` layer provides a JDBC driver and DataSource to connect to a PostgreSQL database. It is also provided by +`org.wildfly:wildfly-datasources-galleon-pack` which is included in the WildFly S2I image. + +The Git repository for this feature pack is hosted at https://github.com/wildfly-extras/wildfly-datasources-galleon-pack. +It provides JDBC drivers and datasources for different databases but for this quickstart, we will only need the `postgresql-datasource`. +endif::[] + +ifdef::ProductRelease[] +The `postgresql-datasource` layer provides a JDBC driver and DataSource to connect to a PostgreSQL database. It is also provided by +the `org.jboss.eap:eap-datasources-galleon-pack` feature pack. + +The Git repository for this feature pack is hosted at https://github.com/jbossas/eap-datasources-galleon-pack. +It provides JDBC drivers and datasources for different databases but for this quickstart, we will only need the `postgresql-datasource`. +endif::[] + +=== Connection to the PostgreSQL database + +ifndef::ProductRelease[] +As mentioned, the JDBC drivers and datasource configuration that the backend uses to connect to the PostgreSQL database +is provided by the `org.wildfly:wildfly-datasources-galleon-pack` feature pack. +endif::[] +ifdef::ProductRelease[] +As mentioned, the JDBC drivers and datasource configuration that the backend uses to connect to the PostgreSQL database +is provided by the `org.jboss.eap:eap-datasources-galleon-pack` feature pack. +endif::[] + +By default, it exposes a single datasource. +In the backend, the name of this datasource is `ToDos` and is specified in the `persistence.xml` to configure JPA: + +[source,xml] +---- + + java:jboss/datasources/ToDos + +---- + +At runtime, we only need a few environment variables to establish the connection from {productName} to the external PostgreSQL database: + +* `POSTGRESQL_DATABASE` - the name of the database (that will be called `todos`) +* `POSTGRESQL_SERVICE_HOST` - the host to connect to the database +* `POSTGRESQL_SERVICE_PORT` - The port to connect to the database +* `POSTGRESQL_USER` & `POSTGRESQL_PASSWORD` - the credentials to connect to the database +* `POSTGRESQL_DATASOURCE` - The name of the datasources (as mentioned above, it will be `ToDos`) + +=== Filters for Cross-Origin Resource Sharing (CORS) + +The Web frontend for this quickstart uses JavaScript calls to query the backend's HTTP API. +We must enable Cross-Origin Resource Sharing (CORS) filters in the `undertow` subsystem of {productName} to allow +these HTTP requests to succeed. + +ifdef::ProductRelease[] +==== Configuration with {productName} S2I + +As we use S2I to provision the server and build the application, we provide a CLI script that contains all the commands to create and configure the CORS filters in Undertow. This script is located in the `src/scripts/cors_filters.cli`. +endif::[] + +This script is executed at build time and will provide the following HTTP headers to enabled CORS: + +* `Access-Control-Allow-Origin: *` +* `Access-Control-Allow-Methods: GET, POST, OPTION, PUT, DELETE, PATCH` +* `Access-Control-Allow-Headers: accept, authorization, content-type, x-requested-with` +* `Access-Control-Allow-Credentials: true` +* `Access-Control-Max-Age: 1` + +By default, the backend accepts requests from any origin (`*`). This is only simplicity. It is possible to restrict +the allowed origin using the environment variable `CORS_ORIGIN` at runtime. + +ifndef::ProductRelease[] + +== Run the Backend Locally + +=== Package the Backend + +The backend is packaged and deployed on a provisioned server: + +[source,options="nowrap"] +---- +$ mvn clean package -Pprovisioned-server +---- + +=== Run a Local PostgreSQL Database + +Before running the backend locally, we need to have a local PostgreSQL database that we can connect to. +We use the `postgresql` docker image to create one: + +[source,options="nowrap"] +---- +$ docker run --name todo-backend-db -e POSTGRES_USER=todos -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 postgres +---- + +This will create a database named `todos` that we can connect to on `localhost:5432` with the credentials `todos / mysecretpassword`. + +=== Run the Application + +With the PostgreSQL database running, we can start the backend by passing the required environment variables to connect to the database: + +[source,options="nowrap"] +---- +$ ./target/server/bin/standalone.sh -Denv.POSTGRESQL_DATABASE=todos -Denv.POSTGRESQL_DATASOURCE=ToDos -Denv.POSTGRESQL_SERVICE_HOST=localhost -Denv.POSTGRESQL_SERVICE_PORT=5432 -Denv.POSTGRESQL_USER=todos -Denv.POSTGRESQL_PASSWORD=mysecretpassword +---- + +The backend is running, and we can use the HTTP API to manage a list of todos: + +[source,options="nowrap"] +---- +# get a list of todos +$ curl http://localhost:8080 +[] + +# create a todo with the title "This is my first todo item!" +$ curl -X POST -H "Content-Type: application/json" -d '{"title": "This is my first todo item!"}' http://localhost:8080 +{"completed":false,"id":1,"order":0,"title":"This is my first todo item!","url":"https://localhost:8080/1"}% + +# get a list of todos with the one that was just created +$ curl http://localhost:8080 +[{"completed":false,"id":1,"order":0,"title":"This is my first todo item!","url":"https://localhost:8080/1"}] +---- + +:extraStartParams: -DPOSTGRESQL_DATABASE=todos -DPOSTGRESQL_SERVICE_HOST=localhost -DPOSTGRESQL_SERVICE_PORT=5432 -DPOSTGRESQL_USER=todos -DPOSTGRESQL_PASSWORD=mysecretpassword -DPOSTGRESQL_DATASOURCE=ToDos +include::../shared-doc/run-integration-tests-with-provisioned-server.adoc[leveloffset=+1] + + +== Run the Backend on OpenShift + +// OpenShift +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] + +=== Environment variables for PostgreSQL + +The Helm Chart also contains the environment variables required to connect to the PostgreSQL database. + +ifndef::ProductRelease[] +In local deployment the credentials were passed directly as the values of the environment variables. +endif::[] + +For OpenShift, we rely on secrets so that the credentials are never copied outside OpenShift: + +[source,options="nowrap"] +---- +deploy: + env: + - name: POSTGRESQL_PASSWORD + valueFrom: + secretKeyRef: + key: database-password + name: todo-backend-db +---- + +When the application is deployed, the value for the `POSTGRESQL_PASSWORD` will be taken from the key `database-password` +in the secret `todo-backend-db`. + +// Testing on Openshift +include::../shared-doc/run-integration-tests-with-openshift.adoc[leveloffset=+1] + +=== Use the todobackend Web Frontend + +Once the backend is deployed on OpenShift, it can be accessed from the route `todo-backend`. +Let's find the host that we can use to connect to this backend: + +[source,options="nowrap"] +---- +$ oc get route todo-backend -o jsonpath="{.spec.host}" +todo-backend-jmesnil1-dev.apps.sandbox.x8i5.p1.openshiftapps.com +---- + +This value will be different for every installation of the backend. + +[WARNING] +==== +Make sure to prepend the host with `https://` to be able to connect to the backend from the ToDo Backend Specs or Client. +The host must also be publicly accessible. +==== + +We can verify that this application is properly working as a ToDo Backend by running its https://todobackend.com/specs/index.html[specs] on it. + + +Once all tests passed, we can use the https://todobackend.com/client/index.html[todobackend client] to have a Web application connected to the backend. + +[NOTE] +==== +https://todobackend.com/[todobackend.com] is an external service used to showcase this quickstart. +It might not always be functional but does not impact the availability of this backend. +==== + +=== Clean Up + +==== Remove the Backend + +The backend can be deleted from OpenShift by running the command: + +[source,options="nowrap"] +---- +$ helm uninstall todo-backend +release "todo-backend" uninstalled +---- + +== Conclusion + +This quickstart shows how the datasource feature pack provided by {productName} simplifies the deployment +of a {productName} Jakarta EE backend on OpenShift to connect to an external database and exposes an HTTP API. + +ifndef::ProductRelease[] +The use of a Server Provisioned deployment makes it seamless to move from a local deployment for development to a +deployment on OpenShift. +endif::[] \ No newline at end of file diff --git a/todo-backend/README.adoc b/todo-backend/README.adoc index ad5456cb9b..923d3c420a 100644 --- a/todo-backend/README.adoc +++ b/todo-backend/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: todo-backend +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = todo-backend: quickstart for backend deployment on OpenShift :toc: left @@ -47,15 +244,37 @@ ifdef::ProductRelease[] endif::[] // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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!: == Architecture === Architecture with S2I -This backend is built using {productName} S2I Builder and Runtime images. +This backend is built using {productName} S2I Builder and Runtime images. ifndef::ProductRelease[] When the image is built, `org.wildfly.plugins:wildfly-maven-plugin` plugin provisions the {productName} application server and all the feature packs it needs for its features. @@ -207,13 +426,523 @@ $ curl http://localhost:8080 ---- :extraStartParams: -DPOSTGRESQL_DATABASE=todos -DPOSTGRESQL_SERVICE_HOST=localhost -DPOSTGRESQL_SERVICE_PORT=5432 -DPOSTGRESQL_USER=todos -DPOSTGRESQL_PASSWORD=mysecretpassword -DPOSTGRESQL_DATASOURCE=ToDos -include::../shared-doc/run-integration-tests-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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!: == Run the Backend on OpenShift // OpenShift -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] +: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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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]] +:leveloffset: +1 + +ifndef::ProductRelease[] +Add the bitnami repository which provides an helm chart for PostgreSQL: +[source,options="nowrap"] +---- +$ helm repo add bitnami https://charts.bitnami.com/bitnami +"bitnami" has been added to your repositories +---- + +The Helm Chart for this quickstart contains all the information to build an image from the source code using S2I and install it with the database: + +[source,options="nowrap"] +---- +dependencies: + - name: postgresql + repository: https://charts.bitnami.com/bitnami + version: ... + - name: wildfly + repository: http://docs.wildfly.org/wildfly-charts/ + version: ... +---- + +So we need to update the dependecies of our Helm Chart. + +[source,options="nowrap",subs="+attributes"] +---- +$ helm dependency update charts/ +---- +endif::[] + +: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] +---- +apiVersion: v2 +name: todo-backend-chart +description: A Helm chart to deploy a WildFly todo-backend application and its Postgresql database +type: application +version: 1.0.0 +appVersion: 31.0.0.Final +dependencies: + - name: postgresql + repository: https://charts.bitnami.com/bitnami + version: 13.1.5 + - name: wildfly + repository: http://docs.wildfly.org/wildfly-charts/ + version: 2.3.2 +---- +endif::useHelmChartDir[] +ifndef::useHelmChartDir[] +[source,yaml] +---- +include::{docdir}/charts/helm.yaml[] +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: === Environment variables for PostgreSQL @@ -240,7 +969,42 @@ When the application is deployed, the value for the `POSTGRESQL_PASSWORD` will b in the secret `todo-backend-db`. // Testing on Openshift -include::../shared-doc/run-integration-tests-with-openshift.adoc[leveloffset=+1] +: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!: === Use the todobackend Web Frontend @@ -292,4 +1056,4 @@ of a {productName} Jakarta EE backend on OpenShift to connect to an external dat ifndef::ProductRelease[] The use of a Server Provisioned deployment makes it seamless to move from a local deployment for development to a deployment on OpenShift. -endif::[] \ No newline at end of file +endif::[] diff --git a/todo-backend/charts/values.yaml b/todo-backend/charts/values.yaml index c469db1371..61c45b430c 100644 --- a/todo-backend/charts/values.yaml +++ b/todo-backend/charts/values.yaml @@ -21,7 +21,7 @@ postgresql: wildfly: build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: todo-backend deploy: replicas: 1 diff --git a/todo-backend/pom.xml b/todo-backend/pom.xml index 0f7f2a4396..03ed1328fb 100644 --- a/todo-backend/pom.xml +++ b/todo-backend/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 todo-backend - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: todo-backend This project demonstrates how to implement a Todo-Backend application to manage ToDos @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/websocket-endpoint/README-source.adoc b/websocket-endpoint/README-source.adoc new file mode 100644 index 0000000000..d71e5d1f34 --- /dev/null +++ b/websocket-endpoint/README-source.adoc @@ -0,0 +1,59 @@ +include::../shared-doc/attributes.adoc[] + += websocket-endpoint: Web application using WebSockets and JSON-P +:author: Rafael Benevides +:level: Beginner +:technologies: CDI, WebSocket, JSON-P +:openshift: true + +[abstract] +Shows how to use WebSockets with JSON to broadcast information to all open WebSocket sessions in {productName}. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `websocket-endpoint` quickstart demonstrates how to use Java API for WebSockets to create server endpoints in {productNameFull}. + +The `BidWebSocketEndpoint` provides the WebSocket endpoint that receives `Message` instances from clients/browsers and replies with the current `Bidding` instance. The conversion from JSON content to the specific instances are made by `MessageDecoder` and `BiddingEncode` classes. + +Every update made on the `Bidding` are immediately propagated to all opened WebSocket sessions without any browser submission or AJAX polling mechanism. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +Access the running application in a browser at the following URL: http://localhost:8080/{artifactId}/. + +You are presented with a simple form that shows a bidding with the status `NOT_STARTED`. + +Click on `Do a bid!` button. That will start the bidding and trigger the 1 minute countdown timer. You can also notice that every Bid will be listed under the `List of bids` section. + +You should open the application URL in other browsers or tabs. You will notice that every change on the bidding is automatically update in all opened browser or tabs. The item will be SOLD once that it reaches the `Buy now price`. At the countdown timeout, the bidding will be EXPIRED. You can click on `Buy it now` button to immediately buy the item. + +You can restart the bidding if you click on `Reset bidding` button. + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/websocket-endpoint/README.adoc b/websocket-endpoint/README.adoc index 1b9622ef1f..4ad7ebc97b 100644 --- a/websocket-endpoint/README.adoc +++ b/websocket-endpoint/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: websocket-endpoint +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = websocket-endpoint: Web application using WebSockets and JSON-P :author: Rafael Benevides @@ -22,19 +219,295 @@ The `BidWebSocketEndpoint` provides the WebSocket endpoint that receives `Messag Every update made on the `Bidding` are immediately propagated to all opened WebSocket sessions without any browser submission or AJAX polling mechanism. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -49,12 +522,625 @@ You should open the application URL in other browsers or tabs. You will notice t You can restart the bidding if you click on `Reset bidding` button. // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file +[[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: 31.x + contextDir: websocket-endpoint +deploy: + replicas: 2 +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/websocket-endpoint/charts/helm.yaml b/websocket-endpoint/charts/helm.yaml index 98d316c0d0..2c62263662 100644 --- a/websocket-endpoint/charts/helm.yaml +++ b/websocket-endpoint/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: websocket-endpoint deploy: replicas: 2 \ No newline at end of file diff --git a/websocket-endpoint/pom.xml b/websocket-endpoint/pom.xml index dd354eff26..033530ef2a 100644 --- a/websocket-endpoint/pom.xml +++ b/websocket-endpoint/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 websocket-endpoint - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: websocket-endpoint This project demonstrates how to use a WebSocket Endppoint @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/websocket-hello/README-source.adoc b/websocket-hello/README-source.adoc new file mode 100644 index 0000000000..185033e45e --- /dev/null +++ b/websocket-hello/README-source.adoc @@ -0,0 +1,65 @@ +include::../shared-doc/attributes.adoc[] + += websocket-hello: A simple WebSocket application +:author: Sande Gilda, Emmanuel Hugonett +:level: Beginner +:technologies: WebSocket, CDI, JSF +:openshift: true + +[abstract] +The `websocket-hello` quickstart demonstrates how to create a simple WebSocket application. + +:standalone-server-type: default +:archiveType: war + +== What is it? + +The `websocket-hello` quickstart demonstrates how to create a simple WebSocket-enabled application in {productNameFull}. It consists of the following: + +* A JavaScript enabled WebSocket HTML client. +* A WebSocket server endpoint that uses annotations to interact with the WebSocket events. +* A `jboss-web.xml` file configured to enable WebSockets + +WebSockets are a requirement of the {javaVersion} specification and are implemented in {productName} {productVersion}. They are configured in the `undertow` subsystem of the server configuration file. This quickstart uses the WebSocket default settings, so it is not necessary to modify the server configuration to deploy and run this quickstart. + +NOTE: This quickstart demonstrates only a few of the basic functions. A fully functional application should provide better error handling and intercept and handle additional events. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +// 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 +include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +// Build and Deploy the Quickstart +include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] + +=== Access the Application + +The application will be running at the following URL: http://localhost:8080/{artifactId}/. + +. Click on the *Open Connection* button to create the WebSocket connection and display current status of `Open`. +. Type a name and click *Say Hello* to create and send the `Say hello to __NAME__` message. The message appears in the server log and a response is sent to the client. +. Click on the *Close Connection* button to close the WebSocket connection and display the current status of *Closed*. +. If you attempt to send another message after closing the connection, the following message appears on the page: ++ +[source,options="nowrap"] +---- +WebSocket connection is not established. Please click the Open Connection button. +---- + +// Server Distribution Testing +include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +// Undeploy the Quickstart +include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] + +// Build and run sections for other environments/builds +ifndef::ProductRelease,EAPXPRelease[] +include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +endif::[] +include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file diff --git a/websocket-hello/README.adoc b/websocket-hello/README.adoc index f64a5ea94c..3fab65f60a 100644 --- a/websocket-hello/README.adoc +++ b/websocket-hello/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: websocket-hello +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = websocket-hello: A simple WebSocket application :author: Sande Gilda, Emmanuel Hugonett @@ -26,19 +223,295 @@ WebSockets are a requirement of the {javaVersion} specification and are implemen NOTE: This quickstart demonstrates only a few of the basic functions. A fully functional application should provide better error handling and intercept and handle additional events. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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 -include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2] +: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 -include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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 +---- + +ifdef::rest-client-qs[] +This builds and deploys the `country-server` and `country-client` to the running instance of the server. + +You should see a message in the server log indicating that the archives deployed successfully. +endif::[] +ifndef::rest-client-qs[] +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. +endif::[] + + +:leveloffset!: === Access the Application @@ -55,12 +528,625 @@ WebSocket connection is not established. Please click the Open Connection button ---- // Server Distribution Testing -include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2] +:leveloffset: +2 + +[[run_the_integration_tests_with_server_distribution]] += Run the Integration Tests +This quickstart includes integration tests, which are located under the `src/test/` 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 you start the {productName} server, as previously described. + +. Make sure you build and deploy the quickstart, as previously described. + +. Type the following command to run the `verify` goal with the `integration-testing` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn verify -Pintegration-testing +---- + +[NOTE] +==== +You may also use the environment variable `SERVER_HOST` or the system property `server.host` to define the target URL of the tests. +==== + +:leveloffset!: // Undeploy the Quickstart -include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2] +: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 you xref:start_the_eap_standalone_server[start the {productName} server] as described above. +. 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[] -include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1] +: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: ] + +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} +---- + +. 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::[] + +ifndef::ProductRelease,EAPXPRelease[] +[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::[] -include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1] \ No newline at end of file + +ifdef::ProductRelease,EAPXPRelease[] +[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::[] + +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 it uses the cloud feature pack which enables a configuration tuned for OpenShift environment. +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: 31.x + contextDir: websocket-hello +deploy: + replicas: 2 +---- +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[] + + +[[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 + +// 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 + +:leveloffset!: diff --git a/websocket-hello/charts/helm.yaml b/websocket-hello/charts/helm.yaml index f15b8656c7..473b08717d 100644 --- a/websocket-hello/charts/helm.yaml +++ b/websocket-hello/charts/helm.yaml @@ -1,6 +1,6 @@ build: uri: https://github.com/wildfly/quickstart.git - ref: main + ref: 31.x contextDir: websocket-hello deploy: replicas: 2 \ No newline at end of file diff --git a/websocket-hello/pom.xml b/websocket-hello/pom.xml index b11f61e5fd..ef43301042 100644 --- a/websocket-hello/pom.xml +++ b/websocket-hello/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 websocket-hello - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: websocket-hello This project demonstrates a simple Hello WebSocket application @@ -45,7 +45,7 @@ - 31.0.0.Beta1 + 31.0.0.Final ${version.server} 5.0.0.Beta2 diff --git a/wsat-simple/README-source.adoc b/wsat-simple/README-source.adoc new file mode 100644 index 0000000000..95e7d8c79c --- /dev/null +++ b/wsat-simple/README-source.adoc @@ -0,0 +1,260 @@ +include::../shared-doc/attributes.adoc[] + += wsat-simple: WS-AT (WS-AtomicTransaction) - Simple +:author: Paul Robinson +:level: Intermediate +:technologies: WS-AT, JAX-WS + +[abstract] +The `wsat-simple` quickstart demonstrates a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service, bundled as a WAR, and deployed to {productName}. + +:standalone-server-type: custom +:archiveType: war +:restoreScriptName: restore-configuration.cli + +== What is it? + +The `wsat-simple` quickstart demonstrates the deployment of a WS-AT (WS-AtomicTransaction) enabled JAX-WS Web service bundled in a WAR archive for deployment to {productNameFull}. + +The Web service is offered by a Restaurant for making bookings. The Service allows bookings to be made within an Atomic Transaction. + +This example demonstrates the basics of implementing a WS-AT enabled Web service. It is beyond the scope of this quick start to demonstrate more advanced features. In particular: + +* The Service does not implement the required hooks to support recovery in the presence of failures. +* It also does not utilize a transactional back-end resource. +* Only one web service participates in the protocol. As WS-AT is a 2PC coordination protocol, it is best suited to multi-participant scenarios. + +For a more complete example, please see the XTS demonstrator application that ships with the Narayana project: http://narayana.io/. + +It is also assumed that you have an understanding of WS-AtomicTransaction. For more details, read the XTS documentation that ships with the Narayana project: http://narayana.io/docs/product. + +The application consists of a single JAX-WS web service that is deployed within a WAR archive. It is tested with a JBoss Arquillian enabled JUnit test. + +When running the `org.jboss.as.quickstarts.wsat.simple.ClientTest#testCommit()` method, the following steps occur: + +. A new Atomic Transaction (AT) is created by the client. +. An operation on a WS-AT enabled Web service is invoked by the client. +. The JaxWSHeaderContextProcessor in the WS Client handler chain inserts the WS-AT context into the outgoing SOAP message +. When the service receives the SOAP request, the JaxWSHeaderContextProcessor in its handler chain inspects the WS-AT context and associates the request with this AT. +. The Web service operation is invoked… +. A participant is enlisted in this AT. This allows the Web Service logic to respond to protocol events, such as Commit and Rollback. +. The service invokes the business logic. In this case, a booking is made with the restaurant. +. The backend resource is prepared. This ensures that the Backend resource can undo or make permanent the change when told to do so by the coordinator. +. The client can then decide to commit or rollback the AT. If the client decides to commit, the coordinator will begin the 2PC protocol. If the participant decides to rollback, all participants will be told to rollback. + +There is another test that shows what happens if the client decides to rollback the AT. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +[[start_the_eap_standalone_server]] +== Start the {productName} Standalone Server + +You must start {productName} with the XTS subsystem enabled. + +. Edit the log level to reduce the amount of log output. This should make it easier to read the logs produced by this example. To do this add the following logger block to the `__{jbossHomeName}__/standalone/configuration/standalone.xml` of your JBoss distribution. You should add it just below one of the other logger blocks. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +[[configure_the_server]] +=== Configure the Server + +You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. ++ +NOTE: Remember you will need to run the restore-configuration.cli script to restore the server original configuration. + + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* Start the {productName} server with the standalone profile : ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh +---- + +. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds xts domain +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following subsystem was added. ++ +[source,xml,options="nowrap"] +---- + + + + + +---- + +. The following `extension` was added. ++ +[source,xml,options="nowrap"] +---- + +---- ++ + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} server with XTS subsystem enabled by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + +// Run the Arquillian Tests +include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] + +[[investigate_the_console_output]] +== Investigate the Console Output + +When you run the Arquillian tests, Maven prints summary of the performed tests to the console. You should see the following results. + +[source,options="nowrap"] +---- +Results : + +Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +---- + +[NOTE] +==== +You see the following warning when you run the Arquillian tests in remote mode. + +[source,options="nowrap"] +---- +WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-4) WFLYSRV0221: Deployment "deployment.wsat-simple.war" is using a deprecated module ("org.jboss.xts") which may be removed in future versions without notice. +---- + +This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the `serverConfig` property defined in the `arquillian.xml` file to start the server with the XTS subsystem enabled (default is standalone.xml). +==== + +[[investigate_the_server_log]] +== Investigate the Server Log + +The following messages should appear in the server log. The messages trace the steps taken by the tests. Note there may be other informational log messages interlaced between these. + +Test rollback: + +[source,options="nowrap"] +---- +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) Starting 'testRollback'. This test invokes a WS within an AT. The AT is later rolled back, which causes the back-end resource(s) to be rolled back. +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] Creating a new WS-AT User Transaction +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] Beginning Atomic Transaction (All calls to Web services that support WS-AT wil be included in this transaction) +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] invoking makeBooking() on WS +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] Restaurant service invoked to make a booking +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] Enlisting a Durable2PC participant into the AT +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] Invoking the back-end business logic +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-25) [SERVICE] makeBooking called on backend resource. +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-4) [CLIENT] rolling back Atomic Transaction (This will cause the AT and thus the enlisted back-end resources to rollback) +INFO [stdout] (TaskWorker-2) [SERVICE] one or more participants voted 'aborted' or a failure occurred, so coordinator tells the participant to rollback +INFO [stdout] (TaskWorker-2) [SERVICE] rollback called on backend resource. +---- + +Test commit: + +[source,options="nowrap"] +---- +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) Starting 'testCommit'. This test invokes a WS within an AT. The AT is later committed, which causes the back-end resource(s) to be committed. +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] Creating a new WS-AT User Transaction +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] Beginning Atomic Transaction (All calls to Web services that support WS-AT wil be included in this transaction) +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] invoking makeBooking() on WS +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] Restaurant service invoked to make a booking +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] Enlisting a Durable2PC participant into the AT +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] Invoking the back-end business logic +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-66) [SERVICE] makeBooking called on backend resource. +INFO [stdout] (http-localhost.localdomain/127.0.0.1:8080-54) [CLIENT] committing Atomic Transaction (This will cause the AT to complete successfully) +INFO [stdout] (TaskWorker-2) [SERVICE] Prepare called on participant, about to prepare the back-end resource +INFO [stdout] (TaskWorker-2) [SERVICE] prepare called on backend resource. +INFO [stdout] (TaskWorker-2) [SERVICE] back-end resource prepared, participant votes prepared +WARN [com.arjuna.wst] (TaskWorker-2) ARJUNA043219: Could not save recovery state for non-serializable durable WS-AT participant restaurantServiceAT:ba222c73-00c3-4ecc-921c-80fd5dfdc11a +INFO [stdout] (TaskWorker-2) [SERVICE] all participants voted 'prepared', so coordinator tells the participant to commit +INFO [stdout] (TaskWorker-2) [SERVICE] commit called on backend resource. +---- + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +This quickstart is more complex than the others. It requires that you configure the {productName} server using the configure-server.cli file. + +. Import the quickstart into {JBDSProductName}. ++ +[NOTE] +==== +When you import this quickstart into {JBDSProductName}, you will see the following warning. +[source] +---- +WS-I: A problem occured while running the WS-I WSDL conformance check: org.eclipse.wst.wsi.internal.analyzer.WSIAnalyzerException: The WS-I Test Assertion Document (TAD)document was either not found or could not be processed.The WSDLAnalyzer was unable to validate the given WSDL File. +---- +This is a known Eclipse issue. For more information, see Eclipse Bugzilla - https://bugs.eclipse.org/bugs/show_bug.cgi?id=535813[Bug 535813]. +==== + +. If you have not already done so, you must configure a new {productName} server to use the XTS configuration. +** In the *Servers* tab, right-click and choose *New* -> *Server*. +** Under *Select the server type:*, expand *Red Hat JBoss Middleware* and choose *{jbdsEapServerName}*. +** For the *Server name*, enter `{productName} XTS Configuration` and click `Next`. +** In the *Create a new Server Adapter* dialog, choose *Create a new runtime (next page)* from the drop-down menu and click *Next*. +** In the *JBoss Runtime* dialog, enter the following information and then click *Finish*. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +*Name*: `{productName} XTS Runtime` +*Home Directory*: __Browse to the __{jbossHomeName}__ directory and select it.__ +*Runtime JRE*: __Choose an alternate JRE if not correct.__ +*Server base directory*: __This should already point to your standalone server configuration directory,__ +*Configuration file*: `standalone.xml` +---- + +. Start the new *{productName} XTS Configuration* server. +. Right-click on the *{artifactId}* project, choose *Run As* -> *Maven build*, enter `clean verify -Parq-remote` for the *Goals*, and click *Run* to run the Arquillian tests. The test results appear in the console. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/wsat-simple/README.adoc b/wsat-simple/README.adoc index 95e7d8c79c..6ecfe1c195 100644 --- a/wsat-simple/README.adoc +++ b/wsat-simple/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: wsat-simple +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = wsat-simple: WS-AT (WS-AtomicTransaction) - Simple :author: Paul Robinson @@ -45,11 +242,66 @@ When running the `org.jboss.as.quickstarts.wsat.simple.ClientTest#testCommit()` There is another test that shows what happens if the client decides to rollback the AT. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: [[start_the_eap_standalone_server]] == Start the {productName} Standalone Server @@ -76,7 +328,7 @@ NOTE: Remember you will need to run the restore-configuration.cli script to rest . Before you begin, make sure you do the following: * xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. -* Start the {productName} server with the standalone profile : +* Start the {productName} server with the standalone profile : + [source,subs="+quotes,attributes+",options="nowrap"] ---- @@ -137,7 +389,58 @@ $ __{jbossHomeName}__/bin/standalone.sh NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. // Run the Arquillian Tests -include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_arquillian_tests]] += Run the Arquillian Tests +//****************************************************************************** +// Include this template if your quickstart provides standard Arquillian tests. +//****************************************************************************** + +This quickstart provides Arquillian tests. By default, these tests are configured to be skipped since Arquillian tests require the use of a container. + +NOTE: The Arquillian tests deploy the application, so make sure you undeploy the quickstart before you begin. + +ifdef::arq-prerequisities[] +== Arquillian Tests prerequisities + +{arq-prerequisities} +endif::[] + +Follow these steps to run the tests. + +ifdef::standalone-server-type[] +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +endif::[] + +ifdef::managed-domain-type[] +. xref:start_the_eap_managed_domain[Start the {productName} server] as described above. +endif::[] + +. Open a terminal and navigate to the root directory of this quickstart. +. Type the following command to run the `verify` goal with the `arq-remote` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn clean verify -Parq-remote +---- +ifdef::arquillianTestResults[] +You should see the following results: ++ +[source,subs=attributes+,options="nowrap"] +---- +Results : + +{arquillianTestResults} +---- +endif::[] + +[NOTE] +==== +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile, meaning the tests will start the server for you. This profile requires that you provide Arquillian with the location of the {productName} server, either by setting the `JBOSS_HOME` environment variable, or by setting the `jbossHome` property in the `arquillian.xml` file. For more information, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. +==== + +:leveloffset!: [[investigate_the_console_output]] == Investigate the Console Output @@ -207,10 +510,63 @@ INFO [stdout] (TaskWorker-2) [SERVICE] commit called on backend resource. ---- // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions This quickstart is more complex than the others. It requires that you configure the {productName} server using the configure-server.cli file. @@ -247,7 +603,33 @@ This is a known Eclipse issue. For more information, see Eclipse Bugzilla - http . Right-click on the *{artifactId}* project, choose *Run As* -> *Maven build*, enter `clean verify -Parq-remote` for the *Goals*, and click *Run* to run the Arquillian tests. The test results appear in the console. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -257,4 +639,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/wsat-simple/pom.xml b/wsat-simple/pom.xml index 4062ff7d0e..1936c9c674 100644 --- a/wsat-simple/pom.xml +++ b/wsat-simple/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 wsat-simple - 31.0.0.Final-SNAPSHOT + 31.0.0.Final war Quickstart: wsat-simple This project demonstrates a WS-AT enabled JAX-WS Web service bundled in a WAR archive diff --git a/wsba-coordinator-completion-simple/README-source.adoc b/wsba-coordinator-completion-simple/README-source.adoc new file mode 100644 index 0000000000..1448e6d5e0 --- /dev/null +++ b/wsba-coordinator-completion-simple/README-source.adoc @@ -0,0 +1,254 @@ +include::../shared-doc/attributes.adoc[] + += wsba-coordinator-completion-simple: Example of a WS-BA Enabled JAX-WS Web Service +:author: Paul Robinson +:level: Intermediate +:technologies: WS-BA, JAX-WS + +[abstract] +The `wsba-coordinator-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (CoordinatorCompletion protocol). + +:standalone-server-type: custom +:archiveType: war +:restoreScriptName: restore-configuration.cli + +== What is it? + +The `wsba-coordinator-completion-simple` quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (Participant Completion protocol) for deployment to {productNameFull}. + +The Web service exposes a simple `set` collection as a service. The Service allows items to be added to the set within a Business Activity. + +This example demonstrates the basics of implementing a WS-BA enabled Web service. It is beyond the scope of this quick start to demonstrate more advanced features. In particular: + +* The Service does not implement the required hooks to support recovery in the presence of failures. +* It also does not utilize a transactional back-end resource. +* Only one web service participates in the protocol. As WS-BA is a coordination protocol, it is best suited to multi-participant scenarios. + +For a more complete example, please see the XTS demonstrator application that ships with the Narayana project: http://narayana.io. + +It is also assumed that you have an understanding of WS-BusinessActivity. For more details, read the XTS documentation that ships with the Narayana project: http://narayana.io/docs/product + +The application consists of a single JAX-WS web service that is deployed within a WAR archive. It is tested with a JBoss Arquillian enabled JUnit test. + +When running the `org.jboss.as.quickstarts.wsba.coordinatorcompletion.simple.ClientTest#testSuccess()` method, the following steps occur: + +. A new Business Activity is created by the client. +. Multiple operations on a WS-BA enabled Web service is invoked by the client. +. The `JaxWSHeaderContextProcessor` in the WS Client handler chain inserts the BA context into the outgoing SOAP messages. +. When the service receives a SOAP request, the `JaxWSHeaderContextProcessor` in its handler chain inspects the BA context and associates the request with this BA. +. The Web service operation is invoked. +. For the first request, in this BA, A participant is enlisted in this BA. This allows the Web Service logic to respond to protocol events, such as compensate and close. +. The service invokes the business logic. In this case, a String value is added to the set. +. The client can then make additional calls to the `SetService`. As the `SetService` participates as a `CoordinatorCompletion` protocol, it will continue to accept calls to `addValueToSet` until it is told to complete by the coordinator. +. The client can then decide to complete or cancel the BA. +** If the client decides to complete, all participants will be told to complete. Providing all participants successfully complete, the coordinator will then tell all participants to close, otherwise the completed participants will be told to compensate. +** If the participant decides to cancel, all participants will be told to compensate. + +There is another test that shows how the client can cancel a BA. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +[[start_the_eap_standalone_server]] +== Start the {productName} Standalone Server + +You must start {productName} with the XTS subsystem enabled. + +. Edit the log level to reduce the amount of log output. This should make it easier to read the logs produced by this example. To do this add the following logger block to the `__{jbossHomeName}__/standalone/configuration/standalone.xml` of your JBoss distribution. You should add it just below one of the other logger blocks. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +[[configure_the_server]] +=== Configure the Server + +You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* Start the {productName} server with the standalone default profile : ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh +---- + +. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds xts domain +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following subsystem was added. ++ +[source,xml,options="nowrap"] +---- + + + + + +---- + +. The following `extension` was added. ++ +[source,xml,options="nowrap"] +---- + +---- ++ + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} server with XTS subsystem enabled by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + +// Run the Arquillian Tests +include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] + +[[investigate_the_console_output]] +== Investigate the Console Output + +When you run the Arquillian tests, Maven prints summary of the performed tests to the console. You should see the following results. + +[source,options="nowrap"] +---- +Results : + +Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +---- + +[NOTE] +==== +You see the following warning when you run the Arquillian tests in remote mode. + +[source,options="nowrap"] +---- +WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-4) WFLYSRV0221: Deployment "deployment.wsat-simple.war" is using a deprecated module ("org.jboss.xts") which may be removed in future versions without notice. +---- + +This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the `serverConfig` property defined in the `arquillian.xml` file to start the server with the XTS subsystem enabled (default is standalone.xml). +==== + +== Investigate the Server Log + +The following messages should appear in the server log. Note there may be other log messages interlaced between these. The messages trace the steps taken by the tests. + +Test success: + +[source,options="nowrap"] +---- +INFO [stdout] (management-handler-threads - 10) Starting 'testSuccess'. This test invokes a WS twice within a BA. The BA is later closes, which causes these WS calls to complete successfully. +INFO [stdout] (management-handler-threads - 10) [CLIENT] Creating a new Business Activity +INFO [stdout] (management-handler-threads - 10) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA wil be included in this activity) +INFO [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(1) on WS +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('1') +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Enlisting a participant into the BA +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic +INFO [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(2) on WS +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('2') +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Re-using the existing participant, already registered for this BA +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic +INFO [stdout] (management-handler-threads - 10) [CLIENT] Closing Business Activity (This will cause the BA to complete successfully) +INFO [stdout] (TaskWorker-3) [SERVICE] Participant.complete (This tells the participant that the BA completed, but may be compensated later) +INFO [stdout] (TaskWorker-3) [SERVICE] Participant.confirmCompleted('true') (This tells the participant that compensation information has been logged and that it is safe to commit any changes.) +INFO [stdout] (TaskWorker-3) [SERVICE] Commit the backend resource (e.g. commit any changes to databases so that they are visible to others) +INFO [stdout] (TaskWorker-1) [SERVICE] Participant.close (The participant knows that this BA is now finished and can throw away any temporary state) +---- + +Test cancel: + +[source,options="nowrap"] +---- +INFO [stdout] (management-handler-threads - 10) Starting 'testCancel'. This test invokes a WS twice within a BA. The BA is later cancelled, which causes these WS calls to be compensated. +INFO [stdout] (management-handler-threads - 10) [CLIENT] Creating a new Business Activity +INFO [stdout] (management-handler-threads - 10) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA will be included in this activity) +INFO [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(1) on WS +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('1') +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Enlisting a participant into the BA +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic +INFO [stdout] (management-handler-threads - 10) [CLIENT] invoking addValueToSet(2) on WS +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] invoked addValueToSet('2') +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Re-using the existing participant, already registered for this BA +INFO [stdout] (http-localhost-127.0.0.1-8080-2) [SERVICE] Invoking the back-end business logic +INFO [stdout] (management-handler-threads - 10) [CLIENT] Cancelling Business Activity (This will cause the work to be compensated) +INFO [stdout] (TaskWorker-3) [SERVICE] Participant.cancel (The participant should compensate any work done within this BA) +INFO [stdout] (TaskWorker-3) [SERVICE] SetParticipantBA: Carrying out compensation action +INFO [stdout] (TaskWorker-3) [SERVICE] Compensate the backend resource by removing '1' from the set (e.g. undo any changes to databases that were previously made visible to others) +INFO [stdout] (TaskWorker-3) [SERVICE] Compensate the backend resource by removing '2' from the set (e.g. undo any changes to databases that were previously made visible to others) +---- + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +This quickstart is more complex than the others. It requires that you configure the {productName} server using the configure-server.cli file. + +. Make sure you import the quickstart into {JBDSProductName}. +. If you have not already done so, you must configure a new {productName} server to use the XTS configuration. + +** In the *Servers* tab, right-click and choose *New* -> *Server*. +** Under *Select the server type:*, expand *Red Hat JBoss Middleware* and choose *{jbdsEapServerName}*. +** For the *Server name*, enter `{productName} XTS Configuration` and click `Next`. +** In the *Create a new Server Adapter* dialog, choose *Create a new runtime (next page)* from the drop-down menu and click *Next*. +** In the *JBoss Runtime* dialog, enter the following information and then click *Finish*. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +*Name*: `{productName} XTS Runtime` +*Home Directory*: __Browse to the _{jbossHomeName}__ directory and select it.__ +*Runtime JRE*: __Choose an alternate JRE if not correct.__ +*Server base directory*: __This should already point to your standalone server configuration directory,__ +*Configuration file*: `standalone.xml` +---- + +. Start the new *{productName} XTS Configuration* server. +. Right-click on the *{artifactId}* project, choose *Run As* -> *Maven build*, enter `clean verify -Parq-remote` for the *Goals*, and click *Run* to run the Arquillian tests. The test results appear in the console. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/wsba-coordinator-completion-simple/README.adoc b/wsba-coordinator-completion-simple/README.adoc index 1448e6d5e0..60faaeb41f 100644 --- a/wsba-coordinator-completion-simple/README.adoc +++ b/wsba-coordinator-completion-simple/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: wsba-coordinator-completion-simple +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = wsba-coordinator-completion-simple: Example of a WS-BA Enabled JAX-WS Web Service :author: Paul Robinson @@ -47,11 +244,66 @@ When running the `org.jboss.as.quickstarts.wsba.coordinatorcompletion.simple.Cli There is another test that shows how the client can cancel a BA. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: [[start_the_eap_standalone_server]] == Start the {productName} Standalone Server @@ -75,7 +327,7 @@ You can configure the server by running JBoss CLI commands. For your convenience . Before you begin, make sure you do the following: * xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. -* Start the {productName} server with the standalone default profile : +* Start the {productName} server with the standalone default profile : + [source,subs="+quotes,attributes+",options="nowrap"] ---- @@ -136,7 +388,58 @@ $ __{jbossHomeName}__/bin/standalone.sh NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. // Run the Arquillian Tests -include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_arquillian_tests]] += Run the Arquillian Tests +//****************************************************************************** +// Include this template if your quickstart provides standard Arquillian tests. +//****************************************************************************** + +This quickstart provides Arquillian tests. By default, these tests are configured to be skipped since Arquillian tests require the use of a container. + +NOTE: The Arquillian tests deploy the application, so make sure you undeploy the quickstart before you begin. + +ifdef::arq-prerequisities[] +== Arquillian Tests prerequisities + +{arq-prerequisities} +endif::[] + +Follow these steps to run the tests. + +ifdef::standalone-server-type[] +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +endif::[] + +ifdef::managed-domain-type[] +. xref:start_the_eap_managed_domain[Start the {productName} server] as described above. +endif::[] + +. Open a terminal and navigate to the root directory of this quickstart. +. Type the following command to run the `verify` goal with the `arq-remote` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn clean verify -Parq-remote +---- +ifdef::arquillianTestResults[] +You should see the following results: ++ +[source,subs=attributes+,options="nowrap"] +---- +Results : + +{arquillianTestResults} +---- +endif::[] + +[NOTE] +==== +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile, meaning the tests will start the server for you. This profile requires that you provide Arquillian with the location of the {productName} server, either by setting the `JBOSS_HOME` environment variable, or by setting the `jbossHome` property in the `arquillian.xml` file. For more information, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. +==== + +:leveloffset!: [[investigate_the_console_output]] == Investigate the Console Output @@ -211,10 +514,63 @@ INFO [stdout] (TaskWorker-3) [SERVICE] Compensate the backend resource by remov ---- // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions This quickstart is more complex than the others. It requires that you configure the {productName} server using the configure-server.cli file. @@ -241,7 +597,33 @@ This quickstart is more complex than the others. It requires that you configure . Right-click on the *{artifactId}* project, choose *Run As* -> *Maven build*, enter `clean verify -Parq-remote` for the *Goals*, and click *Run* to run the Arquillian tests. The test results appear in the console. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -251,4 +633,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/wsba-coordinator-completion-simple/pom.xml b/wsba-coordinator-completion-simple/pom.xml index 4df5887110..a7f42ce127 100644 --- a/wsba-coordinator-completion-simple/pom.xml +++ b/wsba-coordinator-completion-simple/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 wsba-coordinator-completion-simple - 31.0.0.Final-SNAPSHOT + 31.0.0.Final jar Quickstart: wsba-coordinator-completion-simple This project demonstrates WS-BA with Coordinator Driven Completion diff --git a/wsba-participant-completion-simple/README-source.adoc b/wsba-participant-completion-simple/README-source.adoc new file mode 100644 index 0000000000..f5d921b906 --- /dev/null +++ b/wsba-participant-completion-simple/README-source.adoc @@ -0,0 +1,249 @@ +include::../shared-doc/attributes.adoc[] + += wsba-participant-completion-simple: Deployment of a WS-BA enabled JAX-WS Web Service +:author: Paul Robinson +:level: Intermediate +:technologies: WS-BA, JAX-WS + +[abstract] +The `wsba-participant-completion-simple` quickstart deploys a WS-BA (WS Business Activity) enabled JAX-WS Web service WAR (ParticipantCompletion Protocol). + +:standalone-server-type: custom +:archiveType: war +:restoreScriptName: restore-configuration.cli + +== What is it? + +The `wsba-participant-completion-simple` quickstart demonstrates the deployment of a WS-BA (WS Business Activity) enabled JAX-WS Web service bundled in a WAR archive (ParticipantCompletion Protocol) for deployment to {productNameFull}. + +The Web service exposes a simple 'set' collection as a service. The Service allows items to be added to the set within a Business Activity. + +The example demonstrates the basics of implementing a WS-BA enabled Web service. It is beyond the scope of this quickstart to demonstrate more advanced features. In particular + +* The Service does not implement the required hooks to support recovery in the presence of failures. +* It also does not utilize a transactional back-end resource. +* Only one web service participates in the protocol. As WS-BA is a coordination protocol, it is best suited to multi-participant scenarios. + +For a more complete example, please see the XTS demonstrator application that ships with the Narayana project: http://narayana.io. + +It is also assumed tht you have an understanding of WS-BusinessActivity. For more details, read the XTS documentation +that ships with the Narayana project: http://narayana.io/docs/product + +The application consists of a single JAX-WS web service that is deployed within a WAR archive. It is tested with a JBoss +Arquillian enabled JUnit test. + +When running the org.jboss.as.quickstarts.wsba.participantcompletion.simple.ClientTest#testSuccess() method, the +following steps occur: + +. A new Business Activity is created by the client. +. An operation on a WS-BA enabled Web service is invoked by the client. +. The `JaxWSHeaderContextProcessor` in the WS Client handler chain inserts the BA context into the outgoing SOAP message. +. When the service receives the SOAP request, the `JaxWSHeaderContextProcessor` in its handler chain inspects the BA context and associates the request with this BA. +. The Web service operation is invoked. +. A participant is enlisted in this BA. This allows the Web Service logic to respond to protocol events, such as compensate and close. +. The service invokes the business logic. In this case, a String value is added to the set. +. The backend resource is prepared. This ensures that the Backend resource can undo or make permanent the change when told to do so by the coordinator. +. Providing the above steps where successful, the service notifies the coordinator that it has completed. The service has now made its changes visible and is not holding any locks. Allowing the service to notify completion is an optimisation that prevents the holding of locks, whilst waiting for other participants to complete. This notification is required as the Service participates in the `ParticipantCompletion` protocol. +. The client can then decide to complete or cancel the BA. If the client decides to complete, all participants will be told to close. If the participant decides to cancel, all participants will be told to compensate. + +There are additional tests that show: + +* What happens when an application exception is thrown by the service. +* How the client can cancel a BA. + +// Link to the quickstart source +include::../shared-doc/view-the-source.adoc[leveloffset=+1] +// System Requirements +include::../shared-doc/system-requirements.adoc[leveloffset=+1] +// Use of {jbossHomeName} +include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] + +[[start_the_eap_standalone_server]] +== Start the {productName} Standalone Server + +You must start {productName} with the XTS subsystem enabled. + +. Edit the log level to reduce the amount of log output. This should make it easier to read the logs produced by this example. To do this add the following logger block to the `__{jbossHomeName}__/standalone/configuration/standalone.xml` of your JBoss distribution. You should add it just below one of the other logger blocks. ++ +[source,xml,options="nowrap"] +---- + + + +---- + +[[configure_the_server]] +=== Configure the Server + +You can configure the server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-server.cli` script provided in the root directory of this quickstart. + +. Before you begin, make sure you do the following: + +* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. +* Start the {productName} server with the standalone default profile : ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh +---- + +. Review the `configure-server.cli` file in the root of this quickstart directory. This script adds xts domain +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +You should see the following result when you run the script: ++ +[source,options="nowrap"] +---- +The batch executed successfully +---- + +. Stop the {productName} server. + +=== Review the Modified Server Configuration + +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. + +. The following subsystem was added. ++ +[source,xml,options="nowrap"] +---- + + + + + +---- + +. The following `extension` was added. ++ +[source,xml,options="nowrap"] +---- + +---- ++ + +. Open a terminal and navigate to the root of the {productName} directory. +. Start the {productName} server with XTS subsystem enabled by typing the following command. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/standalone.sh +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + +// Run the Arquillian Tests +include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] + +[[investigate_the_console_output]] +== Investigate the Console Output + +When you run the Arquillian tests, Maven prints summary of the performed tests to the console. You should see the following results. + +[source,options="nowrap"] +---- +Results : + +Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +---- + +[NOTE] +==== +You see the following warning when you run the Arquillian tests in remote mode. + +[source,options="nowrap"] +---- +WARN [org.jboss.as.dependency.deprecated] (MSC service thread 1-4) WFLYSRV0221: Deployment "deployment.wsat-simple.war" is using a deprecated module ("org.jboss.xts") which may be removed in future versions without notice. +---- + +This is because, in remote mode, you are responsible for starting the server with the XTS subsystem enabled. When you run the Arquillian tests in managed mode, the container uses the `serverConfig` property defined in the `arquillian.xml` file to start the server with the XTS subsystem enabled (default is standalone.xml). +==== + +== Investigate the Server Log + +The following messages should appear in the server log. Note there may be other log messages interlaced between these. The messages trace the steps taken by the tests. + +Test success: + +[source,options="nowrap"] +---- +INFO [stdout] (management-handler-threads - 6) Starting 'testSuccess'. This test invokes a WS within a BA. The BA is later closed, which causes the WS call to complete successfully. +INFO [stdout] (management-handler-threads - 6) [CLIENT] Creating a new Business Activity +INFO [stdout] (management-handler-threads - 6) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA wil be included in this activity) +INFO [stdout] (management-handler-threads - 6) [CLIENT] invoking addValueToSet(1) on WS +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] invoked addValueToSet('1') +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Enlisting a participant into the BA +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Invoking the back-end business logic +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare the backend resource and if successful notify the coordinator that we have completed our work +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare successful, notifying coordinator of completion +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Participant.confirmCompleted('true') (This tells the participant that compensation information has been logged and that it is safe to commit any changes.) +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Commit the backend resource (e.g. commit any changes to databases so that they are visible to others) +INFO [stdout] (management-handler-threads - 6) [CLIENT] Closing Business Activity (This will cause the BA to complete successfully) +INFO [stdout] (TaskWorker-2) [SERVICE] Participant.close (The participant knows that this BA is now finished and can throw away any temporary state) +---- + +Test cancel: + +[source,options="nowrap"] +---- +INFO [stdout] (management-handler-threads - 5) Starting 'testCancel'. This test invokes a WS within a BA. The BA is later cancelled, which causes these WS call to be compensated. +INFO [stdout] (management-handler-threads - 5) [CLIENT] Creating a new Business Activity +INFO [stdout] (management-handler-threads - 5) [CLIENT] Beginning Business Activity (All calls to Web services that support WS-BA will be included in this activity) +INFO [stdout] (management-handler-threads - 5) [CLIENT] invoking addValueToSet(1) on WS +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] invoked addValueToSet('1') +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Enlisting a participant into the BA +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Invoking the back-end business logic +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare the backend resource and if successful notify the coordinator that we have completed our work +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Prepare successful, notifying coordinator of completion +INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Participant.confirmCompleted('true') (This tells the participant that compensation information has been logged and that it is safe to commit any changes.) +---- + +// Restore the {productName} Standalone Server Configuration +include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] + +// Run the Quickstart in Red Hat CodeReady Studio or Eclipse +include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] + +// Additional Red Hat CodeReady Studio instructions +This quickstart is more complex than the others. It requires that you configure the {productName} server using the configure-server.cli file. + +. Import the quickstart into {JBDSProductName}. +. If you have not already done so, you must configure a new {productName} server to use the XTS configuration. +** In the *Servers* tab, right-click and choose *New* -> *Server*. +** Under *Select the server type:*, expand *Red Hat JBoss Middleware* and choose *{jbdsEapServerName}*. +** For the *Server name*, enter `{productName} XTS Configuration` and click `Next`. +** In the *Create a new Server Adapter* dialog, choose *Create a new runtime (next page)* from the drop-down menu and click *Next*. +** In the *JBoss Runtime* dialog, enter the following information and then click *Finish*. ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +*Name*: `{productName} XTS Runtime` +*Home Directory*: __Browse to the __{jbossHomeName}__ directory and select it.__ +*Runtime JRE*: __Choose an alternate JRE if not correct.__ +*Server base directory*: __This should already point to your standalone server configuration directory,__ +*Configuration file*: `standalone.xml` +---- + +. Start the new *{productName} XTS Configuration* server. +. Right-click on the *{artifactId}* project, choose *Run As* -> *Maven build*, enter `clean verify -Parq-remote` for the *Goals*, and click *Run* to run the Arquillian tests. The test results appear in the console. + +// Debug the Application +include::../shared-doc/debug-the-application.adoc[leveloffset=+1] + +//************************************************* +// Product Release content only +//************************************************* +ifdef::ProductRelease[] + +// Quickstart not compatible with OpenShift +include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] + +endif::[] \ No newline at end of file diff --git a/wsba-participant-completion-simple/README.adoc b/wsba-participant-completion-simple/README.adoc index f5d921b906..a3e704d147 100644 --- a/wsba-participant-completion-simple/README.adoc +++ b/wsba-participant-completion-simple/README.adoc @@ -1,4 +1,201 @@ -include::../shared-doc/attributes.adoc[] +ifdef::env-github[] +:artifactId: wsba-participant-completion-simple +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 +// Do not update the following until after the 7.4 docs are published! +:DocInfoProductNumber: 7.4 +: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.Beta +// 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 = wsba-participant-completion-simple: Deployment of a WS-BA enabled JAX-WS Web Service :author: Paul Robinson @@ -52,11 +249,66 @@ There are additional tests that show: * How the client can cancel a BA. // Link to the quickstart source -include::../shared-doc/view-the-source.adoc[leveloffset=+1] +:leveloffset: +1 + +ifndef::ProductRelease,EAPXPRelease[] +link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] +endif::[] + +:leveloffset!: // System Requirements -include::../shared-doc/system-requirements.adoc[leveloffset=+1] +: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} -include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1] +: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!: [[start_the_eap_standalone_server]] == Start the {productName} Standalone Server @@ -80,7 +332,7 @@ You can configure the server by running JBoss CLI commands. For your convenience . Before you begin, make sure you do the following: * xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above. -* Start the {productName} server with the standalone default profile : +* Start the {productName} server with the standalone default profile : + [source,subs="+quotes,attributes+",options="nowrap"] ---- @@ -141,7 +393,58 @@ $ __{jbossHomeName}__/bin/standalone.sh NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. // Run the Arquillian Tests -include::../shared-doc/run-arquillian-tests.adoc[leveloffset=+1] +:leveloffset: +1 + +[[run_the_arquillian_tests]] += Run the Arquillian Tests +//****************************************************************************** +// Include this template if your quickstart provides standard Arquillian tests. +//****************************************************************************** + +This quickstart provides Arquillian tests. By default, these tests are configured to be skipped since Arquillian tests require the use of a container. + +NOTE: The Arquillian tests deploy the application, so make sure you undeploy the quickstart before you begin. + +ifdef::arq-prerequisities[] +== Arquillian Tests prerequisities + +{arq-prerequisities} +endif::[] + +Follow these steps to run the tests. + +ifdef::standalone-server-type[] +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +endif::[] + +ifdef::managed-domain-type[] +. xref:start_the_eap_managed_domain[Start the {productName} server] as described above. +endif::[] + +. Open a terminal and navigate to the root directory of this quickstart. +. Type the following command to run the `verify` goal with the `arq-remote` profile activated. ++ +[source,options="nowrap"] +---- +$ mvn clean verify -Parq-remote +---- +ifdef::arquillianTestResults[] +You should see the following results: ++ +[source,subs=attributes+,options="nowrap"] +---- +Results : + +{arquillianTestResults} +---- +endif::[] + +[NOTE] +==== +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile, meaning the tests will start the server for you. This profile requires that you provide Arquillian with the location of the {productName} server, either by setting the `JBOSS_HOME` environment variable, or by setting the `jbossHome` property in the `arquillian.xml` file. For more information, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. +==== + +:leveloffset!: [[investigate_the_console_output]] == Investigate the Console Output @@ -207,10 +510,63 @@ INFO [stdout] (http-localhost-127.0.0.1-8080-1) [SERVICE] Participant.confirmCo ---- // Restore the {productName} Standalone Server Configuration -include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2] +:leveloffset: +2 + +[[restore_the_standalone_server_configuration]] += Restore the {productName} Standalone Server Configuration +//****************************************************************************** +// Include this template if your quickstart does a normal restoration of a single +// standalone server configuration. +// * It provides a CLI script. +// * You can manually restore the backup copy. +// +// You must define the script file name using the `restoreScriptName` attribute. +// For example: +// :restoreScriptName: remove-configuration.cli +//****************************************************************************** + +You can restore the original server configuration using either of the following methods. + +* You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. +* You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. + +[[restore_standalone_server_configuration_using_cli]] +== Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script + +. xref:start_the_eap_standalone_server[Start the {productName} server] as described above. +. 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: ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file={restoreScriptName} +---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + +:leveloffset!: // Run the Quickstart in Red Hat CodeReady Studio or Eclipse -include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1] +:leveloffset: +1 + +[[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[] + +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[] + +// Add additional instructions specific to running this quickstart in an IDE here. + +:leveloffset!: // Additional Red Hat CodeReady Studio instructions This quickstart is more complex than the others. It requires that you configure the {productName} server using the configure-server.cli file. @@ -236,7 +592,33 @@ This quickstart is more complex than the others. It requires that you configure . Right-click on the *{artifactId}* project, choose *Run As* -> *Maven build*, enter `clean verify -Parq-remote` for the *Goals*, and click *Run* to run the Arquillian tests. The test results appear in the console. // Debug the Application -include::../shared-doc/debug-the-application.adoc[leveloffset=+1] +:leveloffset: +1 + +[[debug_the_application]] += Debug the Application +//****************************************************************************** +// Include this template to provide debugging information. +//****************************************************************************** + +If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. + +---- +$ mvn dependency:sources +---- + +//// +TODO: I need to investigate whether the following version can be used across all quickstarts. + +If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. + +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- +//// + +:leveloffset!: //************************************************* // Product Release content only @@ -246,4 +628,4 @@ ifdef::ProductRelease[] // Quickstart not compatible with OpenShift include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1] -endif::[] \ No newline at end of file +endif::[] diff --git a/wsba-participant-completion-simple/pom.xml b/wsba-participant-completion-simple/pom.xml index 220372510e..02f4db3480 100644 --- a/wsba-participant-completion-simple/pom.xml +++ b/wsba-participant-completion-simple/pom.xml @@ -25,12 +25,12 @@ Maintain separation between the artifact id and the version to help prevent merge conflicts between commits changing the GA and those changing the V. --> - 7 + 8 wsba-participant-completion-simple - 31.0.0.Final-SNAPSHOT + 31.0.0.Final jar Quickstart: wsba-participant-completion-simple This project demonstrates WS-BA with Participant Driven Completion