├── .gitkeep ├── product_videos.adoc ├── guides ├── USE_OF_EAP_HOME.md ├── USE_OF_EAP7_HOME.md ├── USE_OF_WILDFLY_HOME.adoc ├── USE_OF_EAP_HOME.adoc ├── START_JBOSS_EAP.md ├── CONFIGURE_MAVEN_JBOSS_EAP7.md ├── START_JBOSS_EAP.adoc ├── CONFIGURE_MAVEN_JBOSS_EAP.adoc ├── CONFIGURE_BYTEMAN.md ├── BUILD_AND_DEPLOY_EAP7.md ├── BUILD_AND_DEPLOY_JBOSS_EAP.adoc ├── CONFIGURE_BYTEMAN.adoc ├── BUILD_AND_DEPLOY.md ├── RUN_ARQUILLIAN_TESTS.adoc ├── RUN_ARQUILLIAN_TESTS.md ├── CREATE_USERS.md ├── DEPLOY_TO_OPENSHIFT.md ├── CREATE_USERS.adoc ├── CONFIGURE_MAVEN.md ├── DEPLOY_TO_OPENSHIFT_JBOSS_EAP7.md ├── CONFIGURE_POSTGRESQL.md ├── CONFIGURE_POSTGRESQL_EAP7.md ├── USE_JBDS.md ├── CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc └── USE_JBDS.adoc ├── README.md ├── templates └── README.md └── dist ├── css ├── pygments.css └── documentation.css ├── github-flavored-markdown.rb └── release-utils.sh /.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /product_videos.adoc: -------------------------------------------------------------------------------- 1 | = Adding videos to albums in vimeo 2 | Jason Porter 3 | 4 | If you would like to add a new video to products on the jboss.org product web pages, please follow the instructions below. Adding the video with the below instructions will add it to the Developer Materials section. It may take a few hours for changes to be reflected on the site. 5 | 6 | We have new albums in our vimeo account that correspond to each of our supported middleware products. The current videos on our account need to be categorized and placed into the appropriate albums, where applicable. 7 | 8 | == Adding videos to albums 9 | 10 | . Login to vimeo at https://vimeo.com 11 | + 12 | NOTE: If you do not have login credentials, please talk to Ray or Andrew 13 | + 14 | . Navigate to https://vimeo.com/organizer/collections 15 | . Find the album you wish to add videos 16 | . Click the `>>` link next to the album name 17 | . Click the btn:[Settings] button 18 | . Click the `Videos` link 19 | . Click the `Add More Videos` link 20 | . Proceed to add videos by clicking on the `+` icon in the top right of the desired videos. 21 | -------------------------------------------------------------------------------- /guides/USE_OF_EAP_HOME.md: -------------------------------------------------------------------------------- 1 | Use of EAP_HOME and JBOSS_HOME Variables 2 | ============================= 3 | 4 | The developer guides and quickstart README files use the *replaceable* value `EAP_HOME` to denote the path to the Red Hat JBoss Enterprise Application Platform 7 installation. When you encounter this value in a README file or guide, be sure to replace it with the actual path to your JBoss EAP 7 installation. 5 | 6 | * If you installed JBoss EAP using the ZIP, the install directory is the path you specified when you ran the command. 7 | 8 | * If you installed JBoss EAP using the RPM, the install directory is `/opt/rh/eap7/root/usr/share/wildfly/`. 9 | 10 | * If you used the installer to install JBoss EAP, the default path for `EAP_HOME` is `${user.home}/jboss-eap-7.3/`. 11 | 12 | For Linux: /home/USER_NAME/jboss-eap-7.3/ 13 | For Windows: "C:\Users\USER_NAME\jboss-eap-7.3\" 14 | 15 | * If you used the Red Hat CodeReady Studio installer to install and configure the JBoss EAP Server, the default path for `EAP_HOME` is `${user.home}/jboss-eap-7.3`. 16 | 17 | For Linux: /home/USER_NAME/jboss-eap-7.3/ 18 | For Windows: "C:\Users\USER_NAME\jboss-eap-7.3\" or "C:\Documents and Settings\USER_NAME\jboss-eap-7.3\" 19 | 20 | The `JBOSS_HOME` *environment* variable, which is used in scripts, continues to work as it has in the past. 21 | 22 | 23 | 24 | -------------------------------------------------------------------------------- /guides/USE_OF_EAP7_HOME.md: -------------------------------------------------------------------------------- 1 | Use of EAP7_HOME and JBOSS_HOME Variables 2 | ============================= 3 | 4 | The developer guides and quickstart README files use the *replaceable* value `EAP7_HOME` to denote the path to the Red Hat JBoss Enterprise Application Platform 7 installation. When you encounter this value in a README file or guide, be sure to replace it with the actual path to your JBoss EAP 7 installation. 5 | 6 | * If you installed JBoss EAP using the ZIP, the install directory is the path you specified when you ran the command. 7 | 8 | * If you installed JBoss EAP using the RPM, the install directory is `/opt/rh/eap7/root/usr/share/wildfly`. 9 | 10 | * If you used the installer to install JBoss EAP, the default path for `EAP7_HOME` is `${user.home}/EAP-7.0.0`. 11 | 12 | For Linux: /home/USER_NAME/EAP-7.0.0/ 13 | For Windows: "C:\Users\USER_NAME\EAP-7.0.0\" 14 | 15 | * If you used the JBoss Developer Studio installer to install and configure the JBoss EAP Server, the default path for `EAP7_HOME` is `${user.home}/jbdevstudio/runtimes/jboss-eap`. 16 | 17 | For Linux: /home/USER_NAME/jbdevstudio/runtimes/jboss-eap/ 18 | For Windows: "C:\Users\USER_NAME\jbdevstudio\runtimes\jboss-eap" or "C:\Documents and Settings\USER_NAME\jbdevstudio\runtimes\jboss-eap\" 19 | 20 | The `JBOSS_HOME` *environment* variable, which is used in scripts, continues to work as it has in the past. 21 | 22 | 23 | 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | JBoss Developer Shared Resources 3 | ============================== 4 | 5 | This repository contains JBoss developer instructions and information shared by all of the Red Hat JBoss Enterprise Application Platform and JBoss Middleware quickstarts. 6 | 7 | It includes the following guides: 8 | 9 | * [Configure Maven to Build and Deploy the Quickstarts](guides/CONFIGURE_MAVEN_JBOSS_EAP.adoc): Configure Maven to use the JBoss EAP public repositories before you build and deploy the quickstarts. 10 | * [Create Users Required by the Quickstarts](guides/CREATE_USERS.adoc): Create management and application users for use by quickstarts that use security enabled management interfaces. 11 | * [Start the Red Hat JBoss Enterprise Application Platform Server](guides/START_JBOSS_EAP.adoc): Start the JBoss EAP server using different configuration options. 12 | * [Run the Arquillian Tests](guides/RUN_ARQUILLIAN_TESTS.adoc): Run Arquillian tests provided by many of the quickstarts. 13 | * [Use Red Hat JBoss Developer Studio or Eclipse to Run the Quickstarts](guides/USE_JBDS.adoc): Use Red Hat JBoss Developer Studio to deploy and test the quickstarts. 14 | * [Deploy quickstarts to OpenShift](guides/DEPLOY_TO_OPENSHIFT.md): Learn how to deploy the quickstarts to OpenShift. 15 | * [Configure the PostgreSQL Database for Use with the Quickstarts](guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc): Install and configure PostgreSQL for quickstarts that use it. 16 | * [Configure Byteman for Use with the Quickstarts](guides/CONFIGURE_BYTEMAN.adoc): Configure Byteman for quickstarts that use it to simulate transaction processing. 17 | * [Contribute to the quickstarts](guides/CONTRIBUTING.adoc): Learn how you can contribute to JBoss developer projects. 18 | -------------------------------------------------------------------------------- /guides/USE_OF_WILDFLY_HOME.adoc: -------------------------------------------------------------------------------- 1 | :ProductInstallFolderZip: jboss-eap-7.2 2 | :ProductInstallFolderInstaller: EAP-7.2.0 3 | :JBDSProductName: Red Hat Developer Studio 4 | 5 | [[use_of_product_home_and_jboss_home_variables]] 6 | = Use of WILDFLY_HOME and JBOSS_HOME Variables 7 | 8 | The developer guides and quickstart `README` files use the *replaceable* value `__WILDFLY_HOME__` to denote the path to the Red Hat JBoss Enterprise Application Platform 7 installation. When you encounter this value in a `README` file or guide, be sure to replace it with the actual path to your WildFly installation. 9 | 10 | * If you installed WildFly using the ZIP install method, the install directory is the `{ProductInstallFolderZip}` directory where you extracted the ZIP archive. 11 | 12 | * If you installed WildFly using the RPM install method, the install directory is `/opt/rh/eap7/root/usr/share/wildfly/`. 13 | 14 | * If you used the installer to install WildFly, the default path for `__WILDFLY_HOME__` is `${user.home}/{ProductInstallFolderInstaller}`. 15 | 16 | ** For Red Hat Enterprise Linux, Solaris, and HP-UX: `/home/__USER_NAME__/{ProductInstallFolderInstaller}/` 17 | ** For Microsoft Windows: `C:\Users{backslash}__USER_NAME__{backslash}{ProductInstallFolderInstaller}\` 18 | 19 | * If you used the {JBDSProductName} installer to install and configure the WildFly Server, the default path for `__WILDFLY_HOME__` is `${user.home}/jbdevstudio/runtimes/jboss-eap`. 20 | 21 | ** For Linux: /home/__USER_NAME__/jbdevstudio/runtimes/jboss-eap/ 22 | ** For Windows: `C:\Users{backslash}__USER_NAME__\jbdevstudio\runtimes\jboss-eap` or `C:\Documents and Settings{backslash}__USER_NAME__\jbdevstudio\runtimes\jboss-eap\` 23 | 24 | The `JBOSS_HOME` *environment* variable, which is used in scripts, continues to work as it has in the past. 25 | -------------------------------------------------------------------------------- /guides/USE_OF_EAP_HOME.adoc: -------------------------------------------------------------------------------- 1 | :ProductInstallFolderZip: jboss-eap-7.3 2 | :ProductInstallFolderInstaller: EAP-7.3.0 3 | :JBDSProductName: Red Hat CodeReady Studio 4 | 5 | [[use_of_product_home_and_jboss_home_variables]] 6 | = Use of EAP_HOME and JBOSS_HOME Variables 7 | 8 | The developer guides and quickstart `README` files use the *replaceable* value `__EAP_HOME__` to denote the path to the Red Hat JBoss Enterprise Application Platform 7 installation. When you encounter this value in a `README` file or guide, be sure to replace it with the actual path to your JBoss EAP 7 installation. 9 | 10 | * If you installed JBoss EAP using the ZIP install method, the install directory is the `{ProductInstallFolderZip}` directory where you extracted the ZIP archive. 11 | 12 | * If you installed JBoss EAP using the RPM install method, the install directory is `/opt/rh/eap7/root/usr/share/wildfly/`. 13 | 14 | * If you used the installer to install JBoss EAP, the default path for `__EAP_HOME__` is `${user.home}/{ProductInstallFolderInstaller}`. 15 | 16 | ** For Red Hat Enterprise Linux, Solaris, and HP-UX: `/home/__USER_NAME__/{ProductInstallFolderInstaller}/` 17 | ** For Microsoft Windows: `C:\Users{backslash}__USER_NAME__{backslash}{ProductInstallFolderInstaller}\` 18 | 19 | * If you used the {JBDSProductName} installer to install and configure the JBoss EAP Server, the default path for `__EAP_HOME__` is `${user.home}/{ProductInstallFolderZip}`. 20 | 21 | ** For Linux: /home/__USER_NAME__/{ProductInstallFolderZip}/ 22 | ** For Windows: `C:{backslash}Users{backslash}__USER_NAME__{backslash}{ProductInstallFolderZip}{backslash}` or `C:{backslash}Documents and Settings{backslash}__USER_NAME__{backslash}{ProductInstallFolderZip}{backslash}` 23 | 24 | The `JBOSS_HOME` *environment* variable, which is used in scripts, continues to work as it has in the past. 25 | -------------------------------------------------------------------------------- /templates/README.md: -------------------------------------------------------------------------------- 1 | OpenShift JBoss EAP Application Templates 2 | === 3 | 4 | The `jboss-openshift` [application templates repository](https://github.com/jboss-openshift/application-templates/tree/ose-v1.3.2/eap) defines build configurations for [binary type builds](https://docs.openshift.com/enterprise/3.2/dev_guide/builds.html#binary-source). These templates allow you to consume source code located on a local file system instead files hosted on a remote GitHub repository. 5 | 6 | Follow these instructions to configure your OpenShift environment to use a quickstart located on your local file system. 7 | 8 | 1. Download and extract the JBoss EAP 7 quickstarts from the Customer Portal. For more information, see [Download the Quickstarts](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/version-7.0/getting-started-guide/#download_the_quickstarts) in the _Getting Started Guide_ for JBoss EAP 7. 9 | 2. Navigate to the root directory of the downloaded `greeter` quickstart. 10 | 3. Follow the instructions to [Create the Secrets](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/DEPLOY_TO_OPENSHIFT_JBOSS_EAP7.md#create_the_secrets). 11 | 4. If necessary, create the necessary image streams. 12 | 5. Create the service account for the binary build by typing the following command in a terminal. 13 | 14 | oc create -f https://raw.githubusercontent.com/jboss-developer/jboss-developer-shared-resources/master/templates/eap70-postgresql-binary-s2i.json 15 | 16 | 6. Create the new OpenShift application. 17 | 18 | oc new-app --template=eap70-postgresql-binary-s2i -p \ 19 | SOURCE_REPOSITORY_URL=https://github.com/josefkarasek/jboss-eap-quickstarts,\ 20 | SOURCE_REPOSITORY_REF=7.1.x-develop,\ 21 | CONTEXT_DIR=greeter,\ 22 | DB_JNDI=java:jboss/datasources/GreeterQuickstartDS,\ 23 | DB_DATABASE=USERS,\ 24 | HTTPS_NAME=jboss,\ 25 | HTTPS_PASSWORD=mykeystorepass,\ 26 | JGROUPS_ENCRYPT_NAME=secret-key,\ 27 | JGROUPS_ENCRYPT_PASSWORD=password 28 | 29 | 6. Binary type builds can not leverage any web hooks or triggers provided by the Git hosting infrastructure, so you must trigger the build manually by typing the following command in a terminal. Be sure to replace QUICKSTART_HOME with the path to your local `greeter` quickstart. 30 | 31 | oc start-build eap-app --QUICKSTART_HOME . --follow 32 | -------------------------------------------------------------------------------- /guides/START_JBOSS_EAP.md: -------------------------------------------------------------------------------- 1 | Start the Red Hat JBoss Enterprise Application Platform Server 2 | =========================== 3 | 4 | Before you deploy a quickstart using the Maven command line tool, in most cases you need a running Red Hat JBoss Enterprise Application Platform server. A few of the Arquillian tests do not require a running server. This will be noted in the README for that quickstart. 5 | 6 | The JBoss EAP server can be started the following ways. 7 | 8 | * [Start the Default JBoss EAP Server](#start-the-default-jboss-eap-server): This is the default configuration. It defines minimal subsystems and services. 9 | * [Start the JBoss EAP Server with the Full Profile](#start-the-jboss-eap-server-with-the-full-profile): This profile configures many of the commonly used subsystems and services. 10 | * [Start the JBoss EAP Server with Custom Configuration Options](#start-the-jboss-eap-server-with-custom-configuration-options): Custom configuration parameters can be specified on the command line when starting the server. 11 | 12 | The README for each quickstart specifies which configuration is required to run the example. 13 | 14 | A few [examples of commands to start the JBoss EAP server](#examples-of-commands-to-start-the-jboss-eap-server) are displayed at the end of this guide. 15 | 16 | _NOTE: See [Use of EAP_HOME](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP_HOME.md) for information about the JBoss EAP installation path._ 17 | 18 | 19 | Start the Default JBoss EAP Server 20 | ------------------------------ 21 | 22 | To start the default JBoss EAP server: 23 | 24 | 1. Open a terminal and navigate to the root of the JBoss EAP server directory. 25 | 2. The following shows the command to start the JBoss EAP server: 26 | 27 | For Linux: EAP_HOME/bin/standalone.sh 28 | For Windows: EAP_HOME\bin\standalone.bat 29 | 30 | Start the JBoss EAP Server with the Full Profile 31 | ------------------------------ 32 | 33 | To start JBoss EAP with the Full Profile: 34 | 35 | 1. Open a terminal and navigate to the root of the JBoss EAP server directory. 36 | 2. The following shows the command to start the JBoss EAP server with the full profile: 37 | 38 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml 39 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml 40 | 41 | Start the JBoss EAP Server with Custom Configuration Options 42 | ------------------------------ 43 | 44 | To start JBoss EAP with custom configuration options: 45 | 46 | 1. Open a terminal and navigate to the root of the JBoss EAP server directory. 47 | 2. The following shows the command to start the JBoss EAP server. Replace CUSTOM_OPTIONS with the custom optional parameters specified in the quickstart README file. 48 | 49 | For Linux: EAP_HOME/bin/standalone.sh CUSTOM_OPTIONS 50 | For Windows: EAP_HOME\bin\standalone.bat CUSTOM_OPTIONS 51 | 52 | 53 | Examples of Commands to Start the JBoss EAP Server 54 | ------------------------------ 55 | 56 | The following are a few examples of how to start the server with custom options: 57 | 58 | * Start the default server with a port offset of `100`: 59 | 60 | EAP_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100 61 | 62 | * Start the server with the OSGI configuration option: 63 | 64 | EAP_HOME/bin/standalone.sh -c standalone-osgi.xml 65 | 66 | * Start the server with the XTS subsystem enabled: 67 | 68 | EAP_HOME/bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml 69 | 70 | * Start the JBoss EAP server with the `full profile`, giving it the unique node ID `node1`: 71 | 72 | EAP_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=node1 73 | 74 | -------------------------------------------------------------------------------- /guides/CONFIGURE_MAVEN_JBOSS_EAP7.md: -------------------------------------------------------------------------------- 1 | Configure Maven to Build and Deploy the Quickstarts 2 | =============== 3 | 4 | Overview 5 | -------- 6 | 7 | The artifacts and dependencies needed to build and deploy applications to Red Hat JBoss Enterprise Application Platform 7 are hosted in public repositories. JBoss EAP 6 required that you configure your Maven `settings.xml` file to use those repositories when building the quickstarts. In JBoss EAP 7, this has changed. Maven is now configured in the quickstart project POM files. This method of configuration is provided to make it easier to get started with the quickstarts, however, is generally not recommended for production projects because it can slow down your build. You may even end up with artifacts that are not from the expected repository. For more information, see the [Product Documentation](https://access.redhat.com/documentation/en/jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform. 8 | 9 | You can skip these instructions if you meet one of the following criteria: 10 | 11 | * You plan to use Maven command line and have already installed Maven 3.2.0 or later. In this case, you should already be configured to build and deploy the quickstarts. 12 | * You plan to use Red Hat JBoss Developer Studio 9.1 or later to build and deploy the quickstarts. These IDEs embed Maven 3.2.1 so you do not need to install it separately. 13 | 14 | Some common profiles are defined and may be used in some quickstart POM files. These profiles are described here: [Use of Maven Profiles in POM Files](#use-of-maven-profiles-in-pom-files) 15 | 16 | Download and Install Maven 17 | -------------------------- 18 | 19 | If you plan to use the command line and have not yet done so, you must download and install Maven 3.2.0 or later. 20 | 21 | 1. Go to [Apache Maven Project - Download Maven](http://maven.apache.org/download.html) and download the latest distribution for your operating system. 22 | 2. See the Maven documentation for information on how to download and install Apache Maven for your operating system. 23 | 24 | _IMPORTANT_: There is a known issue with the checkstyle plugin for Maven versions 3.2.1 through 3.3.3 that results in build failure if you attempt to build the quicktarts using the `mvn install` command. You can disable the checkstyle plugin by adding the `-Dcheckstyle.skip=true` argument on the command line, for example: `mvn clean install -Dcheckstyle.skip=true`. The checkstyle plugin is not an issue if you run with Maven 3.3.9 or later. For more information, see [JBEAP-13943](https://issues.jboss.org/browse/JBEAP-13943). 25 | 26 | Use of Maven Profiles in POM Files 27 | ---------------------------------- 28 | 29 | Profiles are used by Maven to customize the build environment. The `pom.xml` in the root of some quickstart directories may define some of the following profiles. 30 | 31 | _NOTE:_ Some profiles in this list may not be used by some product quickstart projects. 32 | 33 | * The `default` profile defines the list of modules or quickstarts that require nothing but Red Hat JBoss Enterprise Application Platform. 34 | * The `requires-postgres` profile lists the quickstarts that require PostgreSQL to be running when the quickstart is deployed. 35 | * The `complex-dependency` profile lists quickstarts that require manual configuration that can not be automated. 36 | * The `requires-full` profile lists quickstarts the require you start the JBoss EAP server using the full profile. 37 | * The `requires-xts` profile lists quickstarts the require you start the JBoss EAP server using the xts profile. 38 | * The `non-maven` profile lists quickstarts that do not require Maven, for example, quickstarts that depend on deployment of other quickstarts or those that use other Frameworks such as Forge. 39 | * The `functional-tests` profile lists quickstarts that provide functional tests. 40 | 41 | [Back to top](#configure-maven-to-build-and-deploy-the-quickstarts) 42 | -------------------------------------------------------------------------------- /guides/START_JBOSS_EAP.adoc: -------------------------------------------------------------------------------- 1 | [[start_the_red_hat_jboss_enterprise_application_platform_server]] 2 | = Start the Red Hat JBoss Enterprise Application Platform Server 3 | 4 | Before you deploy a quickstart using the Maven command line tool, in most cases you need a running Red Hat JBoss Enterprise Application Platform server. A few of the Arquillian tests do not require a running server. This will be noted in the `README` file for that quickstart. 5 | 6 | The JBoss EAP server can be started the following ways. 7 | 8 | * xref:start_the_default_jboss_eap_server[Start the Default JBoss EAP Server]: This is the default configuration. It defines minimal subsystems and services. 9 | * xref:start_the_jboss_eap_server_with_the_full_profile[Start the JBoss EAP Server with the Full Profile]: This profile configures many of the commonly used subsystems and services. 10 | * xref:start_the_jboss_eap_server_with_custom_configuration_options[Start the JBoss EAP Server with Custom Configuration Options]: Custom configuration parameters can be specified on the command line when starting the server. 11 | 12 | The README for each quickstart specifies which configuration is required to run the example. 13 | 14 | A few xref:examples_of_commands_to_start_the_jboss_eap_server[examples of commands to start the JBoss EAP server] are displayed at the end of this guide. 15 | 16 | NOTE: See link:USE_OF_EAP_HOME.adoc[Use of __EAP_HOME__] for information about the JBoss EAP installation path. 17 | 18 | [[start_the_default_jboss_eap_server]] 19 | == Start the Default JBoss EAP Server 20 | 21 | To start the default JBoss EAP server: 22 | 23 | . Open a terminal and navigate to the root of the JBoss EAP server directory. 24 | . The following shows the command to start the JBoss EAP server: 25 | 26 | * For Linux: `$ __EAP_HOME__/bin/standalone.sh` 27 | * For Windows: `> __EAP_HOME__\bin\standalone.bat` 28 | 29 | [[start_the_jboss_eap_server_with_the_full_profile]] 30 | == Start the JBoss EAP Server with the Full Profile 31 | 32 | To start JBoss EAP with the full profile: 33 | 34 | . Open a terminal and navigate to the root of the JBoss EAP server directory. 35 | . The following shows the command to start the JBoss EAP server with the full profile: 36 | 37 | * For Linux: `$ __EAP_HOME__/bin/standalone.sh -c standalone-full.xml` 38 | * For Windows: `> __EAP_HOME__\bin\standalone.bat -c standalone-full.xml` 39 | 40 | [[start_the_jboss_eap_server_with_custom_configuration_options]] 41 | == Start the JBoss EAP Server with Custom Configuration Options 42 | 43 | To start JBoss EAP with custom configuration options: 44 | 45 | . Open a terminal and navigate to the root of the JBoss EAP server directory. 46 | . The following shows the command to start the JBoss EAP server. Replace `__CUSTOM_OPTIONS__` with the custom optional parameters specified in the quickstart `README` file. 47 | 48 | * For Linux: `$ __EAP_HOME__/bin/standalone.sh __CUSTOM_OPTIONS__` 49 | * For Windows: `> __EAP_HOME__\bin\standalone.bat __CUSTOM_OPTIONS__` 50 | 51 | [[examples_of_commands_to_start_the_jboss_eap_server]] 52 | == Examples of Commands to Start the JBoss EAP Server 53 | 54 | The following are a few examples of how to start the server with custom options: 55 | 56 | * Start the default server with a port offset of `100`: 57 | + 58 | [source,subs="+quotes",options="nowrap"] 59 | ---- 60 | $ __EAP_HOME__/bin/standalone.sh -Djboss.socket.binding.port-offset=100 61 | ---- 62 | * Start the server with the OSGI configuration option: 63 | + 64 | [source,subs="+quotes",options="nowrap"] 65 | ---- 66 | $ __EAP_HOME__/bin/standalone.sh -c standalone-osgi.xml 67 | ---- 68 | * Start the server with the XTS subsystem enabled: 69 | + 70 | [source,subs="+quotes",options="nowrap"] 71 | ---- 72 | $ __EAP_HOME__/bin/standalone.sh --server-config=../../docs/examples/configs/standalone-xts.xml 73 | ---- 74 | * Start the JBoss EAP server with the `full profile`, giving it the unique node ID `node1`: 75 | + 76 | [source,subs="+quotes",options="nowrap"] 77 | ---- 78 | $ __EAP_HOME__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=node1 79 | ---- 80 | -------------------------------------------------------------------------------- /guides/CONFIGURE_MAVEN_JBOSS_EAP.adoc: -------------------------------------------------------------------------------- 1 | :JBDSProductName: Red Hat Developer Studio 2 | 3 | [[configure_maven_to_build_and_deploy_the_quickstarts]] 4 | = Configure Maven to Build and Deploy the Quickstarts 5 | 6 | [[configure_maven_overview]] 7 | == Overview 8 | 9 | The artifacts and dependencies needed to build and deploy applications to Red Hat JBoss Enterprise Application Platform are hosted in public repositories. JBoss EAP 6 required that you configure your Maven `settings.xml` file to use those repositories when building the quickstarts. In JBoss EAP 7, this has changed. Maven is now configured in the quickstart project POM files. This method of configuration is provided to make it easier to get started with the quickstarts, however, is generally not recommended for production projects because it can slow down your build. You might even end up with artifacts that are not from the expected repository. For more information, see the https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/[Product Documentation] for Red Hat JBoss Enterprise Application Platform. 10 | 11 | You can skip these instructions if you meet one of the following criteria: 12 | 13 | * You plan to use Maven command line and have already installed Maven 3.2.0 or later. In this case, you should already be configured to build and deploy the quickstarts. 14 | * You plan to use {JBDSProductName} 9.1 or later to build and deploy the quickstarts. These IDEs embed Maven 3.2.1 so you do not need to install it separately. 15 | 16 | Some common profiles are defined and can be used in some quickstart POM files. These profiles are described in xref:use_of_maven_profiles_in_pom_files[Use of Maven Profiles in POM Files]. 17 | 18 | [[download_and_install_maven]] 19 | == Download and Install Maven 20 | 21 | If you plan to use the command line and have not yet done so, you must download and install Maven 3.2.0 or later. 22 | 23 | 1. Open a browser, navigate to http://maven.apache.org/download.html[Apache Maven Project - Download Maven], and download the latest distribution for your operating system. 24 | 2. See the Maven documentation for information on how to download and install Apache Maven for your operating system. 25 | 26 | IMPORTANT: There is a known issue with the checkstyle plugin for Maven versions 3.2.1 through 3.3.3 that results in build failure if you attempt to build the quicktarts using the `mvn install` command. You can disable the checkstyle plugin by adding the `-Dcheckstyle.skip=true` argument on the command line, for example: `mvn clean install -Dcheckstyle.skip=true`. The checkstyle plugin is not an issue if you run with Maven 3.3.9 or later. For more information, see https://issues.jboss.org/browse/JBEAP-13943[JBEAP-13943]. 27 | 28 | [[use_of_maven_profiles_in_pom_files]] 29 | == Use of Maven Profiles in POM Files 30 | 31 | Profiles are used by Maven to customize the build environment. The `pom.xml` in the root of some quickstart product repositories might define some of the following profiles. 32 | 33 | NOTE: Some profiles in this list may not be used by some product quickstart projects. 34 | 35 | * The `default` profile defines the list of modules or quickstarts that require nothing but Red Hat JBoss Enterprise Application Platform. 36 | * The `requires-postgres` profile lists the quickstarts that require PostgreSQL to be running when the quickstart is deployed. 37 | * The `complex-dependencies` profile lists quickstarts that require manual configuration that can not be automated. 38 | * The `requires-full` profile lists quickstarts the require you start the JBoss EAP server using the full profile. 39 | * The `requires-xts` profile lists quickstarts the require you start the JBoss EAP server using the xts profile. 40 | * The `non-maven` profile lists quickstarts that do not require Maven, for example, quickstarts that depend on deployment of other quickstarts or those that use other Frameworks such as Forge. 41 | * The `functional-tests` profile lists quickstarts that provide functional tests. 42 | 43 | xref:configure_maven_to_build_and_deploy_the_quickstarts[Back to top] 44 | -------------------------------------------------------------------------------- /guides/CONFIGURE_BYTEMAN.md: -------------------------------------------------------------------------------- 1 | Configure Byteman for Use with the Quickstarts 2 | ============================= 3 | Summary: _Byteman_ is a tool that simplifies tracing and testing of Java programs. It allows you to insert extra Java code into your application, either as it is loaded during JVM startup or after it has already started running. This code can be used to trace what the application is doing and to monitor and debug deployments to be sure it is operating correctly. You can also use _Byteman_ to inject faults or synchronization code when testing your application. 4 | 5 | A few of the quickstarts use _Byteman_ to demonstrate distributed transaction processing and crash recovery, for example, to halt an application server in the middle of a distributed transaction to demonstrate crash recovery. 6 | 7 | The following sections describe the steps necessary to install, configure, and use _Byteman_ with these quickstarts. 8 | 9 | * [Download and Configure Byteman](#download-and-configure-byteman) 10 | * [Clear the Transaction ObjectStore](#clear-the-transaction-objectstore) 11 | * [Use Byteman to Halt the Application](#use-byteman-to-halt-the-application) 12 | * [Disable the Byteman Script](#disable-the-byteman-script) 13 | 14 | _NOTE: See [Use of EAP_HOME](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP_HOME.md) for information about the Red Hat JBoss Enterprise Application Platform installation path._ 15 | 16 | 17 | Download and Configure Byteman 18 | ------------------------------- 19 | 20 | 1. Download _Byteman_ from 21 | 2. Extract the ZIP file to a directory of your choice. In the instructions below, we refer to this directory as `BYTEMAN_HOME`. 22 | 3. By default, the _Byteman_ download provides unrestricted permissions to `others` which can cause a problem when running Ruby commands for the OpenShift quickstarts. To restrict the permissions to `others`, open a command prompt and type the following: 23 | 24 | chmod -R o-rwx BYTEMAN_HOME/ 25 | 26 | Clear the Transaction ObjectStore 27 | ------------------------- 28 | 29 | Transaction objectstore data remaining from previous tests can prevent _Byteman_ from working properly. You must remove any remaining data before running new _Byteman_ tests. If you are using the default file based transaction logging store: 30 | 31 | 1. Open a command prompt and type the following: 32 | 33 | ls EAP_HOME/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/ 34 | 2. If this directory exists and contains any files, delete them before starting the server: 35 | 36 | rm -rf EAP_HOME/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/* 37 | 3. On Windows, use the file manager to accomplish the same result. 38 | 39 | 40 | Use Byteman to Halt the Application 41 | ------------------------------- 42 | 43 | _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 JBoss EAP server before making the following changes. Otherwise _Byteman_ will not halt the server. 44 | 45 | When instructed to use _Byteman_ to halt the application, perform the following steps: 46 | 47 | 1. Find the appropriate configuration file for your operating system in the list below. 48 | 49 | For Linux: EAP_HOME/bin/standalone.conf 50 | For Windows: EAP_HOME\bin\standalone.conf.bat 51 | 52 | 2. **Important**: Make a backup copy of this configuration file before making any modifications! 53 | 54 | 3. Open the configuration file and append the text specified in the quickstart README instructions to the end of the configuration file. Be sure to replace the `BYTEMAN_HOME` with the path to the Byteman download and the `QUICKSTART_HOME` with the path to the quickstarts. 55 | 56 | The following is an example of of the configuration changes needed for the _jta-crash-rec_ quickstart. 57 | 58 | For Linux: 59 | 60 | JAVA_OPTS="-javaagent:/BYTEMAN_HOME/lib/byteman.jar=script:/QUICKSTART_HOME/jta-crash-rec/src/main/scripts/xa.btm ${JAVA_OPTS}" 61 | For Windows: 62 | 63 | SET "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%" 64 | 65 | 66 | Disable the Byteman Script 67 | ---------------------- 68 | 69 | When you have completed testing the quickstart, replace the server configuration file with the backup copy you created in step 2 above to disable _Byteman_. 70 | 71 | [Back to top](#configure-byteman-for-use-with-the-quickstarts) 72 | 73 | -------------------------------------------------------------------------------- /guides/BUILD_AND_DEPLOY_EAP7.md: -------------------------------------------------------------------------------- 1 | Build and Deploy the Quickstarts to JBoss EAP 7 2 | ===================== 3 | 4 | This document describes the most common way to build, deploy, and undeploy the quickstarts. See the README file in each individual quickstart folder for specific details and information on how to run and access the example. 5 | 6 | The commands in this document use the *replaceable* value `EAP7_HOME` to denote the path to the Red Hat JBoss Enterprise Application Platform 7 installation. When you encounter this value in a README file or guide, be sure to replace it with the actual path to your JBoss EAP 7 installation. The installation path is described in detail here: [Use of EAP7_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md#use-of-EAP7_HOME-and-jboss_home-variables). 7 | 8 | See [Configure Maven for JBoss EAP 7](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts) to make sure you are configured correctly for testing the quickstarts. 9 | 10 | * [Build the Quickstart Archive](#build-the-quickstart-archive) 11 | * [Build and Deploy the Quickstart Archive](#build-and-deploy-the-quickstart-archive) 12 | * [Undeploy the Quickstart Archive](#undeploy-the-quickstart-archive) 13 | * [Verify the Quickstarts Build with One Command](#verify-the-quickstarts-build-with-one-command) 14 | * [Undeploy All Deployed Quickstarts with One Command](#undeploy-all-deployed-quickstarts-with-one-command) 15 | 16 | 17 | ### Build the Quickstart Archive 18 | 19 | In most cases, you can use the following steps to build the application to test for compile errors or to view the contents of the archive. See the specific quickstart README file for complete details. 20 | 21 | 1. Open a command prompt and navigate to the root directory of the quickstart you want to build. 22 | 2. Use this command if you only want to build the archive, but not deploy it: 23 | 24 | mvn clean install 25 | 26 | ### Build and Deploy the Quickstart Archive 27 | 28 | In most cases, you can use the following steps to build and deploy the application. See the specific quickstart README file for complete details. 29 | 30 | 1. Make sure you start the JBoss EAP server as described in the quickstart README file. 31 | 2. Open a command prompt and navigate to the root directory of the quickstart you want to run. 32 | 3. Use this command to build and deploy the archive: 33 | 34 | mvn clean install wildfly:deploy 35 | 36 | ### Undeploy the Quickstart Archive 37 | 38 | The command to undeploy the quickstart is simply: 39 | 40 | mvn wildfly:undeploy 41 | 42 | 43 | ### Verify the Quickstarts Build with One Command 44 | 45 | 46 | You can verify the quickstarts build using one command. However, quickstarts that have complex dependencies must be skipped. For example, the _jax-rs-client_ quickstart is a RESTEasy client that depends on the deployment of the _helloworld-rs_ quickstart. As noted above, the root `pom.xml` file defines a `complex-dependencies` profile to exclude these quickstarts from the root build process. 47 | 48 | To build the quickstarts: 49 | 50 | 1. Do not start the JBoss EAP server. 51 | 2. Open a command prompt and navigate to the root directory of the quickstarts. 52 | 3. Use this command to build the quickstarts that do not have complex dependencies: 53 | 54 | mvn clean install '-Pdefault,!complex-dependencies' 55 | 56 | _Note_: If you see a `java.lang.OutOfMemoryError: PermGen space` error when you run this command, increase the memory by typing the following command for your operating system, then try the above command again. 57 | 58 | For Linux: export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" 59 | For Windows: SET MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" 60 | 61 | 62 | ### Undeploy All Deployed Quickstarts with One Command 63 | ------------------------------------------------------ 64 | 65 | To undeploy the quickstarts from the root of the quickstart folder, you must pass the argument `-fae` (fail at end) on the command line. This allows the command to continue past quickstarts that fail due to complex dependencies and quickstarts that only have Arquillian tests and do not deploy archives to the server. 66 | 67 | You can undeploy quickstarts using the following procedure: 68 | 69 | 1. Start the JBoss EAP server. 70 | 2. Open a command prompt and navigate to the root directory of the quickstarts. 71 | 3. Use this command to undeploy any deployed quickstarts: 72 | 73 | mvn wildfly:undeploy -fae 74 | 75 | To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart's README file. 76 | 77 | 78 | 79 | -------------------------------------------------------------------------------- /dist/css/pygments.css: -------------------------------------------------------------------------------- 1 | /* 2 | * JBoss, Home of Professional Open Source 3 | * Copyright 2014, Red Hat, Inc. and/or its affiliates, and individual 4 | * contributors by the @authors tag. See the copyright.txt in the 5 | * distribution for a full listing of individual contributors. 6 | * 7 | * Licensed under the Apache License, Version 2.0 (the "License"); 8 | * you may not use this file except in compliance with the License. 9 | * You may obtain a copy of the License at 10 | * http://www.apache.org/licenses/LICENSE-2.0 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | * See the License for the specific language governing permissions and 15 | * limitations under the License. 16 | */ 17 | .highlight { background: #ffffff; } 18 | .highlight .c { color: #999988; font-style: italic } /* Comment */ 19 | .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ 20 | .highlight .k { font-weight: bold } /* Keyword */ 21 | .highlight .o { font-weight: bold } /* Operator */ 22 | .highlight .cm { color: #999988; font-style: italic } /* Comment.Multiline */ 23 | .highlight .cp { color: #999999; font-weight: bold } /* Comment.Preproc */ 24 | .highlight .c1 { color: #999988; font-style: italic } /* Comment.Single */ 25 | .highlight .cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */ 26 | .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ 27 | .highlight .gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */ 28 | .highlight .ge { font-style: italic } /* Generic.Emph */ 29 | .highlight .gr { color: #aa0000 } /* Generic.Error */ 30 | .highlight .gh { color: #999999 } /* Generic.Heading */ 31 | .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ 32 | .highlight .gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */ 33 | .highlight .go { color: #888888 } /* Generic.Output */ 34 | .highlight .gp { color: #555555 } /* Generic.Prompt */ 35 | .highlight .gs { font-weight: bold } /* Generic.Strong */ 36 | .highlight .gu { color: #aaaaaa } /* Generic.Subheading */ 37 | .highlight .gt { color: #aa0000 } /* Generic.Traceback */ 38 | .highlight .kc { font-weight: bold } /* Keyword.Constant */ 39 | .highlight .kd { font-weight: bold } /* Keyword.Declaration */ 40 | .highlight .kp { font-weight: bold } /* Keyword.Pseudo */ 41 | .highlight .kr { font-weight: bold } /* Keyword.Reserved */ 42 | .highlight .kt { color: #445588; font-weight: bold } /* Keyword.Type */ 43 | .highlight .m { color: #009999 } /* Literal.Number */ 44 | .highlight .s { color: #d14 } /* Literal.String */ 45 | .highlight .na { color: #008080 } /* Name.Attribute */ 46 | .highlight .nb { color: #0086B3 } /* Name.Builtin */ 47 | .highlight .nc { color: #445588; font-weight: bold } /* Name.Class */ 48 | .highlight .no { color: #008080 } /* Name.Constant */ 49 | .highlight .ni { color: #800080 } /* Name.Entity */ 50 | .highlight .ne { color: #990000; font-weight: bold } /* Name.Exception */ 51 | .highlight .nf { color: #990000; font-weight: bold } /* Name.Function */ 52 | .highlight .nn { color: #555555 } /* Name.Namespace */ 53 | .highlight .nt { color: #000080 } /* Name.Tag */ 54 | .highlight .nv { color: #008080 } /* Name.Variable */ 55 | .highlight .ow { font-weight: bold } /* Operator.Word */ 56 | .highlight .w { color: #bbbbbb } /* Text.Whitespace */ 57 | .highlight .mf { color: #009999 } /* Literal.Number.Float */ 58 | .highlight .mh { color: #009999 } /* Literal.Number.Hex */ 59 | .highlight .mi { color: #009999 } /* Literal.Number.Integer */ 60 | .highlight .mo { color: #009999 } /* Literal.Number.Oct */ 61 | .highlight .sb { color: #d14 } /* Literal.String.Backtick */ 62 | .highlight .sc { color: #d14 } /* Literal.String.Char */ 63 | .highlight .sd { color: #d14 } /* Literal.String.Doc */ 64 | .highlight .s2 { color: #d14 } /* Literal.String.Double */ 65 | .highlight .se { color: #d14 } /* Literal.String.Escape */ 66 | .highlight .sh { color: #d14 } /* Literal.String.Heredoc */ 67 | .highlight .si { color: #d14 } /* Literal.String.Interpol */ 68 | .highlight .sx { color: #d14 } /* Literal.String.Other */ 69 | .highlight .sr { color: #009926 } /* Literal.String.Regex */ 70 | .highlight .s1 { color: #d14 } /* Literal.String.Single */ 71 | .highlight .ss { color: #990073 } /* Literal.String.Symbol */ 72 | .highlight .bp { color: #999999 } /* Name.Builtin.Pseudo */ 73 | .highlight .vc { color: #008080 } /* Name.Variable.Class */ 74 | .highlight .vg { color: #008080 } /* Name.Variable.Global */ 75 | .highlight .vi { color: #008080 } /* Name.Variable.Instance */ 76 | .highlight .il { color: #009999 } /* Literal.Number.Integer.Long */ 77 | -------------------------------------------------------------------------------- /guides/BUILD_AND_DEPLOY_JBOSS_EAP.adoc: -------------------------------------------------------------------------------- 1 | [[build_and_deploy_the_quickstarts_to_jboss_eap]] 2 | 3 | = Build and Deploy the Quickstarts to JBoss EAP 4 | 5 | This document describes the basic steps to build, deploy, and undeploy the quickstarts. See the `README` file in each individual quickstart folder for specific details and information on how to run and access the example. 6 | 7 | The commands in this document use the *replaceable* value `__EAP_HOME__` to denote the path to the Red Hat JBoss Enterprise Application Platform 7 installation. When you encounter this value in a README file or guide, be sure to replace it with the actual path to your JBoss EAP installation. See link:USE_OF_EAP_HOME.adoc#use_of_product_home_and_jboss_home_variables[Use of EAP_HOME and JBOSS_HOME Variables] for more information about the installation path. 8 | 9 | See link:CONFIGURE_MAVEN_JBOSS_EAP.adoc#configure_maven_to_build_and_deploy_the_quickstarts[Configure Maven for JBoss EAP] to make sure you are configured correctly for testing the quickstarts. 10 | 11 | * xref:build_the_quickstart_archive[Build the Quickstart Archive] 12 | * xref:build_and_deploy_the_quickstart_archive[Build and Deploy the Quickstart Archive] 13 | * xref:undeploy_the_quickstart_archive[Undeploy the Quickstart Archive] 14 | * xref:verify_the_quickstarts_build_with_one_command[Verify the Quickstarts Build with One Command] 15 | * xref:undeploy_all_deployed_quickstarts_with_one_command[Undeploy All Deployed Quickstarts with One Command] 16 | 17 | [[build_the_quickstart_archive]] 18 | == Build the Quickstart Archive 19 | 20 | In most cases, you can use the following steps to build the application to test for compile errors or to view the contents of the archive. See the specific quickstart `README` file for complete details. 21 | 22 | . Open a terminal and navigate to the root directory of the quickstart you want to build. 23 | . Use this command if you only want to build the archive, but not deploy it: 24 | + 25 | [source,options="nowrap"] 26 | ---- 27 | $ mvn clean install 28 | ---- 29 | 30 | [[build_and_deploy_the_quickstart_archive]] 31 | == Build and Deploy the Quickstart Archive 32 | 33 | In most cases, you can use the following steps to build and deploy the application. See the specific quickstart `README` file for complete details. 34 | 35 | . Make sure you start the JBoss EAP server as described in the quickstart README file. 36 | . Open a terminal and navigate to the root directory of the quickstart you want to run. 37 | . Use the following command to build and deploy the archive. 38 | + 39 | [source,options="nowrap"] 40 | ---- 41 | $ mvn clean install wildfly:deploy 42 | ---- 43 | 44 | [[undeploy_the_quickstart_archive]] 45 | == Undeploy the Quickstart Archive 46 | 47 | Use the following command to undeploy the quickstart. 48 | 49 | [source,options="nowrap"] 50 | ---- 51 | $ mvn wildfly:undeploy 52 | ---- 53 | 54 | [[verify_the_quickstarts_build_with_one_command]] 55 | == Verify the Quickstarts Build with One Command 56 | 57 | You can verify the quickstarts build using one command. However, quickstarts that have complex dependencies must be skipped. For example, the `jax-rs-client` quickstart is a RESTEasy client that depends on the deployment of the `helloworld-rs` quickstart. The `pom.xml` file in the root directory of the quickstarts defines a `complex-dependencies` profile to exclude these quickstarts from the root build process. For more information, see link:CONFIGURE_MAVEN_JBOSS_EAP.adoc#use_of_maven_profiles_in_pom_files[Use of Maven Profiles in POM Files]. 58 | 59 | To build the quickstarts: 60 | 61 | . Do not start the JBoss EAP server. 62 | . Open a terminal and navigate to the root directory of the quickstarts. 63 | . Use this command to build the quickstarts that do not have complex dependencies: 64 | + 65 | [source,options="nowrap"] 66 | ---- 67 | $ mvn clean install '-Pdefault,!complex-dependencies' 68 | ---- 69 | 70 | [NOTE] 71 | ==== 72 | If you see a `java.lang.OutOfMemoryError: PermGen space` error when you run this command, increase the memory by typing the following command for your operating system, then try the above command again. 73 | [source,options="nowrap"] 74 | ---- 75 | For Linux: export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" 76 | For Windows: SET MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" 77 | ---- 78 | ==== 79 | 80 | [[undeploy_all_deployed_quickstarts_with_one_command]] 81 | == Undeploy All Deployed Quickstarts with One Command 82 | 83 | To undeploy the quickstarts from the root of the quickstart folder, you must pass the argument `-fae` (fail at end) on the command line. This allows the command to continue past quickstarts that fail due to complex dependencies and quickstarts that only have Arquillian tests and do not deploy archives to the server. 84 | 85 | You can undeploy quickstarts using the following procedure: 86 | 87 | . Start the JBoss EAP server. 88 | . Open a terminal and navigate to the root directory of the quickstarts. 89 | . Use this command to undeploy any deployed quickstarts: 90 | + 91 | [source,options="nowrap"] 92 | ---- 93 | $ mvn wildfly:undeploy -fae 94 | ---- 95 | 96 | To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart's `README` file. 97 | -------------------------------------------------------------------------------- /guides/CONFIGURE_BYTEMAN.adoc: -------------------------------------------------------------------------------- 1 | [[configure_byteman_for_use_with_the_quickstarts]] 2 | 3 | = Configure Byteman for Use with the Quickstarts 4 | 5 | [[configure_byteman_for_use_with_the_quickstarts_summary]] 6 | == Summary 7 | 8 | _Byteman_ is a tool that simplifies tracing and testing of Java programs. It allows you to insert extra Java code into your application, either as it is loaded during JVM startup or after it has already started running. This code can be used to trace what the application is doing and to monitor and debug deployments to be sure it is operating correctly. You can also use _Byteman_ to inject faults or synchronization code when testing your application. 9 | 10 | A few of the quickstarts use _Byteman_ to demonstrate distributed transaction processing and crash recovery, for example, to halt an application server in the middle of a distributed transaction to demonstrate crash recovery. 11 | 12 | The following sections describe the steps necessary to install, configure, and use _Byteman_ with these quickstarts. 13 | 14 | * xref:download_and_configure_byteman[Download and Configure Byteman] 15 | * xref:clear_the_transaction_objectstore[Clear the Transaction ObjectStore] 16 | * xref:use_byteman_to_halt_the_application[Use Byteman to Halt the Application] 17 | * xref:disable_the_byteman_script[Disable the Byteman Script] 18 | 19 | NOTE: See link:USE_OF_EAP_HOME.adoc[Use of EAP_HOME and JBOSS_HOME Variables] for information about the Red Hat JBoss Enterprise Application Platform installation path. 20 | 21 | [[download_and_configure_byteman]] 22 | == Download and Configure Byteman 23 | 24 | 25 | . Download _Byteman_ from http://www.jboss.org/byteman/downloads/. 26 | . Extract the ZIP file to a directory of your choice. In the instructions below, we refer to this directory as `__BYTEMAN_HOME__`. 27 | . By default, the _Byteman_ download provides unrestricted permissions to `others` which can cause a problem when running Ruby commands for the OpenShift quickstarts. To restrict the permissions to `others`, open a terminal and type the following: 28 | + 29 | [source,subs="+quotes",options="nowrap"] 30 | ---- 31 | $ chmod -R o-rwx __BYTEMAN_HOME__/ 32 | ---- 33 | 34 | [[clear_the_transaction_objectstore]] 35 | == Clear the Transaction ObjectStore 36 | 37 | Transaction objectstore data remaining from previous tests can prevent _Byteman_ from working properly. You must remove any remaining data before running new _Byteman_ tests. If you are using the default file based transaction logging store: 38 | 39 | . Open a terminal and type the following: 40 | + 41 | [source,subs="+quotes",options="nowrap"] 42 | ---- 43 | $ ls __EAP_HOME__/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/ 44 | ---- 45 | 46 | . If this directory exists and contains any files, delete them before starting the server: 47 | + 48 | [source,subs="+quotes",options="nowrap"] 49 | ---- 50 | $ rm -rf __EAP_HOME__/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/* 51 | ---- 52 | . On Windows, use the file manager to accomplish the same result. 53 | 54 | [[use_byteman_to_halt_the_application]] 55 | == Use Byteman to Halt the Application 56 | 57 | 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 JBoss EAP server before making the following changes. Otherwise _Byteman_ will not halt the server. 58 | 59 | When instructed to use _Byteman_ to halt the application, perform the following steps: 60 | 61 | . Find the appropriate configuration file for your operating system in the list below. 62 | 63 | * For Linux: `__EAP_HOME__/bin/standalone.conf` 64 | * For Windows: `__EAP_HOME__\bin\standalone.conf.bat` 65 | 66 | [[important_make_a_backup_copy]] 67 | 68 | . **Important**: Make a backup copy of this configuration file before making any modifications! 69 | . Open the configuration file and append the text specified in the quickstart `README` file instructions to the end of the configuration file. Be sure to replace the `__BYTEMAN_HOME__` with the path to the Byteman download and the `__QUICKSTART_HOME__` with the path to the quickstarts. 70 | + 71 | The following is an example of of the configuration changes needed for the _jta-crash-rec_ quickstart. 72 | 73 | * For Linux: 74 | + 75 | [source,subs="+quotes",options="nowrap"] 76 | ---- 77 | JAVA_OPTS="-javaagent:/__BYTEMAN_HOME__/lib/byteman.jar=script:/__QUICKSTART_HOME__/jta-crash-rec/src/main/scripts/xa.btm ${JAVA_OPTS}" 78 | ---- 79 | * For Windows: 80 | + 81 | [source,subs="+quotes",options="nowrap"] 82 | ---- 83 | SET "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%" 84 | ---- 85 | 86 | [[disable_the_byteman_script]] 87 | == Disable the Byteman Script 88 | 89 | When you have completed testing the quickstart, replace the server configuration file with the xref:important_make_a_backup_copy[backup copy] you created above to disable _Byteman_. 90 | 91 | xref:configure_byteman_for_use_with_the_quickstarts[Back to top] 92 | -------------------------------------------------------------------------------- /guides/BUILD_AND_DEPLOY.md: -------------------------------------------------------------------------------- 1 | Build and Deploy the Quickstarts 2 | ===================== 3 | 4 | This document describes the most common way to build, deploy, and undeploy the quickstarts. See the README file in each individual quickstart folder for specific details and information on how to run and access the example. 5 | 6 | The commands in this document use the *replaceable* value `EAP_HOME` to denote the path to the Red Hat JBoss Enterprise Application Platform 6 installation. When you encounter this value in a README file or guide, be sure to replace it with the actual path to your JBoss EAP 6 installation. The installation path is described in detail here: [Use of EAP_HOME and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP_HOME.md#use-of-eap_home-and-jboss_home-variables). 7 | 8 | _Note:_ If you do not configure the Maven settings as described here, [Configure Maven](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN.md#configure-maven-to-build-and-deploy-the-quickstarts), you must pass the configuration setting on every Maven command as follows: ` -s QUICKSTART_HOME/settings.xml` 9 | 10 | * [Build the Quickstart Archive](#build-the-quickstart-archive) 11 | * [Build and Deploy the Quickstart Archive](#build-and-deploy-the-quickstart-archive) 12 | * [Undeploy the Quickstart Archive](#undeploy-the-quickstart-archive) 13 | * [Verify the Quickstarts Build with One Command](#verify-the-quickstarts-build-with-one-command) 14 | * [Undeploy All Deployed Quickstarts with One Command](#undeploy-all-deployed-quickstarts-with-one-command) 15 | 16 | 17 | ### Build the Quickstart Archive 18 | 19 | In most cases, you can use the following steps to build the application to test for compile errors or to view the contents of the archive. See the specific quickstart README file for complete details. 20 | 21 | 1. Open a command prompt and navigate to the root directory of the quickstart you want to build. 22 | 2. Use this command if you only want to build the archive, but not deploy it: 23 | * If you have configured the Maven settings : 24 | 25 | mvn clean install 26 | * If you have NOT configured settings Maven settings: 27 | 28 | mvn clean install -s QUICKSTART_HOME/settings.xml 29 | 30 | ### Build and Deploy the Quickstart Archive 31 | 32 | In most cases, you can use the following steps to build and deploy the application. See the specific quickstart README file for complete details. 33 | 34 | 1. Make sure you start the JBoss EAP server as described in the quickstart README file. 35 | 2. Open a command prompt and navigate to the root directory of the quickstart you want to run. 36 | 3. Use this command to build and deploy the archive: 37 | 38 | * If you have configured the Maven settings : 39 | 40 | mvn clean install jboss-as:deploy 41 | * If you have NOT configured the Maven settings : 42 | 43 | mvn clean install jboss-as:deploy -s QUICKSTART_HOME/settings.xml 44 | 45 | ### Undeploy the Quickstart Archive 46 | 47 | The command to undeploy the quickstart is simply: 48 | 49 | mvn jboss-as:undeploy 50 | 51 | 52 | ### Verify the Quickstarts Build with One Command 53 | 54 | 55 | You can verify the quickstarts build using one command. However, quickstarts that have complex dependencies must be skipped. For example, the _jax-rs-client_ quickstart is a RESTEasy client that depends on the deployment of the _helloworld-rs_ quickstart. As noted above, the root `pom.xml` file defines a `complex-dependencies` profile to exclude these quickstarts from the root build process. 56 | 57 | To build the quickstarts: 58 | 59 | 1. Do not start the JBoss EAP server. 60 | 2. Open a command prompt and navigate to the root directory of the quickstarts. 61 | 3. Use this command to build the quickstarts that do not have complex dependencies: 62 | 63 | * If you have configured the Maven settings : 64 | 65 | mvn clean install '-Pdefault,!complex-dependencies' 66 | 67 | * If you have NOT configured the Maven settings : 68 | 69 | mvn clean install '-Pdefault,!complex-dependencies' -s QUICKSTART_HOME/settings.xml 70 | 71 | _Note_: If you see a `java.lang.OutOfMemoryError: PermGen space` error when you run this command, increase the memory by typing the following command for your operating system, then try the above command again. 72 | 73 | For Linux: export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" 74 | For Windows: SET MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" 75 | 76 | 77 | ### Undeploy All Deployed Quickstarts with One Command 78 | ------------------------------------------------------ 79 | 80 | To undeploy the quickstarts from the root of the quickstart folder, you must pass the argument `-fae` (fail at end) on the command line. This allows the command to continue past quickstarts that fail due to complex dependencies and quickstarts that only have Arquillian tests and do not deploy archives to the server. 81 | 82 | You can undeploy quickstarts using the following procedure: 83 | 84 | 1. Start the JBoss EAP server. 85 | 2. Open a command prompt and navigate to the root directory of the quickstarts. 86 | 3. Use this command to undeploy any deployed quickstarts: 87 | 88 | mvn jboss-as:undeploy -fae 89 | 90 | To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart's README file. 91 | 92 | 93 | 94 | -------------------------------------------------------------------------------- /guides/RUN_ARQUILLIAN_TESTS.adoc: -------------------------------------------------------------------------------- 1 | [[run_the_arquillian_tests]] 2 | 3 | = Run the Arquillian Tests 4 | 5 | 6 | Arquillian is a testing platform that makes it easy to create automated integration, functional, and acceptance tests for your project. Some quickstarts provide Arquillian tests to demonstrate how write tests for your project using Red Hat JBoss Enterprise Application Platform. Because Arquillian tests an application on a real server, these tests are configured to be skipped by default. 7 | 8 | There are two ways you can run Arquillian tests: 9 | 10 | * xref:test_the_quickstart_on_a_remote_jboss_eap_server[Test the Quickstart on a Remote JBoss EAP Server]: You must start the server yourself and run the tests against a remote server. 11 | * xref:test_the_quickstart_on_a_managed_jboss_eap_server[Test the Quickstart on a Managed JBoss EAP Server]: You must not start the server and instead let Arquillian manage the server lifecycle during the testing. 12 | 13 | The individual quickstart `README` file should tell you what to expect in the console output and the server log when you run the tests. 14 | 15 | NOTE: The JBoss EAP 7 quickstarts include the repository in the project POM files and do not require you to configure your Maven settings. 16 | 17 | [[test_the_quickstart_on_a_remote_jboss_eap_server]] 18 | == Test the Quickstart on a Remote JBoss EAP Server 19 | 20 | Arquillian's remote container adapter expects a JBoss EAP server instance to be already started prior to the test execution. 21 | 22 | . You must start the JBoss EAP server as described in the quickstart `README` file. 23 | 24 | . If you run the tests against a JBoss EAP server running on a machine other than `localhost`, you must configure the following properties in the `src/test/resources/arquillian.xml` file: 25 | + 26 | [source,xml,options="nowrap"] 27 | ---- 28 | 29 | 30 | myhost.example.com 31 | 9999 32 | customAdminUser 33 | myPassword 34 | 35 | 36 | ---- 37 | 38 | . Run the `test` goal with the correct profile activated. 39 | 40 | * For JBoss EAP 6.x, this is the `arq-jbossas-remote` profile, so you type the following command: 41 | + 42 | [source,options="nowrap"] 43 | ---- 44 | $ mvn clean test -Parq-jbossas-remote 45 | ---- 46 | * For JBoss EAP 7.0, this is the `arq-wildfly-remote` profile, so you type the following command: 47 | + 48 | [source,options="nowrap"] 49 | ---- 50 | $ mvn clean test -Parq-wildfly-remote 51 | ---- 52 | * For JBoss EAP 7.3, this is the `arq-remote` profile, so you type the following command: 53 | + 54 | [source,options="nowrap"] 55 | ---- 56 | $ mvn clean verify -Parq-remote 57 | ---- 58 | 59 | NOTE: See the individual quickstart `README` files for any additional requirements. 60 | 61 | [[test_the_quickstart_on_a_managed_jboss_eap_server]] 62 | == Test the Quickstart on a Managed JBoss EAP Server 63 | 64 | Arquillian's managed container adapter starts the container for you and requires that your JBoss EAP server is not running. 65 | 66 | . You must first let Arquillian know where to find the JBoss EAP server directory. 67 | 68 | * The simplest approach is to set the `__JBOSS_HOME__` environment variable to the full path to your JBoss EAP server directory, for example: 69 | + 70 | [source,options="nowrap"] 71 | ---- 72 | $ export JBOSS_HOME=/home/myusername/EAP/jboss-eap-x.x/ 73 | ---- 74 | * Alternatively, you can set the path in the `jbossHome` property in the quickstarts's Arquillian configuration file as follows. 75 | 76 | .. Open the `src/test/resources/arquillian.xml` file located in the quickstart directory. 77 | .. Find the configuration for the JBoss container. It should look like this: 78 | + 79 | [source,xml,options="nowrap"] 80 | ---- 81 | 82 | 83 | 86 | 89 | 90 | ---- 91 | .. Uncomment the `configuration` element, find the `jbossHome` property, and replace the "EAP_HOME" value with the actual path to your JBoss EAP server. For example: 92 | + 93 | [source,xml,options="nowrap"] 94 | ---- 95 | 96 | 97 | 98 | property name="jbossHome">/home/myusername/EAP/jboss-eap-x.x/ 99 | 100 | 101 | ---- 102 | 103 | . Run the `test` goal with the correct profile activated. 104 | 105 | * For JBoss EAP 6.x, this is the `arq-jbossas-managed` profile, so you type the following command: 106 | + 107 | [source,options="nowrap"] 108 | ---- 109 | $ mvn clean test -Parq-jbossas-managed 110 | ---- 111 | * For JBoss EAP 7.0, this is the `arq-wildfly-managed` profile, so you type the following command: 112 | + 113 | [source,options="nowrap"] 114 | ---- 115 | $ mvn clean test -Parq-wildfly-managed 116 | ---- 117 | * For JBoss EAP 7.3, this is the `arq-managed` profile, so you type the following command: 118 | + 119 | [source,options="nowrap"] 120 | ---- 121 | $ mvn clean verify -Parq-managed 122 | ---- 123 | 124 | NOTE: See the individual quickstart `README` files for any additional requirements. 125 | -------------------------------------------------------------------------------- /guides/RUN_ARQUILLIAN_TESTS.md: -------------------------------------------------------------------------------- 1 | Run the Arquillian Tests 2 | ======================== 3 | 4 | Arquillian is a testing platform that makes it easy to create automated integration, functional, and acceptance tests for your project. Some quickstarts provide Arquillian tests to demonstrate how write tests for your project. Because Arquillian tests an application on a real server, these tests are configured to be skipped by default. 5 | 6 | There are two ways you can run Arquillian tests: 7 | 8 | * [Test the Quickstart on a Remote Red Hat JBoss Enterprise Application Platform Server](#test-the-quickstart-on-a-remote-jboss-eap-server): You must start the server yourself and run the tests against a remote server. 9 | * [Test the Quickstart on a Managed Red Hat JBoss Enterprise Application Platform Server](#test-the-quickstart-on-a-managed-jboss-eap-server): You must not start the server and instead let Arquillian manage the server lifecycle during the testing. 10 | 11 | The individual quickstart README should tell you what to expect in the console output and the server log when you run the tests. 12 | 13 | _Note:_ 14 | 15 | * _For the JBoss EAP 6.x quickstarts, if you do not configure your Maven settings as described here, [Configure Maven](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN.md#configure-maven-to-build-and-deploy-the-quickstarts), you must pass the configuration settings file on every Maven command as follows: ` -s QUICKSTART_HOME/settings.xml`._ 16 | * _The JBoss EAP 7 quickstarts include the repository in the project POM files and do not require you to configure your Maven settings._ 17 | 18 | 19 | Test the Quickstart on a Remote Red Hat JBoss Enterprise Application Platform Server 20 | ------------------------------------- 21 | 22 | Arquillian's remote container adapter expects a Red Hat JBoss Enterprise Application Platform server instance to be already started prior to the test execution. 23 | 24 | 1. You must start the JBoss EAP server as described in the quickstart README file. 25 | 26 | 2. If you run the tests against a JBoss EAP server running on a machine other than `localhost`, you must configure the following properties in the `src/test/resources/arquillian.xml` file: 27 | 28 | 29 | 30 | myhost.example.com 31 | 9999 32 | customAdminUser 33 | myPassword 34 | 35 | 36 | 37 | 3. Run the test goal with the correct profile activated. 38 | 39 | * For JBoss EAP 6.x, this is the `arq-jbossas-remote` profile, so you type the following command: 40 | 41 | mvn clean test -Parq-jbossas-remote 42 | 43 | * For JBoss EAP 7.0, this is the `arq-wildfly-remote` profile, so you type the following command: 44 | 45 | mvn clean test -Parq-wildfly-remote 46 | 47 | * For JBoss EAP 7.1, this is the `arq-remote` profile, so you type the following command: 48 | 49 | mvn clean verify -Parq-remote 50 | 51 | 52 | _Note:_ See the individual quickstart README file for any additional requirements. 53 | 54 | Test the Quickstart on a Managed Red Hat JBoss Enterprise Application Platform Server 55 | --------------------------------------- 56 | 57 | Arquillian's managed container adapter starts the container for you and requires that your JBoss EAP server is not running. 58 | 59 | 1. You must first let Arquillian know where to find the JBoss EAP server directory. 60 | 61 | The simplest approach is to set the `JBOSS_HOME` environment variable to the full path to your JBoss EAP server directory. 62 | 63 | Alternatively, you can set the path in the `jbossHome` property in the Arquillian configuration file as follows. 64 | 65 | * Open the `src/test/resources/arquillian.xml` file located in the quickstart directory. 66 | * Find the configuration for the JBoss container. It should look like this: 67 | 68 | 69 | 70 | 73 | 76 | 77 | 78 | * Uncomment the `configuration` element, find the `jbossHome` property, and replace the "EAP_HOME" value with the actual path to your JBoss EAP server. For example: 79 | 80 | 81 | 82 | 83 | property name="jbossHome">/home/myusername/EAP/jboss-eap-x.x/ 84 | 85 | 86 | 87 | 88 | 2. Run the test goal with the correct profile activated. 89 | 90 | * For JBoss EAP 6.x, this is the `arq-jbossas-managed` profile, so you type the following command: 91 | 92 | mvn clean test -Parq-jbossas-managed 93 | 94 | * For JBoss EAP 7.0, this is the `arq-wildfly-managed` profile, so you type the following command: 95 | 96 | mvn clean test -Parq-wildfly-managed 97 | 98 | * For JBoss EAP 7.1, this is the `arq-managed` profile, so you type the following command: 99 | 100 | mvn clean verify -Parq-managed 101 | 102 | _Note:_ See the individual quickstart README file for any additional requirements. 103 | -------------------------------------------------------------------------------- /guides/CREATE_USERS.md: -------------------------------------------------------------------------------- 1 | Create Users Required by the Quickstarts 2 | =============== 3 | 4 | Summary: By default, Red Hat JBoss Enterprise Application Platform is distributed with security enabled for the management interfaces. A few of the quickstarts use these management interfaces and require that you create a management or application user to access the running application. An `add-user` script is provided in the `EAP_HOME/bin` directory for that purpose. You can run the script interactively or you can pass arguments on the command line. 5 | 6 | The following procedures describe how to add a user with the appropriate permissions to run the quickstarts that depend on them. 7 | 8 | * [Add a Management User](#add-a-management-user) 9 | * [Add an Application User](#add-an-application-user) 10 | 11 | _Note:_ Passwords must meet the following requirements: 12 | 13 | * It can not be the same as the user name. 14 | * It must contain at least 8 characters. 15 | * It must contain at least one alphanumeric character. 16 | * It must contain at least one digit. 17 | * It must contain at least one non-alphanumeric symbol. 18 | 19 | Foe more information about how to configure users, see the [Product Documentation](https://access.redhat.com/documentation/en/jboss-enterprise-application-platform/) for Red Hat JBoss Enterprise Application Platform. 20 | 21 | _NOTE: See [Use of EAP_HOME](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP_HOME.md#use-of-eap_home-and-jboss_home-variables "Use Of EAP_HOME") for information about the JBoss EAP installation path._ 22 | 23 | Add a Management User 24 | ---------------------- 25 | 26 | You can pass arguments on the command line or you can run the script interactively. The examples below use "admin" for the `Username` and "adminPass1!" for the `Password`. If the quickstart requires a specific `Username` and `Password`, be sure to replace them in the examples below. 27 | 28 | ### Add a Management User Passing Arguments on the Command Line 29 | 30 | You can create the management user non-interactively by passing each argument on the command line. 31 | 32 | For example, to add the Management User `admin` in the default `ManagementRealm` realm with password `adminPass1!`, 33 | open a command prompt and type the following: 34 | 35 | For Linux: EAP_HOME/bin/add-user.sh -u 'admin' -p 'adminPass1!' 36 | For Windows: EAP_HOME\bin\add-user.bat -u 'admin' -p 'adminPass1!' 37 | 38 | ### Add a Management User Interactively 39 | 40 | If you prefer, you can create the management user interactively. 41 | 42 | 1. Open a command prompt. 43 | 2. Type the command for your operating system 44 | 45 | For Linux: EAP_HOME/bin/add-user.sh 46 | For Windows: EAP_HOME\bin\add-user.bat 47 | 3. You should see the following response: 48 | 49 | What type of user do you wish to add? 50 | 51 | a) Management User (mgmt-users.properties) 52 | b) Application User (application-users.properties) 53 | (a): 54 | 55 | At the prompt, press enter to use the default Management User. 56 | 4. You should see the following response: 57 | 58 | Enter the details of the new user to add. 59 | Using realm 'ManagementRealm' as discovered from the existing property files. 60 | Username : 61 | 5. Enter the Username and, at the next prompt, enter the Password. 62 | 63 | Username : admin 64 | Password : (choose a password for the admin user) 65 | Repeat the password. 66 | 6. At the next prompt, you will be asked "What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]: ". Leave it blank and press enter. 67 | 7. Choose yes for the remaining prompts. 68 | 69 | Add an Application User 70 | ----------------------- 71 | 72 | You can pass arguments on the command line or you can run the script interactively. The examples below use "quickstartUser" for the `Username`, "quickstartPwd1!" for the `Password`, and "guest" for the group. If the quickstart requires a specific `Username`, `Password`, or `group`, be sure to replace them in the examples below. 73 | 74 | ### Add an Application User Passing Arguments on the Command Line 75 | 76 | You can create the application user non-interactively by passing each argument on the command line. 77 | 78 | The default application user for the quickstarts is `quickstartUser`, in the `ApplicationRealm` realm, with password `quickstartPwd1!`, and belonging to group `guest`. 79 | To add the default application user, open a command prompt and type the following: 80 | 81 | For Linux: EAP_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' 82 | For Windows: EAP_HOME\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' 83 | 84 | 85 | ##### Add an Application User Interactively 86 | 87 | If you prefer, you can create the application user interactively. 88 | 89 | 1. Open a command prompt. 90 | 2. Type the command for your operating system 91 | 92 | For Linux: EAP_HOME/bin/add-user.sh 93 | For Windows: EAP_HOME\bin\add-user.bat 94 | 3. You should see the following response: 95 | 96 | What type of user do you wish to add? 97 | 98 | a) Management User (mgmt-users.properties) 99 | b) Application User (application-users.properties) 100 | (a): 101 | 102 | At the prompt, type: `b` 103 | 4. You should see the following response: 104 | 105 | Enter the details of the new user to add. 106 | Using realm 'ApplicationRealm' as discovered from the existing property files. 107 | Username : 108 | 109 | 5. Enter the the Username and at the next prompt, enter the Password. If the quickstart README specifies a Username and Password, enter them here. Otherwise, use the default Username `quickstartUser` and Password `quickstartPwd1!`. 110 | 111 | Username : quickstartUser 112 | Password : quickstartPwd1! 113 | 6. At the next prompt, you will be asked "What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]: ". If the quickstart README specifies the groups to use, enter that here. Otherwise, type the group: `guest` 114 | 115 | [Back to top](#create-users-required-by-the-quickstarts) 116 | 117 | -------------------------------------------------------------------------------- /dist/github-flavored-markdown.rb: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env ruby 2 | # 3 | # JBoss, Home of Professional Open Source 4 | # Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual 5 | # contributors by the @authors tag. See the copyright.txt in the 6 | # distribution for a full listing of individual contributors. 7 | # 8 | # Licensed under the Apache License, Version 2.0 (the "License"); 9 | # you may not use this file except in compliance with the License. 10 | # You may obtain a copy of the License at 11 | # http://www.apache.org/licenses/LICENSE-2.0 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | # 18 | 19 | 20 | require 'rubygems' 21 | require 'redcarpet' 22 | require 'nokogiri' 23 | require 'fileutils' 24 | require 'pygments.rb' 25 | require 'rexml/document' 26 | 27 | # create a custom renderer that allows highlighting of code blocks 28 | class HTMLWithPygmentsAndPants < Redcarpet::Render::HTML 29 | include Redcarpet::Render::SmartyPants 30 | def block_code(code, language) 31 | Pygments.highlight(code, :lexer => language, :options => {:encoding => 'utf-8'}) 32 | end 33 | 34 | #method copied from: https://gist.github.com/suan/5692767 35 | def header(title, level) 36 | @headers ||= [] 37 | 38 | title_elements = REXML::Document.new(title) 39 | flattened_title = title_elements.inject('') do |flattened, element| 40 | flattened += if element.respond_to?(:text) 41 | element.text 42 | else 43 | element.to_s 44 | end 45 | end 46 | permalink = flattened_title.downcase.gsub(/[^a-z0-9\s]/, '').gsub(/\W+/, "-") 47 | 48 | # for extra credit: implement this as its own method 49 | if @headers.include?(permalink) 50 | permalink += "_1" 51 | # my brain hurts 52 | loop do 53 | break if !@headers.include?(permalink) 54 | # generate titles like foo-bar_1, foo-bar_2 55 | permalink.gsub!(/\_(\d+)$/, "_#{$1.to_i + 1}") 56 | end 57 | end 58 | @headers << permalink 59 | %(\n#{title}\n) 60 | end 61 | end 62 | 63 | 64 | def find(p, tag) 65 | if p.text 66 | r = p.text[/^(#{tag}: )(.+)$/, 2] 67 | if r 68 | p['id'] = 'metadata' 69 | return r 70 | end 71 | end 72 | end 73 | 74 | def find_split(p, tag) 75 | s = find(p, tag) 76 | if s 77 | return s.split(',').sort 78 | end 79 | end 80 | 81 | def metadata(source_path, html) 82 | # TODO canonicalise path 83 | toc_file='dist/target/toc.html' 84 | # Markdown doesn't have an metadata syntax, so all we can do is pray ;-) 85 | # Look for a paragraph that contains tags, which we define by convention 86 | page_content = Nokogiri::HTML(html) 87 | technologies = [] 88 | level = "" 89 | prerequisites = [] 90 | summary = "" 91 | page_content.css('p').each do |p| 92 | t = find_split(p, 'Technologies') 93 | if t 94 | technologies = t 95 | end 96 | l = find(p, 'Level') 97 | if l 98 | level = l 99 | end 100 | pr = find_split(p, 'Prerequisites') 101 | if pr 102 | prerequisites = pr 103 | end 104 | s = find(p, 'Summary') 105 | if s 106 | summary = s 107 | end 108 | 109 | end 110 | dir = source_path[/([^\/]+)\/([^\/]+).md$/, 1] 111 | filename = source_path[/([^\/]+)\/([^\/]+).md$/, 2] 112 | if dir 113 | output = "#{dir}#{' '.concat(technologies.map{|u| u} * ', ')}#{summary}#{level}#{' '.concat(prerequisites.map{|u| u} * ', ')}\n" 114 | FileUtils.mkdir_p(File.dirname(toc_file)) 115 | File.open(toc_file, 'a').write(output) 116 | end 117 | end 118 | 119 | def markdown(source_path) 120 | renderer = HTMLWithPygmentsAndPants.new(optionize [ 121 | :with_toc_data, 122 | :xhtml 123 | ]) 124 | markdown = Redcarpet::Markdown.new(renderer, optionize([ 125 | :fenced_code_blocks, 126 | :no_intra_emphasis, 127 | :tables, 128 | :autolink, 129 | :strikethrough, 130 | :space_after_headers, 131 | :with_toc_data 132 | ])) 133 | text = source_path.read 134 | toc_file='dist/target/toc.html' 135 | if File.exist?(toc_file) 136 | qs_toc_content=File.open('dist/target/toc.html').read 137 | qs_toc = "#{qs_toc_content}
Quickstart NameDemonstrated TechnologiesDescriptionExperience Level RequiredPrerequisites
" 138 | text.gsub!("\[TOC-quickstart\]", qs_toc) 139 | end 140 | toc = Redcarpet::Markdown.new(Redcarpet::Render::HTML_TOC).render(text) 141 | text.gsub!("\[TOC\]", toc) 142 | rendered = markdown.render(text) 143 | metadata(source_path.path, rendered) 144 | rendered = rendered.gsub(/README.md/, "README.html").gsub(/CONFIGURE_BYTEMAN.md/, "CONFIGURE_BYTEMAN.html").gsub(/CONFIGURE_MAVEN.md/, "CONFIGURE_MAVEN.html").gsub(/CONFIGURE_POSTGRESQL.md/, "CONFIGURE_POSTGRESQL.html").gsub(/CONTRIBUTING.md/, "CONTRIBUTING.html").gsub(/CREATE_USERS.md/, "CREATE_USERS.html").gsub(/DEPLOY_TO_OPENSHIFT.md/, "DEPLOY_TO_OPENSHIFT.html").gsub(/RUN_ARQUILLIAN_TESTS.md/, "RUN_ARQUILLIAN_TESTS.html").gsub(/START_JBOSS_EAP.md/, "START_JBOSS_EAP.html").gsub(/USE_JBDS.md/, "USE_JBDS.html").gsub(/USE_JDBS.md/, "USE_JDBS.html") 145 | 'README' + rendered + '' 146 | end 147 | 148 | def optionize(options) 149 | options.each_with_object({}) { |option, memo| memo[option] = true } 150 | end 151 | 152 | puts markdown(ARGF) 153 | 154 | -------------------------------------------------------------------------------- /guides/DEPLOY_TO_OPENSHIFT.md: -------------------------------------------------------------------------------- 1 | Build and Deploy a Quickstart - to OpenShift 2 | ===================== 3 | 4 | This guide contains the basic instructions to build and deploy a quickstart to OpenShift. 5 | 6 | The instructions in this guide use the following *replaceable* values. 7 | 8 | * `QUICKSTART_NAME`: This variable should be replaced with your quickstart name, for example: *my-quickstart* 9 | * `APPLICATION_NAME`: This value should be replaced with a unique variation of the quickstart name, for example: *myquickstart* 10 | * `YOUR_DOMAIN_NAME`: This value should be replaced with your OpenShift domain name. 11 | 12 | ### Create an OpenShift Account and Domain 13 | 14 | If you do not yet have an OpenShift account and domain, [Sign in to OpenShift](https://openshift.redhat.com/app/login) to create the account and domain. [Get Started with OpenShift](https://openshift.redhat.com/app/getting_started) will show you how to install the OpenShift Express command line interface. 15 | 16 | ### Create the OpenShift Application 17 | 18 | _NOTE_: The domain name for this application will be `APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com`. In these instructions, be sure to replace all instances of `YOUR_DOMAIN_NAME` with your own OpenShift account user name. 19 | 20 | Open a shell command prompt and change to a directory of your choice. Enter the following command to create a Red Hat JBoss Enterprise Application Platform 6 application: 21 | 22 | rhc app create -a APPLICATION_NAME -t jbosseap-6 23 | 24 | This command creates an OpenShift application named APPLICATION_NAME and will run the application inside the `jbosseap-6` container. You should see some output similar to the following: 25 | 26 | Application Options 27 | ------------------- 28 | Namespace: YOUR_DOMAIN_NAME 29 | Cartridges: jbosseap-6 (addtl. costs may apply) 30 | Gear Size: default 31 | Scaling: no 32 | 33 | Creating application 'APPLICATION_NAME' ... done 34 | 35 | Waiting for your DNS name to be available ... done 36 | 37 | Cloning into 'APPLICATION_NAME'... 38 | Warning: Permanently added the RSA host key for IP address '54.237.58.0' to the list of known hosts. 39 | 40 | Your application 'APPLICATION_NAME' is now available. 41 | 42 | URL: http://APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com/ 43 | SSH to: 52864af85973ca430200006f@APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com 44 | Git remote: ssh://52864af85973ca430200006f@APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com/~/git/APPLICATION_NAME.git/ 45 | Cloned to: CURRENT_DIRECTORY/APPLICATION_NAME 46 | 47 | Run 'rhc show-app APPLICATION_NAME' for more details about your app. 48 | 49 | The create command creates a GitHub repository in the current directory with the same name as the application. Notice that the output also reports the URL at which the application can be accessed. Make sure it is available by typing the published url into a browser or use command line tools such as curl or wget. Be sure to replace `YOUR_DOMAIN_NAME` with your OpenShift account domain name. 50 | 51 | _Note_: There is a limit to the number of applications you can deploy concurrently to OpenShift. If the `rhc app create` command returns an error indicating you have reached that limit, you must delete an existing application before you continue. 52 | 53 | * To view the list of your OpenShift applications, type: `rhc domain show` 54 | * To delete an application from OpenShift, type the following, substituting the application name you want to delete: `rhc app-delete -a APPLICATION_NAME_TO_DELETE` 55 | 56 | ### Migrate the Quickstart Source 57 | 58 | Now that you have confirmed it is working you can migrate the quickstart source. You do not need the generated default application, so navigate to the new git repository directory and tell git to remove the source and pom files: 59 | 60 | cd APPLICATION_NAME 61 | git rm -r src pom.xml 62 | 63 | Copy the source for the QUICKSTART_NAME quickstart into this new git repository: 64 | 65 | cp -r QUICKSTART_HOME/QUICKSTART_NAME/src . 66 | cp QUICKSTART_HOME/QUICKSTART_NAME/pom.xml . 67 | 68 | ### Configure the OpenShift Server 69 | 70 | If you need to configure the server, you modify the XML in the hidden `APPLICATION_NAME/.openshift/config/standalone.xml` file. 71 | 72 | ### Deploy the OpenShift Application 73 | 74 | You can now deploy the changes to your OpenShift application using git as follows. 75 | 76 | 1. Add the files to GitHub 77 | * Add the quickstart `src` directory and `pom.xml` file. 78 | 79 | git add src pom.xml 80 | * If you modified the server configuration, you must also add the hidden configuration file. 81 | 82 | git add .openshift/config/standalone.xml 83 | 2. Commit the changes. 84 | 85 | git commit -m "QUICKSTART_NAME quickstart on OpenShift" 86 | 3. Deploy the quickstart to OpenShift. 87 | 88 | git push 89 | 90 | The final push command triggers the OpenShift infrastructure to build and deploy the changes. 91 | 92 | Note that OpenShift activates the `openshift` profile in the `pom.xml` file. The resulting WAR is copied to the `deployments/` directory and deployed without a context path. 93 | 94 | ### Test the OpenShift Application 95 | 96 | When the push command returns you can test the application by getting the following URL either via a browser or using tools such as curl or wget. Be sure to replace the `YOUR_DOMAIN_NAME` in the URL with your OpenShift account domain name. 97 | 98 | http://APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com 99 | 100 | You can use the OpenShift command line tools or the OpenShift web console to discover and control the application. 101 | 102 | ### View the JBoss EAP Server Log on OpenShift 103 | 104 | Now you can look at the output of the server by running the following command: 105 | 106 | rhc tail -a APPLICATION_NAME 107 | 108 | This will show the tail of the JBoss EAP server log. 109 | 110 | _Note:_ You may see the following error in the log: 111 | 112 | 2014/03/17 07:50:36,231 ERROR [org.jboss.as.controller.management-operation] (management-handler-thread - 4) JBAS014613: Operation ("read-resource") failed - address: ([("subsystem" => "deployment-scanner")]) - failure description: "JBAS014807: Management resource '[(\"subsystem\" => \"deployment-scanner\")]' not found" 113 | 114 | This is a benign error that occurs when the status of the deployment is checked too early in the process. This process is retried, so you can safely ignore this error. 115 | 116 | ### Delete the OpenShift Application 117 | 118 | When you are finished with the application you can delete it as follows: 119 | 120 | rhc app-delete -a APPLICATION_NAME 121 | 122 | 123 | -------------------------------------------------------------------------------- /guides/CREATE_USERS.adoc: -------------------------------------------------------------------------------- 1 | [[create_users_required_by_the_quickstarts]] 2 | 3 | = Create Users Required by the Quickstarts 4 | 5 | == Summary 6 | 7 | By default, Red Hat JBoss Enterprise Application Platform is distributed with security enabled for the management interfaces. A few of the quickstarts use these management interfaces and require that you create a management or application user to access the running application. An `add-user` script is provided in the `__EAP_HOME__/bin` directory for that purpose. You can run the script interactively or you can pass arguments on the command line. 8 | 9 | NOTE: See link:USE_OF_EAP_HOME.adoc#use_of_product_home_and_jboss_home_variables[Use of EAP_HOME] for information about the JBoss EAP installation path. 10 | 11 | The following procedures describe how to add a user with the appropriate permissions to run the quickstarts that depend on them. 12 | 13 | * xref:add_a_management_user[Add a Management User] 14 | * xref:add_an_application_user[Add an Application User] 15 | 16 | Be aware that passwords must meet the following requirements: 17 | 18 | * It can not be the same as the user name. 19 | * It must contain at least 8 characters. 20 | * It must contain at least one alphanumeric character. 21 | * It must contain at least one digit. 22 | * It must contain at least one non-alphanumeric symbol. 23 | 24 | For more information about how to configure users, see the https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/[Product Documentation] for Red Hat JBoss Enterprise Application Platform. 25 | 26 | [[add_a_management_user]] 27 | == Add a Management User 28 | 29 | You can pass arguments on the command line or you can run the script interactively. The examples below use "admin" for the `Username` and "adminPass1!" for the `Password`. If the quickstart requires a specific `Username` and `Password`, be sure to replace them in the examples below. 30 | 31 | [[add_a_management_user_passing_arguments]] 32 | === Add a Management User Passing Arguments on the Command Line 33 | 34 | You can create the management user non-interactively by passing each argument on the command line. 35 | 36 | For example, to add the Management User `admin` in the default `ManagementRealm` realm with password `adminPass1!`, 37 | open a terminal and type the following: 38 | 39 | * For Linux: `$ __EAP_HOME__/bin/add-user.sh -u 'admin' -p 'adminPass1!'`` 40 | * For Windows: `> __EAP_HOME__\bin\add-user.bat -u 'admin' -p 'adminPass1!'`` 41 | 42 | 43 | [[add_a_management_user_interactively]] 44 | === Add a Management User Interactively 45 | 46 | If you prefer, you can create the management user interactively. 47 | 48 | . Open a terminal. 49 | . Type the command for your operating system. 50 | * For Linux: `$ __EAP_HOME__/bin/add-user.sh` 51 | * For Windows: `> __EAP_HOME__\bin\add-user.bat` 52 | 53 | . You should see the following response: 54 | + 55 | [source,options="nowrap"] 56 | ---- 57 | What type of user do you wish to add? 58 | 59 | a) Management User (mgmt-users.properties) 60 | b) Application User (application-users.properties) 61 | (a): 62 | ---- 63 | + 64 | . At the prompt, press enter to use the default `Management User`. You should see the following response. 65 | + 66 | [source,options="nowrap"] 67 | ---- 68 | Enter the details of the new user to add. 69 | Using realm 'ManagementRealm' as discovered from the existing property files. 70 | Username : 71 | ---- 72 | . Enter the `Username` and, at the next prompt, enter the `Password`. 73 | + 74 | [source,options="nowrap"] 75 | ---- 76 | Username : admin 77 | Password : (choose a password for the admin user) 78 | ---- 79 | + 80 | Repeat the password. 81 | . At the next prompt, you are asked the following. 82 | + 83 | [source,options="nowrap"] 84 | ---- 85 | What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]: 86 | ---- 87 | + 88 | Leave it blank and press enter. 89 | 90 | . Choose `yes` for the remaining prompts. 91 | 92 | [[add_an_application_user]] 93 | == Add an Application User 94 | 95 | You can pass arguments on the command line or you can run the script interactively. The examples below use "quickstartUser" for the `Username`, "quickstartPwd1!" for the `Password`, and "guest" for the group. If the quickstart requires a specific `Username`, `Password`, or `group`, be sure to replace them in the examples below. 96 | 97 | [[add_an_application_user_passing_arguments]] 98 | === Add an Application User Passing Arguments on the Command Line 99 | 100 | You can create the application user non-interactively by passing each argument on the command line. 101 | 102 | The default application user for the quickstarts is `quickstartUser`, in the `ApplicationRealm` realm, with password `quickstartPwd1!`, and belonging to group `guest`. 103 | To add the default application user, open a terminal and type the following: 104 | 105 | * For Linux: `$ __EAP_HOME__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'` 106 | * For Windows: `> __EAP_HOME__\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'` 107 | 108 | 109 | [[add_an_application_user_interactively]] 110 | === Add an Application User Interactively 111 | 112 | If you prefer, you can create the application user interactively. 113 | 114 | . Open a terminal. 115 | . Type the command for your operating system. 116 | 117 | * For Linux: `$ __EAP_HOME__/bin/add-user.sh` 118 | * For Windows: `> __EAP_HOME__\bin\add-user.bat` 119 | 120 | . You should see the following response: 121 | + 122 | [source,options="nowrap"] 123 | ---- 124 | What type of user do you wish to add? 125 | 126 | a) Management User (mgmt-users.properties) 127 | b) Application User (application-users.properties) 128 | (a): 129 | ---- 130 | 131 | . At the prompt, type `b`. You should see the following response: 132 | + 133 | [source,options="nowrap"] 134 | ---- 135 | Enter the details of the new user to add. 136 | Using realm 'ApplicationRealm' as discovered from the existing property files. 137 | Username : 138 | ---- 139 | 140 | . Enter the the `Username` and at the next prompt, enter the `Password`. If the quickstart `_README_` file specifies a `Username` and `Password`, enter them here. Otherwise, use the default `Username` `quickstartUser` and `Password` `quickstartPwd1!`. 141 | + 142 | [source,options="nowrap"] 143 | ---- 144 | Username : quickstartUser 145 | Password : quickstartPwd1! 146 | ---- 147 | 148 | . At the next prompt, you are asked the following. 149 | + 150 | [source,options="nowrap"] 151 | ---- 152 | What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]: 153 | ---- 154 | 155 | . If the quickstart `_README_` file specifies the groups to use, enter that here. Otherwise, type the group: `guest` 156 | 157 | xref:create_users_required_by_the_quickstarts[Back to top] 158 | -------------------------------------------------------------------------------- /guides/CONFIGURE_MAVEN.md: -------------------------------------------------------------------------------- 1 | Configure Maven to Build and Deploy the Quickstarts 2 | =============== 3 | 4 | Summary: The artifacts and dependencies needed to build and deploy applications to Red Hat JBoss Enterprise Application Platform 6 are hosted in public repositories. You must configure Maven to use these repositories before you build and deploy the quickstarts. How you do this depends on whether you plan to use JBoss Developer Studio or Maven command line to build and deploy your applications. Both methods are described below. 5 | 6 | * [Configure Maven - For Use with Command Line](#configure-maven---for-use-with-command-line): Follow these instructions if you plan to build and deploy the quickstarts using Maven command line tools. 7 | * [Configure Maven - For Use with JBoss Developer Studio](#configure-maven---for-use-with-jboss-developer-studio): Follow these instructions if you plan to build and deploy the quickstarts using JBoss Developer Studio. 8 | 9 | Some common profiles are defined and may be used in some quickstart POM files. These profiles are described here: [Use of Maven Profiles in POM Files](#use-of-maven-profiles-in-pom-files) 10 | 11 | For more information about Maven, see the [Maven Guide](https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Development_Guide/index.html#chap-Maven_Guide "Maven Guide") chapter in the _Development Guide_ for Red Hat JBoss Enterprise Application Platform. 12 | 13 | For more information about how to configure Maven for use with the quickstarts, see [Configure Maven](https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html-single/Getting_Started_Guide/index.html#sect-Configure_Maven "Configure Maven") in the _Getting Started Guide_ for Red Hat JBoss Enterprise Application Platform. 14 | 15 | 16 | Configure Maven - For Use With Command Line 17 | ------------------------------------------- 18 | 19 | ### Download and Install Maven 20 | 21 | If you have not yet done so, you must download and install Maven. 22 | 23 | 1. Go to [Apache Maven Project - Download Maven](http://maven.apache.org/download.html) and download the latest distribution for your operating system. 24 | 2. See the Maven documentation for information on how to download and install Apache Maven for your operating system. 25 | 26 | _Note:_ Maven 3.2.2 introduced a bug that breaks resolution of the JBoss EAP BOM dependencies because it ignores additional repositories during artifact resolution. For more information about this bug, see . Make sure to use Maven 3.2.3 or later. 27 | 28 | ### Configure Maven to Use the JBoss EAP Repositories 29 | 30 | The quickstarts use artifacts located in the JBoss GA and Early Access repositories. You must configure Maven to use these repositories before you build and deploy the quickstarts. 31 | 32 | _Note:_ These instructions assume you are working with a released version of the quickstarts. If you are working with the quickstarts located in the GitHub master branch, follow the instructions located in the [Contributing Guide](CONTRIBUTING.md#configure-maven). 33 | 34 | 1. Locate the Maven install directory for your operating system. It is usually installed in `${user.home}/.m2/`. 35 | 36 | For Linux or Mac: ~/.m2/ 37 | For Windows: "\Documents and Settings\USER_NAME\.m2\" -or- "\Users\USER_NAME\.m2\" 38 | 39 | 2. Copy the `settings.xml` file from the root of the quickstarts directory to your Maven install directory. 40 | 41 | For Linux or Mac: cp QUICKSTART_HOME/settings.xml ~/.m2/settings.xml 42 | For Windows: copy QUICKSTART_HOME/settings.xml "\Documents and Settings\USER_NAME\.m2\settings.xml" 43 | -or- copy QUICKSTART_HOME/settings.xml "\Users\USER_NAME\.m2\settings.xml" 44 | 45 | _Note:_ If you do not wish to configure the Maven settings, you must pass the configuration setting on every Maven command as follows: ` -s QUICKSTART_HOME/settings.xml` 46 | 47 | 48 | Configure Maven - For Use with JBoss Developer Studio 49 | ----------------------------------------------------- 50 | 51 | Maven is distributed with JBoss Developer Studio, so it is not necessary to install it separately. However, you must configure Maven for use by the Java EE Web Project wizard for deployments to JBoss Enterprise Application Server 6.x. 52 | 53 | 1. Start JBoss Developer Studio. 54 | 2. Choose menu option `Window` --> `Preferences`. 55 | 3. Expand `JBoss Tools` and select `JBoss Maven Integration`. 56 | 4. Keep the default selections and click the `Configure Maven Repositories...` button. 57 | 5. Click `Add Repository` to configure the `JBoss GA Tech Preview` Maven repository and complete the form as follows: 58 | 59 | Profile 60 | Profile ID: jboss-ga-repository 61 | Repository 62 | ID: jboss-ga-repository 63 | Name: jboss-ga-repository 64 | URL: http://maven.repository.redhat.com/techpreview/all/ 65 | 66 | Also check the `Active by default` checkbox to enable the Maven repository. Then click `OK`. 67 | 68 | 5. Click `Add Repository` to configure the `JBoss Early Access` Maven repository and complete the form as follows: 69 | 70 | Profile 71 | Profile ID: jboss-earlyaccess-repository 72 | Repository 73 | ID: jboss-earlyaccess-repository 74 | Name: jboss-earlyaccess-repository 75 | URL: http://maven.repository.redhat.com/earlyaccess/all/ 76 | 77 | Also check the `Active by default` checkbox to enable the Maven repository. Then click `OK`. 78 | 79 | 6. Review the newly added repositories and click `Finish`. You are prompted with the message "Are you sure you want to update the file 'MAVEN_HOME/settings.xml'?". Click `Yes` to update the settings. Click `OK` to close the dialog. 80 | 81 | The JBoss EAP Maven repository is now configured for use with JBoss Developer Studio.JBoss Developer Studio configures the `MAVEN_HOME/settings.xml` file for you. 82 | 83 | 84 | Use of Maven Profiles in POM Files 85 | ---------------------------------- 86 | 87 | Profiles are used by Maven to customize the build environment. The `pom.xml` in the root of some quickstart directories may define some of the following profiles. 88 | 89 | _NOTE:_ Some profiles in this list may not be used by some product quickstart projects. 90 | 91 | * The `default` profile defines the list of modules or quickstarts that require nothing but JBoss Enterprise Application Platform. 92 | * The `requires-postgres` profile lists the quickstarts that require PostgreSQL to be running when the quickstart is deployed. 93 | * The `complex-dependency` profile lists quickstarts that require manual configuration that can not be automated. 94 | * The `requires-full` profile lists quickstarts the require you start the JBoss EAP server using the full profile. 95 | * The `requires-xts` profile lists quickstarts the require you start the JBoss EAP server using the xts profile. 96 | * The `non-maven` profile lists quickstarts that do not require Maven, for example, quickstarts that depend on deployment of other quickstarts or those that use other Frameworks such as Forge. 97 | * The `functional-tests` profile lists quickstarts that provide functional tests. 98 | 99 | [Back to top](#configure-maven-to-build-and-deploy-the-quickstarts) 100 | -------------------------------------------------------------------------------- /dist/release-utils.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # 3 | # JBoss, Home of Professional Open Source 4 | # Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual 5 | # contributors by the @authors tag. See the copyright.txt in the 6 | # distribution for a full listing of individual contributors. 7 | # 8 | # Licensed under the Apache License, Version 2.0 (the "License"); 9 | # you may not use this file except in compliance with the License. 10 | # You may obtain a copy of the License at 11 | # http://www.apache.org/licenses/LICENSE-2.0 12 | # Unless required by applicable law or agreed to in writing, software 13 | # distributed under the License is distributed on an "AS IS" BASIS, 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 | # See the License for the specific language governing permissions and 16 | # limitations under the License. 17 | # 18 | 19 | 20 | REQUIRED_BASH_VERSION=3.0.0 21 | 22 | if [[ $BASH_VERSION < $REQUIRED_BASH_VERSION ]]; then 23 | echo "You must use Bash version 3 or newer to run this script" 24 | exit 25 | fi 26 | 27 | 28 | DIR=$(cd -P -- "$(dirname -- "$0")" && pwd -P) 29 | 30 | # DEFINE 31 | 32 | ARCHETYPES=("jboss-javaee6-webapp-archetype" "jboss-javaee6-webapp-ear-archetype") 33 | QUICKSTARTS=("kitchensink" "kitchensink-ear") 34 | VERSIONS_MAVEN_PLUGIN_VERSION=1.3.1 35 | 36 | # SCRIPT 37 | 38 | HUMAN_READABLE_ARCHETYPES="" 39 | i=0 40 | element_count=${#ARCHETYPES[@]} 41 | index=0 42 | while [ "$index" -lt "$element_count" ] 43 | do 44 | if [ $index -ne 0 ] 45 | then 46 | HUMAN_READABLE_ARCHETYPES="${HUMAN_READABLE_ARCHETYPES}, " 47 | fi 48 | HUMAN_READABLE_ARCHETYPES="${HUMAN_READABLE_ARCHETYPES}${ARCHETYPES[index]}" 49 | ((index++)) 50 | done 51 | 52 | 53 | usage() 54 | { 55 | cat << EOF 56 | usage: $0 options 57 | 58 | This script aids in releasing the quickstarts 59 | 60 | OPTIONS: 61 | -u Updates version numbers in all POMs, used with -o and -n 62 | -o Old version number to update from 63 | -n New version number to update to 64 | -r Regenerate the various quickstarts based on archetypes ${HUMAN_READABLE_ARCHETYPES} 65 | -m Generate html versions of markdown readmes 66 | -h Shows this message 67 | EOF 68 | } 69 | 70 | update() 71 | { 72 | cd $DIR/../ 73 | echo "Updating versions from $OLDVERSION TO $NEWVERSION for all Java files under $PWD" 74 | perl -pi -e "s/${OLDVERSION}/${NEWVERSION}/g" `find . -name \*.java` 75 | 76 | echo "Performing updates to POMs" 77 | poms=`find . -type f -iname "pom.xml" -maxdepth 2 | sort` 78 | for pom in $poms 79 | do 80 | echo "Updating ${pom}" 81 | mvn org.codehaus.mojo:versions-maven-plugin:${VERSIONS_MAVEN_PLUGIN_VERSION}:set -DnewVersion=${NEWVERSION} -f ${pom} -q 82 | mvn org.codehaus.mojo:versions-maven-plugin:${VERSIONS_MAVEN_PLUGIN_VERSION}:commit -f ${pom} -q 83 | done 84 | } 85 | 86 | markdown_to_html() 87 | { 88 | cd $DIR/../ 89 | # Clear the contents from toc.html file 90 | #rm dist/target/toc.html 91 | #touch dist/target/toc.html 92 | 93 | # Loop through the sorted quickstart directories and process them 94 | # Exclude the template directory since it's not a quickstart 95 | #subdirs=`find . -maxdepth 1 -type d ! -iname ".*" ! -iname "template" | sort` 96 | #for subdir in $subdirs 97 | #do 98 | # readmes=`find $subdir -iname readme.md` 99 | # for readme in $readmes 100 | # do 101 | # echo "Processing $readme" 102 | # output_filename=${readme//.md/.html} 103 | # output_filename=${output_filename//.MD/.html} 104 | # $DIR/github-flavored-markdown.rb $readme > $output_filename 105 | # done 106 | #done 107 | 108 | 109 | # Process the MarkDown files in the guides directory 110 | cd $DIR/../guides 111 | echo "Processing the guides.." 112 | 113 | for i in *.md; do 114 | markdown_filename=$i 115 | echo "Processing $markdown_filename" 116 | output_filename=${markdown_filename//.md/.html} 117 | $DIR/github-flavored-markdown.rb $markdown_filename > $output_filename 118 | done 119 | 120 | # guidefiles=`find . -name *.md` 121 | # echo "guidefiles=" $guidefiles 122 | # for guidefile in $guidefiles 123 | # do 124 | # markdown_filename=$guidefile 125 | # echo "Processing $markdown_filename" 126 | # output_filename=${markdown_filename//.md/.html} 127 | # $DIR/github-flavored-markdown.rb $markdown_filename > $output_filename 128 | # done 129 | 130 | # Now process the root readme 131 | cd $DIR/../ 132 | readme=README.md 133 | echo "Processing $readme" 134 | output_filename=${readme//.md/.html} 135 | output_filename=${output_filename//.MD/.html} 136 | $DIR/github-flavored-markdown.rb $readme > $output_filename 137 | 138 | # Now process the contributing markdown 139 | # cd $DIR/../ 140 | # markdown_filename=CONTRIBUTING.md 141 | # echo "Processing $markdown_filename" 142 | # output_filename=${markdown_filename//.md/.html} 143 | # output_filename=${output_filename//.MD/.html} 144 | # $DIR/github-flavored-markdown.rb $markdown_filename > $output_filename 145 | 146 | # Now process the release procedure markdown 147 | # cd $DIR/../ 148 | # markdown_filename=RELEASE_PROCEDURE.md 149 | # echo "Processing $markdown_filename" 150 | # output_filename=${markdown_filename//.md/.html} 151 | # output_filename=${output_filename//.MD/.html} 152 | # $DIR/github-flavored-markdown.rb $markdown_filename > $output_filename 153 | } 154 | 155 | regenerate() 156 | { 157 | TMPDIR="$DIR/target/regen" 158 | ROOTDIR="$DIR/../" 159 | 160 | rm -rf $TMPDIR 161 | 162 | mkdir -p $TMPDIR 163 | 164 | cd $TMPDIR 165 | 166 | element_count=${#ARCHETYPES[@]} 167 | index=0 168 | while [ "$index" -lt "$element_count" ] 169 | do 170 | archetype=${ARCHETYPES[index]} 171 | quickstart=${QUICKSTARTS[index]} 172 | package=${quickstart//-/_} 173 | name="JBoss AS Quickstarts: $quickstart" 174 | echo "**** Regenerating $quickstart from $archetype" 175 | mvn archetype:generate -DarchetypeGroupId=org.jboss.spec.archetypes -DarchetypeArtifactId=$archetype -DarchetypeVersion=$VERSION -DartifactId=jboss-as-$quickstart -DgroupId=org.jboss.as.quickstarts -Dpackage=org.jboss.as.quickstarts.$package -Dversion=$VERSION -DinteractiveMode=false -Dname="${name}" 176 | ((index++)) 177 | rm -rf $ROOTDIR/$quickstart 178 | mv $TMPDIR/jboss-as-$quickstart $ROOTDIR/$quickstart 179 | done 180 | 181 | } 182 | 183 | OLDVERSION="1.0.0-SNAPSHOT" 184 | NEWVERSION="1.0.0-SNAPSHOT" 185 | VERSION="1.0.0-SNAPSHOT" 186 | CMD="usage" 187 | 188 | while getopts “muo:n:r:” OPTION 189 | 190 | do 191 | case $OPTION in 192 | u) 193 | CMD="update" 194 | ;; 195 | h) 196 | usage 197 | exit 198 | ;; 199 | o) 200 | OLDVERSION=$OPTARG 201 | ;; 202 | n) 203 | NEWVERSION=$OPTARG 204 | ;; 205 | r) 206 | CMD="regenerate" 207 | VERSION=$OPTARG 208 | ;; 209 | m) 210 | CMD="markdown_to_html" 211 | ;; 212 | [?]) 213 | usage 214 | exit 215 | ;; 216 | esac 217 | done 218 | 219 | $CMD 220 | 221 | -------------------------------------------------------------------------------- /dist/css/documentation.css: -------------------------------------------------------------------------------- 1 | /* 2 | * JBoss, Home of Professional Open Source 3 | * Copyright 2014, Red Hat, Inc. and/or its affiliates, and individual 4 | * contributors by the @authors tag. See the copyright.txt in the 5 | * distribution for a full listing of individual contributors. 6 | * 7 | * Licensed under the Apache License, Version 2.0 (the "License"); 8 | * you may not use this file except in compliance with the License. 9 | * You may obtain a copy of the License at 10 | * http://www.apache.org/licenses/LICENSE-2.0 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | * See the License for the specific language governing permissions and 15 | * limitations under the License. 16 | */ 17 | /*------------------------------------------------------------------------------ 18 | Global Documentation Styles 19 | ------------------------------------------------------------------------------*/ 20 | 21 | html { 22 | height:100%; 23 | } 24 | 25 | body, table { 26 | font: 13px helvetica,arial,freesans,clean,sans-serif; 27 | line-height: 1.4em; 28 | background-color: #fff; 29 | color: #393939; 30 | } 31 | 32 | body { 33 | height: 100%; 34 | width: 95%; 35 | position: relative; 36 | float: left; 37 | z-index: 2; 38 | } 39 | 40 | table { 41 | border-collapse: collapse; 42 | margin: 0 1em; 43 | table-layout: fixed; 44 | white-space: pre-wrap; 45 | word-wrap: break-word; 46 | } 47 | 48 | p { 49 | margin: 1em 0; 50 | } 51 | 52 | h1 { 53 | font-size: 20px; 54 | border-bottom: 1px solid #cccccc; 55 | padding: .5em 0; 56 | margin: 2em 0 1em; 57 | } 58 | 59 | h1:first-child { 60 | margin: 0 0 1em; 61 | } 62 | 63 | h2 { 64 | font-size: 16px; 65 | color: #333; 66 | margin: 2em auto 1em; 67 | } 68 | 69 | body.api .content h2 { 70 | background: transparent url(../images/crud-sprite.png) left 2px no-repeat; 71 | padding-left: 22px; 72 | } 73 | 74 | h2 span.step { 75 | color: #666; 76 | } 77 | 78 | h3 { 79 | font-size: 14px; 80 | color: #333; 81 | margin: 1.5em 0 .5em; 82 | } 83 | 84 | h5 { 85 | font-size: 13px; 86 | } 87 | 88 | h6 { 89 | font-size: 13px; 90 | color: #666; 91 | } 92 | 93 | a { 94 | color: #4183C4; 95 | text-decoration: none; 96 | } 97 | 98 | a:hover, 99 | a:active { 100 | text-decoration:underline; 101 | } 102 | 103 | blockquote { 104 | margin:0 -5px; 105 | padding: 0px 20px; 106 | } 107 | 108 | ul, ol { 109 | margin: 0px; 110 | padding: 0px; 111 | margin-left: 1.5em; 112 | } 113 | 114 | ul { 115 | list-style-type: disc; 116 | } 117 | 118 | dl { 119 | margin-left: 10px; 120 | } 121 | 122 | dt { 123 | font-weight: bold; 124 | color: #666; 125 | } 126 | 127 | dd { 128 | padding-left: 1em; 129 | margin-bottom: 1em; 130 | } 131 | 132 | dd + dd { 133 | margin-bottom: 0; 134 | } 135 | 136 | em { 137 | font-style: italic; 138 | } 139 | 140 | a img { 141 | border: 0px; 142 | } 143 | 144 | img { 145 | max-width: 100%; 146 | border: 1px solid #dddddd; 147 | -webkit-box-shadow: 1px 1px 3px #ddd; 148 | -moz-box-shadow: 1px 1px 3px #ddd; 149 | box-shadow: 1px 1px 3px #ddd; 150 | } 151 | 152 | td, th { 153 | border: solid 1px #ccc; 154 | margin: 0px; 155 | } 156 | 157 | tr:nth-child(even) { background-color:#f8f8f8; } 158 | tr:nth-child(odd) { background-color:#fff; } 159 | 160 | p > tt, 161 | p > code, 162 | li > code, 163 | td > code, 164 | th > code { 165 | font: 12px Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace; 166 | color: #52595d; 167 | -webkit-border-radius: 3px; 168 | -moz-border-radius: 3px; 169 | border-radius: 3px; 170 | -moz-background-clip: padding; 171 | -webkit-background-clip: padding-box; 172 | background-clip: padding-box; 173 | border: 1px solid #ccc; 174 | background-color: #f8f8f8; 175 | padding: 0px 3px; 176 | display: inline-block; 177 | } 178 | 179 | 180 | /*------------------------------------------------------------------------------ 181 | Pre/Code Styles 182 | ------------------------------------------------------------------------------*/ 183 | 184 | code {white-space: nowrap;} 185 | 186 | pre { 187 | border: 1px solid #cacaca; 188 | line-height: 1.2em; 189 | font: 12px Monaco,"Courier New","DejaVu Sans Mono","Bitstream Vera Sans Mono",monospace; 190 | padding: 10px; 191 | overflow:auto; 192 | -webkit-border-radius: 3px; 193 | -moz-border-radius: 3px; 194 | border-radius: 3px; 195 | -moz-background-clip: padding; 196 | -webkit-background-clip: padding-box; 197 | background-clip: padding-box; 198 | background-color: #f8f8f8; 199 | color: #393939; 200 | margin: 0px; 201 | } 202 | 203 | ul + pre { 204 | margin-top: 1em; 205 | } 206 | 207 | pre code {white-space: pre;} 208 | 209 | pre span.comment {color: #aaa;} 210 | 211 | pre.headers { 212 | margin-bottom: 0; 213 | border-bottom-width: 0; 214 | -webkit-border-radius: 3px 3px 0 0; 215 | -moz-border-radius: 3px 3px 0 0; 216 | border-radius: 3px 3px 0 0; 217 | color: #666; 218 | background-color: #f1f1f1; 219 | background-image: -moz-linear-gradient(top, #f1f1f1, #e1e1e1); 220 | background-image: -ms-linear-gradient(top, #f1f1f1, #e1e1e1); 221 | background-image: -o-linear-gradient(top, #f1f1f1, #e1e1e1); 222 | background-image: -webkit-gradient(linear, left top, left bottom, from(#f1f1f1), to(#e1e1e1)); 223 | background-image: -webkit-linear-gradient(top, #f1f1f1, #e1e1e1); 224 | background-image: linear-gradient(top, #f1f1f1, #e1e1e1); 225 | filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#f1f1f1', EndColorStr='#e1e1e1'); 226 | text-shadow: 0 1px 0 rgba(255, 255, 255, 0.7); 227 | } 228 | 229 | pre.no-response { 230 | -webkit-border-radius: 3px 3px; 231 | -moz-border-radius: 3px 3px; 232 | border-radius: 3px 3px; 233 | border-bottom: 1px solid #CACACA; 234 | } 235 | 236 | pre.headers + pre.highlight { 237 | -webkit-border-radius: 0 0 3px 3px; 238 | -moz-border-radius: 0 0 3px 3px; 239 | border-radius: 0 0 3px 3px; 240 | } 241 | 242 | pre.highlight { 243 | -webkit-border-radius:3px; 244 | -moz-border-radius:3px; 245 | border-radius:3px; 246 | background-color: #FAFAFB; 247 | } 248 | 249 | pre.terminal { 250 | background-color: #444; 251 | color: #fff; 252 | -webkit-border-radius: 3px; 253 | -moz-border-radius: 3px; 254 | border-radius: 3px; 255 | -moz-background-clip: padding; 256 | -webkit-background-clip: padding-box; 257 | background-clip: padding-box; 258 | border: 2px solid #DEDEDE; 259 | position: relative; 260 | padding: 10px; 261 | text-shadow: none; 262 | background-image: none; 263 | filter: none; 264 | } 265 | 266 | pre.terminal em { 267 | color: #f9fe64; 268 | } 269 | 270 | span.codeline { 271 | display: block; 272 | position: relative; 273 | } 274 | 275 | span.codeline:hover { 276 | background-color: #292929; 277 | margin: 0px; 278 | padding-left: 3px; 279 | margin-left: -3px; 280 | -webkit-border-radius: 3px; 281 | -moz-border-radius: 3px; 282 | border-radius: 3px; 283 | color: #666666; 284 | } 285 | 286 | span.codeline span { 287 | display: inline-block; 288 | font-size: 10px; 289 | color: #fff; 290 | padding: 0 0.3em 0.05em; 291 | position: absolute; 292 | right: 0px; 293 | top: 0px; 294 | text-indent: -9999px; 295 | background-image: url(../images/qmark.png); 296 | background-repeat: no-repeat; 297 | background-position: 1px 3px; 298 | max-width: 8px; 299 | min-width: 8px; 300 | -moz-user-select: none; 301 | -khtml-user-select: none; 302 | user-select: none; 303 | cursor: default; 304 | } 305 | 306 | span.codeline span:hover { 307 | display: inline-block; 308 | text-indent: 0px; 309 | -webkit-border-radius: 3px; 310 | -moz-border-radius: 3px; 311 | border-radius: 3px; 312 | background: #000; 313 | border: 1px solid #292929; 314 | max-width: 1000px; 315 | } 316 | 317 | span.codeline:hover em { 318 | color: #666666; 319 | } 320 | 321 | pre.bootcamp { 322 | white-space: normal; 323 | margin-left: -10px; 324 | background-image: none; 325 | } 326 | 327 | span.bash-output { 328 | color: #63e463; 329 | display: block; 330 | position: relative; 331 | -moz-user-select: none; 332 | -khtml-user-select: none; 333 | user-select: none; 334 | } 335 | 336 | /* end */ 337 | -------------------------------------------------------------------------------- /guides/DEPLOY_TO_OPENSHIFT_JBOSS_EAP7.md: -------------------------------------------------------------------------------- 1 | Deploy the JBoss EAP 7 Quickstarts to OpenShift 2 | =============== 3 | 4 | If you have not yet done so, you must first configure your OpenShift environment to run the JBoss EAP quickstarts by following these instructions. 5 | 6 | ### Overview 7 | 8 | Before you begin, be sure to review the [Red Hat xPaaS EAP Image](https://access.redhat.com/documentation/en/red-hat-xpaas/version-0/red-hat-xpaas-eap-image/) documentation for information about developing with the Red Hat Enterprise Application Platform Image. Then follow the steps in the sections below to configure your OpenShift environment. 9 | 10 | * [Download and Configure the OpenShift Client Tools](#install_client_tools) 11 | * [Configure Your OpenShift Environment](#configure_openshift) 12 | * [Create Your OpenShift Project](#create_your_project) 13 | * [Install the Required Images](#install_the_required_images) 14 | * [Create the PostgreSQL Template for Local OpenShift Instances](#create_the_eap70-postgresql-s2i_template) 15 | * [Create the HTTPS Template for Local OpenShift Instances](#create_the_https-s2i_template) 16 | * [Create the Secrets Template for Your Project](#create_the_secrets) 17 | * [Deploy the Quickstart to OpenShift](#deploy_the_quickstart_to_openshift) 18 | * [Access the Running Application](#access_the_running_application) 19 | 20 | 21 | ### Download and Configure the OpenShift Client Tools. 22 | 23 | 1. Download and upzip the [OpenShift Client Tools](https://github.com/openshift/origin/releases/latest) for your operating system. 24 | 2. Add the folder to your `PATH` environment variable. 25 | 26 | _Note: For Linux systems, if you prefer you can simply copy the `oc` executable to `/usr/local/bin/` directory._ 27 | 28 | 3. Test the `oc` command by typing the following command in a terminal. 29 | 30 | $ oc version 31 | 32 | 4. For more information about this tool, see the [OpenShift CLI Reference](https://docs.openshift.com/enterprise/latest/cli_reference/index.html). 33 | 34 | ### Configure Your OpenShift Environment 35 | 36 | You can choose to configure and run OpenShift using any of the following methods. 37 | 38 | * You can use the [Public Cloud - Openshift Public](#use_public) 39 | * You can run OpenShift locally using the [Container Development Kit](#use_cdk) 40 | 41 | #### Use the OpenShift Public Cloud 42 | 43 | 1. [Register](https://api.preview.openshift.com) for the OpenShift Public offering. 44 | 2. When you receive your login information by email, go to the OpenShift Public [console](https://console.preview.openshift.com/console/). 45 | 3. Click the question mark (?) icon in the right upper corner of the console and select `Command Line Tools`. 46 | 4. Review your login token and run the `oc login --token=...` command. 47 | 48 | #### Use the Container Development Kit to Run OpenShift Locally 49 | 50 | 1. Install and configure the Container Development Kit (CDK). 51 | 52 | * Download the [Container Development Kit](http://developers.redhat.com/products/cdk/download/). 53 | * See the Red Hat Container Development Kit [Installation Guide](https://access.redhat.com/documentation/en/red-hat-container-development-kit/2.1/paged/installation-guide/) for instructions to configure and start the CDK. 54 | * Upon successful startup, the login credentials are printed to the terminal. 55 | 56 | 2. Log in to your OpenShift instance as `openshift-dev` by typing the following command in the terminal. 57 | 58 | $ oc login 10.1.2.2:8443 -u openshift-dev -p devel 59 | 60 | 61 | ### Create Your OpenShift Project 62 | 63 | Create a new OpenShift [project](https://docs.openshift.com/enterprise/latest/architecture/core_concepts/projects_and_users.html#projects) project named `quickstart-project`. 64 | 65 | $ oc new-project quickstart-project 66 | 67 | _NOTE: You can review the existing projects using the following command._ 68 | 69 | $ oc get project 70 | 71 | ### Install the Required Images 72 | 73 | If you are using a local OpenShift instance, you must install the JBoss EAP xPaaS image, the PostgreSQL image. If you are using OpenShift Public, you can skip this section. 74 | 75 | 1. Install the JBoss EAP xPaaS image by copying and pasting the following text into a terminal. 76 | 77 | cat <Create the PostgreSQL Template for Local OpenShift Instances 100 | 101 | If you are using a local OpenShift instance, you must create the application template for JBoss EAP 7 PostgreSQL applications. If you are using OpenShift Public, you can skip this section. 102 | 103 | To create this template, type the following command in a terminal. 104 | 105 | $ oc create -f https://raw.githubusercontent.com/jboss-openshift/application-templates/master/eap/eap70-postgresql-s2i.json 106 | 107 | ### Create the HTTPS Template for Local OpenShift Instances 108 | 109 | If you are using a local OpenShift instance, you must create the HTTPS template for JBoss EAP 7 applications. If you are using OpenShift Public, you can skip this section. 110 | 111 | To create this template, type the following command in a terminal. 112 | 113 | $ oc create -f https://raw.githubusercontent.com/jboss-openshift/application-templates/ose-v1.3.3/eap/eap70-https-s2i.json 114 | 115 | ### Create the Secrets Template for Your Project 116 | 117 | OpenShift provides support for distributing secrets, such as SSL certificates, among running containers. Import a self-signed certificate that will be used for encrypting HTTPS/TLS traffic. Create a certificate to be imported by JBoss EAP during the startup process b typing the following command in a terminal. 118 | 119 | $ oc create -n quickstart-project -f https://raw.githubusercontent.com/jboss-openshift/application-templates/master/secrets/eap7-app-secret.json 120 | 121 | _IMPORTANT: This self-signed, [base64 encoded certificate](https://github.com/jboss-openshift/application-templates/blob/ose-v1.3.3/secrets/eap7-app-secret.json#L35) was created using the [Oracle keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html). It is meant to demonstrate how to use a certificate stored in a Java keystore and is not secure!_ 122 | 123 | 124 | ### Deploy the Quickstart to OpenShift 125 | 126 | You are now ready to follow the quickstart instructions to configure and deploy your project to OpenShift. 127 | 128 | 1. Be sure you are still logged in to the OpenShift instance. 129 | 130 | 2. Create and deploy the quickstart to the OpenShift instance using either the `oc process` or `oc new-app` command. Be sure to replace `QUICKSTART_HOME`. `QUICKSTART_NAME`, and `QUICKSTART_DS` with the values provided in the quickstart instructions. 131 | 132 | * Use the `oc process` command. 133 | 134 | * If the quickstart uses a data source, use the following command. 135 | 136 | oc process -v \ 137 | SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts,\ 138 | SOURCE_REPOSITORY_REF=7.1.x-develop,\ 139 | CONTEXT_DIR=QUICKSTART_NAME,\ 140 | DB_JNDI=java:jboss/datasources/QUICKSTART_DS,\ 141 | DB_DATABASE=USERS,\ 142 | HTTPS_NAME=jboss,\ 143 | HTTPS_PASSWORD=mykeystorepass,\ 144 | JGROUPS_ENCRYPT_NAME=secret-key,\ 145 | JGROUPS_ENCRYPT_PASSWORD=password,\ 146 | IMAGE_STREAM_NAMESPACE=quickstart-project eap70-postgresql-s2i | oc create -f - 147 | 148 | * If the quickstart does not use a data source, you can omit the `DB_JNDI` and `DB_DATABASE` arguments and use the following command. 149 | 150 | oc process -v \ 151 | SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts,\ 152 | SOURCE_REPOSITORY_REF=7.1.x-develop,\ 153 | CONTEXT_DIR=QUICKSTART_NAME,\ 154 | HTTPS_NAME=jboss,\ 155 | HTTPS_PASSWORD=mykeystorepass,\ 156 | JGROUPS_ENCRYPT_NAME=secret-key,\ 157 | JGROUPS_ENCRYPT_PASSWORD=password,\ 158 | IMAGE_STREAM_NAMESPACE=quickstart-project eap70-postgresql-s2i | oc create -f - 159 | 160 | * Use the `oc new-app` command. 161 | 162 | * If the quickstart uses a data source, use the following command. 163 | 164 | oc new-app --template=eap70-postgresql-s2i -p \ 165 | SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts,\ 166 | SOURCE_REPOSITORY_REF=7.1.x-develop,\ 167 | CONTEXT_DIR=QUICKSTART_NAME,\ 168 | DB_JNDI=java:jboss/datasources/QUICKSTART_DS,\ 169 | DB_DATABASE=USERS,\ 170 | HTTPS_NAME=jboss,\ 171 | HTTPS_PASSWORD=mykeystorepass,\ 172 | JGROUPS_ENCRYPT_NAME=secret-key,\ 173 | JGROUPS_ENCRYPT_PASSWORD=password,\ 174 | IMAGE_STREAM_NAMESPACE=quickstart-project 175 | 176 | * If the quickstart does not use a data source, you can omit the `DB_JNDI` and `DB_DATABASE` arguments and use the following command. 177 | 178 | oc new-app --template=eap70-postgresql-s2i -p \ 179 | SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts,\ 180 | SOURCE_REPOSITORY_REF=7.1.x-develop,\ 181 | CONTEXT_DIR=QUICKSTART_NAME,\ 182 | HTTPS_NAME=jboss,\ 183 | HTTPS_PASSWORD=mykeystorepass,\ 184 | JGROUPS_ENCRYPT_NAME=secret-key,\ 185 | JGROUPS_ENCRYPT_PASSWORD=password,\ 186 | IMAGE_STREAM_NAMESPACE=quickstart-project 187 | 188 | 3. Wait for the build to finish. Check the status and view the logs using the following commands. 189 | 190 | * View the status of the containers. 191 | 192 | $ oc get pods -w 193 | 194 | * View the build logs. Replace `POD_NAME` with the name of the pod that displays in the previous command. In most cases, it is something similar to `eap-app-1-build` or `eap-app-1-06s0v`. 195 | 196 | $ oc logs -f POD_NAME 197 | 198 | * The log should display the following message when build has finished and the JBoss EAP server startup has completed. 199 | 200 | INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: JBoss EAP 7.0.0.GA (WildFly Core 2.1.2.Final-redhat-1) started in 26285ms - Started 542 of 866 services (513 services are lazy, passive or on-demand) 201 | 202 | 4. When the build completes, you are ready to access the running appliction. 203 | 204 | ### Access the Running Application 205 | 206 | You can access the application by using the OpenShift web console or by finding the URL using using`oc` tool. 207 | 208 | #### Access the Application Using the OpenShift Web Console 209 | 210 | 1. Using a browser, access the OpenShift web console using the URL provided when you configured and started Openshift. 211 | 212 | 2. Click on the *quickstart-project* link. 213 | 214 | 3. On the left side of the page, click on *Browse*, then choose *Routes*. You should see something similar to the following. 215 | 216 | | **Name** | **Hostname** | **Routes To** | **Target Port** | **TLS Termination** | 217 | |:----|:--------|:-----|:-----------|:---------------| 218 | | eap-app | eap-app-sample-project.router.default.svc.cluster.local | eap-app | | | 219 | | secure-eap-app | secure-eap-app-sample-project.router.default.svc.cluster.local | secure-eap-app | | | 220 | 221 | Because we used a self-signed certificate, there are two routes available for this application, one unsecured `http` and one `https` secured. 222 | 223 | 4. Click on the secure *Hostname* link to access the running application, for example, `secure-eap-app-sample-project.router.default.svc.cluster.local`. Be sure to accept the self-signed certificate as trusted in your browser. 224 | 225 | #### Access the Application Using the OpenShift Client Tool 226 | 227 | 1. Type the following command in a terminal. 228 | 229 | $ oc get route 230 | 231 | 2. You should see something like the following. 232 | 233 | | **NAME** | **HOST/PORT** | **PATH** | **SERVICE** | **TERMINATION** | **LABELS** | 234 | |:----|:--------|:-----|:-----------|:---------------|:-----| 235 | | eap-app | eap-app-sample-project.router.default.svc.cluster.local | | eap-app | | application=eap-app,template=eap70-postgresql-s2i,xpaas=1.3.2 | 236 | | secure-eap-app | secure-eap-app-sample-project.router.default.svc.cluster.local | | secure-eap-app | passthrough | application=eap-app,template=eap70-postgresql-s2i,xpaas=1.3.2 | 237 | 238 | 3. Copy the service address for the `secure-eap-app`, prefix it with `https://`, and paste it into a browser, for example: 239 | 240 | https://secure-eap-app-sample-project.router.default.svc.cluster.local 241 | -------------------------------------------------------------------------------- /guides/CONFIGURE_POSTGRESQL.md: -------------------------------------------------------------------------------- 1 | Configure the PostgreSQL Database for Use with the Quickstarts 2 | =============== 3 | 4 | Summary: Some of the quickstarts require the PostgreSQL database. This guide describes how to install and configure the database for use with these quickstarts. The instructions here are the minimum required to install PostgreSQL version 9.3. If you install a later version, be sure to modify the version when you issue the commands below. More detailed instructions on how to install, configure, and start PostgreSQL can be found on the Internet. 5 | 6 | _Note_: Although the database only needs to be installed once, to help partition each quickstart we recommend using a separate database per quickstart. Where you see `QUICKSTART_DATABASE_NAME`, you should replace that with the name provided in the specific quickstart's README file. 7 | 8 | The following sections describe the steps necessary to install and configure PostgreSQL for use with the quickstarts: 9 | 10 | * [Download and Install PostgreSQL](#download-and-install-postgresql): Follow the instructions for your operating system to download and install PostgreSQL. 11 | * [Create a Database User](#create-a-database-user): Create a user for the PostgreSQL database. 12 | * [Add the PostgreSQL Module to the Red Hat JBoss Enterprise Application Platform Server](#add-the-postgresql-module-to-the-red-hat-jboss-enterprise-application-platform-server): Create a JBoss Module for the JBoss EAP server. 13 | * [Configure the PostgreSQL Driver in the Red Hat JBoss Enterprise Application Platform Server](#configure-the-postgresql-driver-in-the-red-hat-jboss-enterprise-application-platform-server): Add PostgreSQL to the JBoss EAP server configuration. 14 | * [Remove the PostgreSQL Configuration](#remove-the-postgresql-configuration): When you are done testing, remove PostgreSQL from the server configuration. 15 | 16 | _NOTE: See [Use of EAP_HOME](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP_HOME.md) for information about the Red Hat JBoss Enterprise Application Platform installation path._ 17 | 18 | 19 | Download and Install PostgreSQL 20 | ------------------------------- 21 | 22 | Follow the instructions below for your operating system. 23 | 24 | * [Download and Install PostgreSQL on Linux](#download-and-install-postgresql-on-linux) 25 | * [Download and Install PostgreSQL on Macintosh](#download-and-install-postgresql-on-macintosh): 26 | * [Download and Install PostgreSQL on Windows](#download-and-install-postgresql-on-windows): 27 | 28 | _Note:_ The installation of PostgreSQL is a one time procedure. However, 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. 29 | 30 | ### Download and Install PostgreSQL on Linux 31 | 32 | Use the following steps to install and configure PostgreSQL on Linux. You can download the PDF installation guide here: 33 | 34 | 1. Install PostgreSQL 35 | * The yum install instructions for PostgreSQL can be found here: 36 | * Download the repository RPM from here: 37 | * To install PostgreSQL, in a command prompt type `sudo rpm -ivh RPM_FILE_NAME`, where RPM_FILE_NAME is the name of the downloaded repository RPM file, for example: 38 | 39 | sudo rpm -ivh pgdg-fedora93-9.3-1.noarch.rpm 40 | * Edit your distributions package manager definitions to exclude PostgreSQL. See the "important note" on for details on how to exclude install-and-configure-the-postgresql-database packages from the repository of the distribution. 41 | * Install _postgresql93_ and _postgres93-server_ by typing the following in a command prompt: 42 | 43 | sudo yum install postgresql93 postgresql93-server 44 | 2. Set a password for the _postgres_ user 45 | * In a command prompt, login as root and set the postgres password by typing the following commands: 46 | 47 | su 48 | passwd postgres 49 | * Choose a password 50 | 3. Configure the test database 51 | * In a command prompt, login as the _postgres_ user, navigate to the postgres directory, and initialize the database by typing: 52 | 53 | su postgres 54 | cd /usr/pgsql-9.3/bin/ 55 | ./initdb -D /var/lib/pgsql/9.3/data 56 | * Modify the `/var/lib/pgsql/9.3/data/pg_hba.conf` file to set the authentication scheme to password for tcp connections. Modify the line following the IPv4 local connections: change trust to to password. The line should look like this: 57 | 58 | host all all 127.0.0.1/32 password 59 | * Modify the `/var/lib/pgsql/9.3/data/postgresql.conf` file to allow prepared transactions and reduce the maximum number of connections 60 | 61 | max_prepared_transactions = 10 62 | max_connections = 10 63 | 64 | 4. Start the database server 65 | * In the same command prompt, type the following: 66 | 67 | ./postgres -D /var/lib/pgsql/9.3/data 68 | * Note, this command does not release the command prompt. In the next step you need to open a new command prompt. 69 | 70 | _Note: If you do not configure the the database to automatically start as a service, you must repeat the instruction to start the database every time you reboot your machine._ 71 | 72 | 5. Create a database for the quickstart (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart) 73 | * Open a new command prompt and login again as the _postgres_ user, navigate to the postgres directory, and create the database by typing the following: 74 | 75 | su postgres 76 | cd /usr/pgsql-9.3/bin/ 77 | ./createdb QUICKSTART_DATABASE_NAME 78 | 79 | 80 | ### Download and Install PostgreSQL on Macintosh 81 | 82 | The following are the steps to install and start PostgreSQL on Mac OS X. Note that this guide covers only 'One click installer' option. 83 | 84 | 1. Install PostgreSQL using Mac OS X One click installer: 85 | 2. Allow prepared transactions: 86 | 87 | sudo su - postgres 88 | * Edit `/Library/PostgreSQL/9.3/data/postgresql.conf` to allow prepared transactions 89 | 90 | max_prepared_transactions = 10 91 | 3. Start the database server 92 | 93 | cd /Library/PostgreSQL/9.3/bin 94 | ./pg_ctl -D ../data restart 95 | 4. Create a database for the quickstart (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart) 96 | 97 | ./createdb QUICKSTART_DATABASE_NAME 98 | 5. Verify that everything works. As the _postgres_ user using the password you specified in Step 1, type the following: 99 | 100 | cd /Library/PostgreSQL/9.3/bin 101 | ./psql -U postgres 102 | At the prompt 103 | 104 | start transaction; 105 | select 1; 106 | prepare transaction 'foobar'; 107 | commit prepared 'foobar'; 108 | 109 | 110 | ### Download and Install PostgreSQL on Windows 111 | 112 | Use the following steps to install and configure PostgreSQL on Windows: 113 | 114 | 1. Install PostgreSQL using the Windows installer: 115 | 2. Enable password authentication and configure PostgreSQL to allow prepared transactions 116 | * Modify the `C:\Program Files\PostgreSQL\9.3\data\pg_hba.conf` file to set the authentication scheme to password for tcp connections. Modify the line following the IPv4 local connections: change trust to to password. The line should look like this: 117 | 118 | host all all 127.0.0.1/32 password` 119 | * Modify the `C:\Program Files\PostgreSQL\9.3\data\postgresql.conf` file to allow prepared transactions and reduce the maximum number of connections: 120 | 121 | max_prepared_transactions = 10 122 | max_connections = 10 123 | 3. Start the database server 124 | * Choose Start -> All Programs -> PostgreSQL 9.3\pgAdmin III 125 | * Server Groups -> Servers (1) -> PostgreSQL 9.3 (localhost:5432) 126 | * Right click -> Stop Service 127 | * Right click -> Start Service 128 | 4. Create a database for the quickstart (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart) 129 | * Open a command prompt and type the following: 130 | 131 | cd C:\Program Files\PostgreSQL\9.3\bin\ 132 | createdb.exe -U postgres QUICKSTART_DATABASE_NAME 133 | 134 | 135 | Create a Database User 136 | ---------------------- 137 | 138 | 1. Make sure the PostgreSQL bin directory is in your PATH. 139 | * Open a command prompt and change to the root directory 140 | psql 141 | * If you see an error that 'psql' is not a recognized command, you need to add the PostgreSQL bin directory to your PATH environment variable. 142 | 2. As the _postgres_ user, start the PostgreSQL interactive terminal by typing the following command: 143 | 144 | psql -U postgres 145 | 3. Create the user sa with password sa and all privileges on the database by typing the following commands (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart): 146 | 147 | create user sa with password 'sa'; 148 | grant all privileges on database "QUICKSTART_DATABASE_NAME" to sa; 149 | \q 150 | 4. Test the connection to the database using the TCP connection as user `'sa'`. This validates that the change to `pg_hba.conf` was made correctly: 151 | 152 | psql -h 127.0.0.1 -U sa QUICKSTART_DATABASE_NAME 153 | 154 | 155 | Add the PostgreSQL Module to the Red Hat JBoss Enterprise Application Platform Server 156 | ------------------------------------------------- 157 | 158 | 1. Create the following directory structure: `EAP_HOME/modules/org/postgresql/main` 159 | 2. Download the JBDC driver from and copy it into the directory you created in the previous step. 160 | 3. In the same directory, create a file named module.xml. Copy the following contents into the file: 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | Configure the PostgreSQL Driver in the Red Hat JBoss Enterprise Application Platform Server 174 | ----------------------------------------------------------- 175 | 176 | You configure the PostgreSQL driver in the JBoss EAP server by running JBoss CLI commands. For your convenience, the quickstarts batch the commands into a `configure-postgresql.cli` script provided in the root directory of the quickstarts. 177 | 178 | ### Run the Script to Configure PostgreSQL 179 | 180 | 1. Before you begin, back up your server configuration file. 181 | * If it is running, stop the JBoss EAP server. 182 | * Backup the file: `EAP_HOME/standalone/configuration/standalone-full.xml` 183 | * After you have completed testing the quickstarts, you can replace this file to restore the server to its original configuration. 184 | 185 | 2. Start the JBoss EAP server. 186 | * If the quickstart does not provide additional instructions, type the following command. 187 | 188 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml 189 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml 190 | 191 | * If the quickstart instructs you to pass the node ID, add the `-Djboss.tx.node.id=UNIQUE_NODE_ID` argument using the appropriate node ID when you start the server. 192 | 193 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 194 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 195 | 3. Review the `configure-postgres.cli` file in the root of the quickstarts directory. This script adds the PostgreSQL driver to the datasources subsystem in the server configuration. 196 | 197 | 4. Open a new command prompt, navigate to the root directory of the quickstarts, and run the following command, replacing EAP_HOME with the path to your server: 198 | 199 | For Linux: EAP_HOME/bin/jboss-cli.sh --connect --file=configure-postgresql.cli 200 | For Windows: EAP_HOME\bin\jboss-cli.bat --connect --file=configure-postgresql.cli 201 | You should see the following result when you run the script: 202 | 203 | #1 /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource) 204 | The batch executed successfully. 205 | {"outcome" => "success"} 206 | 207 | #### Review the PostgreSQL Changes to the Server Configuration 208 | 209 | If you want to review and understand newly added XML configuration, stop the JBoss EAP server and open the `EAP_HOME/standalone/configuration/standalone-full.xml` file. 210 | 211 | The `postgresql` driver was added to the `` section in the `datasources` subsystem of the server configuration file. 212 | 213 | 214 | org.postgresql.xa.PGXADataSource 215 | 216 | 217 | 218 | Remove the PostgreSQL Configuration 219 | ------------------------------------ 220 | 221 | When you are done testing the quickstarts, you can remove the PostgreSQL configuration by running the `remove-postgresql.cli` script provided in the root directory of the quickstarts or by manually restoring the back-up copy the configuration file. 222 | 223 | ### Remove the PostgreSQL Configuration by Running the JBoss CLI Script 224 | 225 | 1. Start the JBoss EAP server. 226 | * If the quickstart does not provide additional instructions, type the following command. 227 | 228 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml 229 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml 230 | 231 | * If the quickstart instructs you to pass the node ID, add the `-Djboss.tx.node.id=UNIQUE_NODE_ID` argument using the appropriate node ID when you start the server. 232 | 233 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 234 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 235 | 2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP_HOME with the path to your server: 236 | 237 | EAP_HOME/bin/jboss-cli.sh --connect --file=remove-postgresql.cli 238 | This script removes PostgreSQL from the `datasources` subsystem in the server configuration. You should see the following result when you run the script: 239 | 240 | #1 /subsystem=datasources/jdbc-driver=postgresql:remove 241 | The batch executed successfully. 242 | {"outcome" => "success"} 243 | 244 | ### Remove the PostgreSQL Configuration Manually 245 | 246 | 1. If it is running, stop the JBoss EAP server. 247 | 2. Replace the `EAP_HOME/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. 248 | 249 | [Back to top](#configure-the-postgresql-database-for-use-with-the-quickstarts) 250 | 251 | -------------------------------------------------------------------------------- /guides/CONFIGURE_POSTGRESQL_EAP7.md: -------------------------------------------------------------------------------- 1 | Configure the PostgreSQL Database for Use with the Quickstarts 2 | =============== 3 | 4 | Summary: Some of the quickstarts require the PostgreSQL database. This guide describes how to install and configure the database for use with these quickstarts. The instructions here are the minimum required to install PostgreSQL version 9.3. If you install a later version, be sure to modify the version when you issue the commands below. More detailed instructions on how to install, configure, and start PostgreSQL can be found on the Internet. 5 | 6 | _Note_: Although the database only needs to be installed once, to help partition each quickstart we recommend using a separate database per quickstart. Where you see `QUICKSTART_DATABASE_NAME`, you should replace that with the name provided in the specific quickstart's README file. 7 | 8 | The following sections describe the steps necessary to install and configure PostgreSQL for use with the quickstarts: 9 | 10 | * [Download and Install PostgreSQL](#download-and-install-postgresql): Follow the instructions for your operating system to download and install PostgreSQL. 11 | * [Create a Database User](#create-a-database-user): Create a user for the PostgreSQL database. 12 | * [Add the PostgreSQL Module to the Red Hat JBoss Enterprise Application Platform Server](#add-the-postgresql-module-to-the-red-hat-jboss-enterprise-application-platform-server): Create a JBoss Module for the JBoss EAP server. 13 | * [Configure the PostgreSQL Driver in the Red Hat JBoss Enterprise Application Platform Server](#configure-the-postgresql-driver-in-the-red-hat-jboss-enterprise-application-platform-server): Add PostgreSQL to the JBoss EAP server configuration. 14 | * [Remove the PostgreSQL Configuration](#remove-the-postgresql-configuration): When you are done testing, remove PostgreSQL from the server configuration. 15 | 16 | _NOTE: See [Use of EAP7_HOME](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_EAP7_HOME.md) for information about the Red Hat JBoss Enterprise Application Platform installation path._ 17 | 18 | 19 | Download and Install PostgreSQL 20 | ------------------------------- 21 | 22 | Follow the instructions below for your operating system. 23 | 24 | * [Download and Install PostgreSQL on Linux](#download-and-install-postgresql-on-linux) 25 | * [Download and Install PostgreSQL on Macintosh](#download-and-install-postgresql-on-macintosh): 26 | * [Download and Install PostgreSQL on Windows](#download-and-install-postgresql-on-windows): 27 | 28 | _Note:_ The installation of PostgreSQL is a one time procedure. However, 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. 29 | 30 | ### Download and Install PostgreSQL on Linux 31 | 32 | Use the following steps to install and configure PostgreSQL on Linux. You can download the PDF installation guide here: 33 | 34 | 1. Install PostgreSQL 35 | * The yum install instructions for PostgreSQL can be found here: 36 | * Download the repository RPM from here: 37 | * To install PostgreSQL, in a command prompt type `sudo rpm -ivh RPM_FILE_NAME`, where RPM_FILE_NAME is the name of the downloaded repository RPM file, for example: 38 | 39 | sudo rpm -ivh pgdg-fedora93-9.4-1.noarch.rpm 40 | * Edit your distributions package manager definitions to exclude PostgreSQL. See the "important note" on for details on how to exclude install-and-configure-the-postgresql-database packages from the repository of the distribution. 41 | * Install _postgresql93_ and _postgres93-server_ by typing the following in a command prompt: 42 | 43 | sudo yum install postgresql93 postgresql93-server 44 | 2. Set a password for the _postgres_ user 45 | * In a command prompt, login as root and set the postgres password by typing the following commands: 46 | 47 | su 48 | passwd postgres 49 | * Choose a password 50 | 3. Configure the test database 51 | * In a command prompt, login as the _postgres_ user, navigate to the postgres directory, and initialize the database by typing: 52 | 53 | su postgres 54 | cd /usr/pgsql-9.4/bin/ 55 | ./initdb -D /var/lib/pgsql/9.4/data 56 | * Modify the `/var/lib/pgsql/9.4/data/pg_hba.conf` file to set the authentication scheme to password for tcp connections. Modify the line following the IPv4 local connections: change trust to to password. The line should look like this: 57 | 58 | host all all 127.0.0.1/32 password 59 | * Modify the `/var/lib/pgsql/9.4/data/postgresql.conf` file to allow prepared transactions and reduce the maximum number of connections 60 | 61 | max_prepared_transactions = 10 62 | max_connections = 10 63 | 64 | 4. Start the database server. 65 | * In the same command prompt, type the following: 66 | 67 | ./postgres -D /var/lib/pgsql/9.4/data 68 | * Note, this command does not release the command prompt. In the next step you need to open a new command prompt. 69 | 70 | _Note: If you do not configure the the database to automatically start as a service, you must repeat the instruction to start the database every time you reboot your machine._ 71 | 72 | 5. Create a database for the quickstart (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart) 73 | * Open a new command prompt and login again as the _postgres_ user, navigate to the postgres directory, and create the database by typing the following: 74 | 75 | su postgres 76 | cd /usr/pgsql-9.4/bin/ 77 | ./createdb QUICKSTART_DATABASE_NAME 78 | 79 | 80 | ### Download and Install PostgreSQL on Macintosh 81 | 82 | The following are the steps to install and start PostgreSQL on Mac OS X. Note that this guide covers only 'One click installer' option. 83 | 84 | 1. Install PostgreSQL using Mac OS X One click installer: 85 | 2. Allow prepared transactions: 86 | 87 | sudo su - postgres 88 | * Edit `/Library/PostgreSQL/9.4/data/postgresql.conf` to allow prepared transactions 89 | 90 | max_prepared_transactions = 10 91 | 3. Start the database server 92 | 93 | cd /Library/PostgreSQL/9.4/bin 94 | ./pg_ctl -D ../data restart 95 | 4. Create a database for the quickstart (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart) 96 | 97 | ./createdb QUICKSTART_DATABASE_NAME 98 | 5. Verify that everything works. As the _postgres_ user using the password you specified in Step 1, type the following: 99 | 100 | cd /Library/PostgreSQL/9.4/bin 101 | ./psql -U postgres 102 | At the prompt 103 | 104 | start transaction; 105 | select 1; 106 | prepare transaction 'foobar'; 107 | commit prepared 'foobar'; 108 | 109 | 110 | ### Download and Install PostgreSQL on Windows 111 | 112 | Use the following steps to install and configure PostgreSQL on Windows: 113 | 114 | 1. Install PostgreSQL using the Windows installer: 115 | 2. Enable password authentication and configure PostgreSQL to allow prepared transactions 116 | * Modify the `C:\Program Files\PostgreSQL\9.4\data\pg_hba.conf` file to set the authentication scheme to password for tcp connections. Modify the line following the IPv4 local connections: change trust to to password. The line should look like this: 117 | 118 | host all all 127.0.0.1/32 password` 119 | * Modify the `C:\Program Files\PostgreSQL\9.4\data\postgresql.conf` file to allow prepared transactions and reduce the maximum number of connections: 120 | 121 | max_prepared_transactions = 10 122 | max_connections = 10 123 | 3. Start the database server 124 | * Choose Start -> All Programs -> PostgreSQL 9.4\pgAdmin III 125 | * Server Groups -> Servers (1) -> PostgreSQL 9.4 (localhost:5432) 126 | * Right click -> Stop Service 127 | * Right click -> Start Service 128 | 4. Create a database for the quickstart (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart) 129 | * Open a command prompt and type the following: 130 | 131 | cd C:\Program Files\PostgreSQL\9.4\bin\ 132 | createdb.exe -U postgres QUICKSTART_DATABASE_NAME 133 | 134 | 135 | Create a Database User 136 | ---------------------- 137 | 138 | 1. Make sure the PostgreSQL bin directory is in your PATH. 139 | * Open a command prompt and change to the root directory 140 | psql 141 | * If you see an error that 'psql' is not a recognized command, you need to add the PostgreSQL bin directory to your PATH environment variable. 142 | 2. As the _postgres_ user, start the PostgreSQL interactive terminal by typing the following command: 143 | 144 | psql -U postgres 145 | 3. Create the user sa with password sa and all privileges on the database by typing the following commands (as noted above, replace QUICKSTART_DATABASE_NAME with the name provided in the particular quickstart): 146 | 147 | create user sa with password 'sa'; 148 | grant all privileges on database "QUICKSTART_DATABASE_NAME" to sa; 149 | \q 150 | 4. Test the connection to the database using the TCP connection as user `'sa'`. This validates that the change to `pg_hba.conf` was made correctly: 151 | 152 | psql -h 127.0.0.1 -U sa QUICKSTART_DATABASE_NAME 153 | 154 | 155 | Add the PostgreSQL Module to the Red Hat JBoss Enterprise Application Platform Server 156 | ------------------------------------------------- 157 | 158 | 1. Create the following directory structure: `EAP7_HOME/modules/org/postgresql/main` 159 | 2. Download the `JDBC41` version of JBDC driver from and save it into the directory you created in the previous step. It should be named something like `postgresql-9.4-1102.jdbc41.jar`. 160 | 3. In the same directory, create a file named module.xml. Copy the following contents into the file, replacing the "####" in the JAR name with the revision that matches the downloaded JAR name. 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | Configure the PostgreSQL Driver in the Red Hat JBoss Enterprise Application Platform Server 174 | ----------------------------------------------------------- 175 | 176 | You configure the PostgreSQL driver in the JBoss EAP server by running JBoss CLI commands. For your convenience, the quickstarts batch the commands into a `configure-postgresql.cli` script provided in the root directory of the quickstarts. 177 | 178 | ### Run the Script to Configure PostgreSQL 179 | 180 | 1. Before you begin, back up your server configuration file. 181 | * If it is running, stop the JBoss EAP server. 182 | * Backup the file: `EAP7_HOME/standalone/configuration/standalone-full.xml` 183 | * After you have completed testing the quickstarts, you can replace this file to restore the server to its original configuration. 184 | 185 | 2. Start the JBoss EAP server. 186 | * If the quickstart does not provide additional instructions, type the following command. 187 | 188 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml 189 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml 190 | 191 | * If the quickstart instructs you to pass the node ID, add the `-Djboss.tx.node.id=UNIQUE_NODE_ID` argument using the appropriate node ID when you start the server. 192 | 193 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 194 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 195 | 3. Review the `configure-postgres.cli` file in the root of the quickstarts directory. This script adds the PostgreSQL driver to the datasources subsystem in the server configuration. 196 | 197 | 4. Open a new command prompt, navigate to the root directory of the quickstarts, and run the following command, replacing EAP7_HOME with the path to your server: 198 | 199 | For Linux: EAP7_HOME/bin/jboss-cli.sh --connect --file=configure-postgresql.cli 200 | For Windows: EAP7_HOME\bin\jboss-cli.bat --connect --file=configure-postgresql.cli 201 | You should see the following result when you run the script: 202 | 203 | #1 /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource) 204 | The batch executed successfully. 205 | 206 | #### Review the PostgreSQL Changes to the Server Configuration 207 | 208 | If you want to review and understand newly added XML configuration, stop the JBoss EAP server and open the `EAP7_HOME/standalone/configuration/standalone-full.xml` file. 209 | 210 | The `postgresql` driver was added to the `` section in the `datasources` subsystem of the server configuration file. 211 | 212 | 213 | org.postgresql.xa.PGXADataSource 214 | 215 | 216 | 217 | Remove the PostgreSQL Configuration 218 | ------------------------------------ 219 | 220 | When you are done testing the quickstarts, you can remove the PostgreSQL configuration by running the `remove-postgresql.cli` script provided in the root directory of the quickstarts or by manually restoring the back-up copy the configuration file. 221 | 222 | ### Remove the PostgreSQL Configuration by Running the JBoss CLI Script 223 | 224 | 1. Start the JBoss EAP server. 225 | * If the quickstart does not provide additional instructions, type the following command. 226 | 227 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml 228 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml 229 | 230 | * If the quickstart instructs you to pass the node ID, add the `-Djboss.tx.node.id=UNIQUE_NODE_ID` argument using the appropriate node ID when you start the server. 231 | 232 | For Linux: EAP_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 233 | For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID 234 | 2. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing EAP7_HOME with the path to your server: 235 | 236 | EAP7_HOME/bin/jboss-cli.sh --connect --file=remove-postgresql.cli 237 | This script removes PostgreSQL from the `datasources` subsystem in the server configuration. You should see the following result when you run the script: 238 | 239 | #1 /subsystem=datasources/jdbc-driver=postgresql:remove 240 | The batch executed successfully. 241 | {"outcome" => "success"} 242 | 243 | ### Remove the PostgreSQL Configuration Manually 244 | 245 | 1. If it is running, stop the JBoss EAP server. 246 | 2. Replace the `EAP7_HOME/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. 247 | 248 | [Back to top](#configure-the-postgresql-database-for-use-with-the-quickstarts) 249 | 250 | -------------------------------------------------------------------------------- /guides/USE_JBDS.md: -------------------------------------------------------------------------------- 1 | # Use Red Hat Red Hat CodeReady Studio or Eclipse to Run the Quickstarts 2 | 3 | 4 | You can deploy many of the quickstarts and run the Arquillian tests from Eclipse using JBoss tools. However, the EJB Client currently has limited support in the Eclipse Web Tools Platform (WTP). For that reason, some quickstarts that ship with Red Hat JBoss Enterprise Application Platform are not supported in Red Hat CodeReady Studio. 5 | 6 | This guide includes the following information. 7 | 8 | * [Where to Find Information](#where-to-find-information) 9 | * [Important Special Instructions](#important-special-instructions) 10 | * [Deploying and Undeploying Quickstarts and Running the Arquillian Tests](#deploying-and-undeploying-quickstarts-and-running-the-arquillian-tests) 11 | * [Deploy and Undeploy a Quickstart WAR Project](#deploy-and-undeploy-a-quickstart-war-project) 12 | * [Deploy and Undeploy a Quickstart EAR Project](#deploy-and-undeploy-a-quickstart-ear-project) 13 | * [Deploy and Undeploy a Quickstart Containing Server and Java Client Projects](#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects) 14 | * [Deploy and Undeploy a Quickstart Consisting of Multiple Interdependent Projects](#deploy-and-undeploy-a-quickstart-consisting-of-multiple-interdependent-projects) 15 | * [Run a Quickstart's Arquillian Tests](#run-a-quickstarts-arquillian-tests) 16 | * [Known Issues for JBoss EAP Quickstarts](#known-issues-for-jboss-eap-quickstarts) 17 | 18 | ## Where to Find Information 19 | 20 | See [Setting Up the Development Environment](https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#setting_up_the_development_environment) in the _Development Guide_ for JBoss EAP for information about how to download and install Red Hat CodeReady Studio and how to add the JBoss EAP server to the configuration. 21 | 22 | For information about how to configure Maven and Red Hat CodeReady Studio for use with the quickstarts, see [Configure Maven for Use with Red Hat Red Hat CodeReady Studio](https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/development_guide/#configure_maven_for_use_with_red_hat_jboss_developer_studio) in the _Development Guide_ for JBoss EAP. 23 | 24 | For information about how to deploy and run the quickstarts and to run the Arquillian tests in Red Hat CodeReady Studio, see [Run the Quickstarts in Red Hat CodeReady Studio](https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/getting_started_guide/index#using_the_quickstart_examples) in the _Getting Started Guide_ for JBoss EAP. 25 | 26 | For instructions to run the Arquillian tests using the Maven command line, see [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests). 27 | 28 | See [Red Hat Red Hat CodeReady Studio](https://developers.redhat.com/products/codeready-studio/overview/ "Get Started") on the Red Hat Developer Program website for additional information. 29 | 30 | ## Important Special Instructions 31 | 32 | 1. Your quickstart project folder must be located outside of your IDE workspace. If your quickstart project folder is located within the IDE workspace when you import it into Red Hat CodeReady Studio, the IDE generates an invalid project name and an invalid WAR archive name. Be sure your quickstart project folder is located outside the IDE workspace before you begin! 33 | 34 | 2. Be sure to follow the instructions in the quickstart `README.md` file to add any required application users or make the appropriate server configuration changes. 35 | 36 | 3. More complex quickstarts may require special instructions to run properly in Red Hat CodeReady Studio. This document describes some of these special situations. 37 | 38 | 4. If you see errors or warnings when you import or run a quickstart, see the list of [Known Issues for JBoss EAP Quickstarts](#known-issues-for-jboss-eap-quickstarts) below for an explanation. 39 | 40 | ## Deploying and Undeploying Quickstarts and Running the Arquillian Tests 41 | 42 | ### Deploy and Undeploy a Quickstart WAR Project 43 | 44 | For WAR projects, you simply deploy the project. 45 | 46 | 1. Right-click on the project, and choose `Run As` --> `Run on Server`. 47 | 2. Choose the server and click `Finish`. 48 | 3. This starts the server, deploys the application, and opens a browser window that accesses the running application. 49 | 4. To undeploy the project, right-click on the project and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 50 | 51 | 52 | ### Deploy and Undeploy a Quickstart EAR Project 53 | 54 | For EAR projects, you simply deploy the EAR subproject. The subproject name is usually appended with "-ear-ear". 55 | 56 | 1. Right-click on the EAR subproject, and choose `Run As` --> `Run on Server`. 57 | 2. Choose the server and click `Finish`. 58 | 3. This starts the server, deploys the application, and opens a browser window that accesses the running application. 59 | 4. To undeploy the project, right-click on the EAR subproject and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 60 | 61 | ### Deploy and Undeploy a Quickstart Containing Server and Java Client Projects 62 | 63 | You must deploy the server project before running the client. More detailed instructions be found in the `shopping-cart` quickstart. 64 | 65 | 1. Right-click on the server project and choose `Run As` --> `Run on Server`. 66 | 2. Right-click on the Java client project and choose `Run As` --> `Java Application`. In the `Select Java Application` window, choose the client class and click `OK`. 67 | 3. The client output displays in the `Console` window. 68 | 4. To undeploy the project, right-click on the server subproject and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 69 | 70 | ### Deploy and Undeploy a Quickstart Consisting of Multiple Interdependent Projects 71 | 72 | To deploy a quickstart that consists of multiple projects containing interdependencies on each other without opening a browser and running the application, use the following steps. More detailed instructions be found in the `inter-app` quickstart. 73 | 74 | 1. In the `Servers` tab, right-click on the JBoss EAP server and choose `Start`. 75 | 2. Deploy the projects in one of the following ways. 76 | * `Drag and Drop` mode: Click to multi-select the projects, then drag and drop them on the running JBoss EAP server. This deploys the projects to the server without opening the browser. 77 | * `Batch` mode: In the `Servers` tab, right-click on the server and choose `Add and Remove`. If the quickstart projects are the only projects in the list, click `Add All`. Otherwise, use multi-select to select them and click `Add`. Then click `Finish`. 78 | 3. Right-click on the individual projects and choose `Run As` --> `Run on Server`. A browser window appears that accesses the running application. 79 | 4. To undeploy the projects, right-click on the subprojects in the reverse order of how they were deployed, and choose `Run As` --> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. 80 | 81 | 82 | ### Run a Quickstart's Arquillian Tests 83 | 84 | You can run the Arquillian tests that are included with many of the JBoss EAP 7.3 quickstarts by following the steps below. See [Run the Arquillian Tests](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests) for more complete information about running the Arquillian tests and for instructions for older versions of the quickstarts. 85 | 86 | 1. In the `Servers` tab, right-click on the JBoss EAP server and choose `Start`. 87 | 2. Right-click on the quickstart project in the `Project Explorer` tab and choose `Run As` -> `Maven Build`. 88 | 3. Enter `clean verify -Parq-remote` in the `Goals` input field and click `Run`. 89 | 90 | ## Known Issues for JBoss EAP Quickstarts 91 | 92 | You may see one or more of the following errors or warnings when you import quickstart projects into Red Hat CodeReady Studio. 93 | 94 | * **JRE System Library Problem: Build path specifies execution environment JavaSE-1.6. There are no JREs installed in the workspace that are strictly compatible with this environment.** 95 | 96 | The JBoss EAP 6 quickstarts demonstrate Java EE 6 features and are built on Java SE 6. Red Hat CodeReady Studio requires Java 8 to run, but is still capable of launching runtimes with various versions of Java. You can ignore this warning, or you can install a JDK 6 on your machine and add it to the Eclipse Java Runtime Environment by choosing `Preferences` --> `Java` --> `Installed JREs`. 97 | 98 | * **JPA Problem: No connection specified for project. No database-specific validation will be performed.** 99 | 100 | If the quickstart project uses JPA to access a database, you will see the following warning when you import the project into Eclipse. You can ignore this warning as it only applies to the local connection in the Eclipse development environment and does not affect the JBoss EAP runtime deployment. To eliminate this warning, you must configure the database connection in the Eclipse project settings. 101 | 102 | * **Failed while installing JPA 2.0. org.osgi.service.prefs.BackingStoreException: Resource '/PROJECT_NAME/SUBPROJECT_NAME/.settings' does not exist** 103 | 104 | This error can occur with quickstart projects that are composed of multiple subprojects. This is a known issue. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=459810. 105 | 106 | * **Maven Configuration Problem: Project configuration is not up-to-date with pom.xml. Run Maven->Update Project or use Quick Fix.** 107 | 108 | This error can occur with quickstart projects that are composed of multiple subprojects. The import of a project on one thread may trigger Eclipse to refresh a project on another thread making the project state appear to be inconsistent. To resolve the errors, right-click on the parent project in Red Hat CodeReady Studio and choose `Maven` --> `Update Project`. Make sure all the projects are selected and click `OK`. This should resolve the errors. 109 | 110 | * **Maven Configuration Problem: Endorsed directory QUICKSTART_HOME/some-path/target/endorsed' is missing. You may need to a perform a Maven command line build in order to create it.** 111 | 112 | This error occurs if endorsed directories are defined in the `maven-compiler-plugin` configuration of the quickstart POM file. To resolve the error, right-click on error in the Red Hat CodeReady Studio `Problems` window and choose `Quick Fix`. This opens a window with the fix `Run 'mvn process-sources' to execute dependency:copy` selected. Click `Finish` to resolve the error. For more information, see [JBoss Maven Integration](http://docs.jboss.org/tools/whatsnew/maven/maven-news-3.3.0.CR1.html). 113 | 114 | * **Maven pom Loading Problem: Overriding managed version 1.0.2.Final for wildfly-maven-plugin pom.xml.** 115 | 116 | You can ignore this m2e warning. It can occur in child projects where the dependency versions are defined in the parent POM file. For more information, see [Bug 346725 - "Overriding managed version" in pom.xml should not be a warning severity ](https://bugs.eclipse.org/bugs/show_bug.cgi?id=346725). 117 | 118 | * **XML Problem: Referenced file contains errors (jar:file:PATH-TO-jbdevstudio/studio/plugins/org.jboss.tools.as.catalog_3.0.0.Final-v20141016-1911-B95.jar!/schema/xsd/jboss-ejb3-2_0.xsd). For more information, right click on the message in the Problems View and select "Show Details..."** 119 | 120 | You can ignore this error. This is a known issue with the `jboss-ejb3-spec-2_0.xsd` schema file. See . 121 | 122 | * **XML Problem: Referenced file contains errors (jar:file:/PATH-TO-jbdevstudio/studio/plugins/org.jboss.tools.as.catalog_3.0.1.Final-v20141209-0156-B106.jar!/schema/xsd/jboss-ejb3-spec-2_0.xsd). For more information, right click on the message in the Problems View and select "Show Details..."** 123 | 124 | You can ignore this error. This is a known issue with the `jboss-ejb3-spec-2_0.xsd` schema file. See . 125 | 126 | * **XML Problem: cvc-complex-type.2.4.a: Invalid content was found starting with element 'iiop:iiop'. One of '{"http://java.sun.com/xml/ns/javaee":security-role, "http://java.sun.com/xml/ns/javaee":method-permission, "http://java.sun.com/xml/ns/javaee":container-transaction, "http://java.sun.com/xml/ns/javaee":interceptor-binding, "http://java.sun.com/xml/ns/javaee":message-destination, "http://java.sun.com/xml/ns/javaee":exclude-list, "http://java.sun.com/xml/ns/javaee":application-exception, "http://java.sun.com/xml/ns/javaee":assembly-descriptor-entry}' is expected.** 127 | 128 | You can ignore this error. This is a known issue with the ` jboss-ejb-iiop_1_0.xsd` schema file. See and . 129 | 130 | * **XML Problem: cvc-complex-type.2.4.a: Invalid content was found starting with element 'iiop:binding-name'. One of '{"urn:iiop":ejb-name}' is expected.** 131 | 132 | You can ignore this error. This is a known issue with the ` jboss-ejb-iiop_1_0.xsd` schema file. See and . 133 | 134 | * **XML Problem: cvc-complex-type.2.4.a: Invalid content was found starting with element 'jee:interceptor-binding'. One of '{"http://java.sun.com/xml/ns/javaee":description, "http://java.sun.com/xml/ns/javaee":ejb-name}' is expected.** 135 | 136 | You can ignore this error. This is a known issue with the `jboss-ejb-container-interceptors_1_0.xsd` schema file. See . 137 | 138 | * **WSDL Problem: WS-I: (AP2901) A description uses neither the WSDL MIME Binding as described in WSDL 1.1 Section 5 nor WSDL SOAP binding as described in WSDL 1.1 Section 3 on each of the wsdl:input or wsdl:output elements of a wsdl:binding.** 139 | 140 | You can ignore this error. This is a known Eclipse issue. See . To turn off WSDL validation in Red Hat CodeReady Studio, choose `Windows` --> `Preferences`, select `Validation`, find `WSDL Validator` in the list, and uncheck the `Manual` and `Build` selections. 141 | 142 | * **WSDL Problem: WS-I: (BP2402) The wsdl:binding element does not use a soapbind:binding element as defined in section "3 SOAP Binding." of the WSDL 1.1 specification.** 143 | 144 | You can ignore this error. This is a known Eclipse issue. See . To turn off WSDL validation in Red Hat CodeReady Studio, choose `Windows` --> `Preferences`, select `Validation`, find `WSDL Validator` in the list, and uncheck the `Manual` and `Build` selections. 145 | 146 | * **EJB Problem: An EJB module must contain one or more enterprise beans.** 147 | 148 | Eclipse Web Tools Platform (WTP) can not deploy simple JARs to the JBoss EAP server. For this reason, quickstart subprojects that would normally deploy shared artifacts as JARs deploy them instead as EJB JARs. You can ignore this warning. 149 | 150 | * **Knowledge Base Builder Problem: JBoss Tools Knowledge Base problem: Nature is not installed on required Java project ``. Use Quick Fix to include artifacts declared in that project into Content Assistant and Validation.** 151 | 152 | Quickstarts that require Knowledge Base capabilities to be enabled on the project display this warning. To resolve it, right-click on the warning message in the in the Red Hat CodeReady Studio `Problems` window and choose `Quick Fix`. This opens a window with the fix `Enable Knowledge Base capabilities on project ` selected. Make sure all projects are selected and click `Finish` to resolve the warning. 153 | 154 | * **JPA Problem: Console configuration QUICKSTART_HOME does not exist. Hibernate specific validation and content assist will be limited.** 155 | 156 | This warning is intermittent and can occur with any quickstart project that uses Hibernate. This is a known issue. For more information, see . 157 | -------------------------------------------------------------------------------- /guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc: -------------------------------------------------------------------------------- 1 | [[configure_the_postgresql_database_for_use_with_the_quickstarts]] 2 | 3 | = Configure the PostgreSQL Database for Use with the Quickstarts 4 | 5 | [[configure_the_postgresql_database_summary]] 6 | == Summary 7 | 8 | Some of the quickstarts require the PostgreSQL database. This guide describes how to install and configure the database for use with these quickstarts. The instructions here are the minimum required to install PostgreSQL version 9.6. If you install a later version, be sure to modify the version when you issue the commands below. More detailed instructions on how to install, configure, and start PostgreSQL can be found on the Internet. 9 | 10 | NOTE: Although the database only needs to be installed once, to help partition each quickstart, Red Hat recommends using a separate database for each quickstart. Where you see `__QUICKSTART_DATABASE_NAME__` in the instructions, you should replace that with the name provided in the specific quickstart's `README` file. 11 | 12 | The following sections describe the steps necessary to install and configure PostgreSQL for use with the quickstarts: 13 | 14 | . xref:download_and_install_postgresql[Download and Install PostgreSQL] 15 | + 16 | Follow the instructions for your operating system to download and install PostgreSQL. 17 | . xref:create_a_database_user[Create a Database User] 18 | + 19 | Create a user for the PostgreSQL database. 20 | . xref:add_the_postgres_module_to_the_jboss_eap_server[Add the PostgreSQL Module to the JBoss EAP] 21 | + 22 | Create a JBoss Module for the JBoss EAP server. 23 | . xref:configure_the_postgresql_driver_in_the_jboss_eap_server[Configure the PostgreSQL Driver in the JBoss EAP Server] 24 | + 25 | Add PostgreSQL to the JBoss EAP server configuration. 26 | 27 | . xref:remove_the_postgresql_configuration[Remove the PostgreSQL Configuration] 28 | + 29 | When you are done testing, remove PostgreSQL from the server configuration. 30 | 31 | NOTE: See link:USE_OF_EAP_HOME.adoc[Use of __EAP_HOME__] for information about the JBoss EAP installation path. 32 | 33 | [[download_and_install_postgresql]] 34 | == Download and Install PostgreSQL 35 | 36 | Follow the instructions below for your operating system. 37 | 38 | * xref:download-and-install-postgresql-on-linux[Download and Install PostgreSQL on Linux] 39 | * xref:download-and-install-postgresql-on-macintosh[Download and Install PostgreSQL on Macintosh] 40 | * xref:download-and-install-postgresql-on-windows[Download and Install PostgreSQL on Windows] 41 | 42 | NOTE: The installation of PostgreSQL is a one time procedure. However, unless you have set up the database to automatically start as a service, you must repeat the instructions for your operating system to start the database server every time you reboot your machine. 43 | 44 | [[download_and_install_postgresql_on_linux]] 45 | === Download and Install PostgreSQL on Linux 46 | 47 | Follow these steps to install and configure PostgreSQL on Linux. You can download the PDF installation guide here: http://yum.postgresql.org/files/PostgreSQL-RPM-Installation-PGDG.pdf 48 | 49 | . Install PostgreSQL 50 | 51 | * The yum install instructions for PostgreSQL can be found here: http://yum.postgresql.org/howtoyum.php/ 52 | 53 | * Download the repository RPM from here: http://yum.postgresql.org/repopackages.php/ 54 | 55 | * To install PostgreSQL, open a terminal and type `sudo rpm -ivh __RPM_FILE_NAME__`, where __RPM_FILE_NAME__ is the name of the downloaded repository RPM file, for example: 56 | + 57 | [source,options="nowrap"] 58 | ---- 59 | $ sudo rpm -ivh pgdg-fedora96-9.6-3.noarch.rpm 60 | ---- 61 | * Edit your distributions package manager definitions to exclude PostgreSQL. See the "important note" on http://yum.postgresql.org/howtoyum.php for details on how to exclude install-and-configure-the-postgresql-database packages from the repository of the distribution. 62 | * Install _postgresql96_ and _postgres96-server_ by typing the following in a terminal: 63 | + 64 | [source,options="nowrap"] 65 | ---- 66 | $ sudo yum install postgresql96 postgresql96-server 67 | ---- 68 | 69 | . Set a password for the `postgres` user. 70 | 71 | * In a terminal, login as root and set the `postgres` password by typing the following commands: 72 | + 73 | [source,options="nowrap"] 74 | ---- 75 | $ su 76 | passwd postgres 77 | ---- 78 | * Choose a password 79 | 80 | . Configure the test database. 81 | 82 | * In a terminal, login as the `postgres` user, navigate to the postgres directory, and initialize the database by typing: 83 | + 84 | [source,options="nowrap"] 85 | ---- 86 | $ su postgres 87 | # cd /usr/pgsql-9.6/bin/ 88 | # ./initdb -D /var/lib/pgsql/9.6/data 89 | ---- 90 | 91 | * Modify the `/var/lib/pgsql/9.6/data/pg_hba.conf` file to set the authentication scheme to `password` for TCP connections. Modify the line following the IPv4 local connections, changing `trust` to to `password`. The line should look like this: 92 | + 93 | [source,options="nowrap"] 94 | ---- 95 | host all all 127.0.0.1/32 password 96 | ---- 97 | * Modify the `/var/lib/pgsql/9.6/data/postgresql.conf` file to allow prepared transactions and reduce the maximum number of connections 98 | + 99 | [source,options="nowrap"] 100 | ---- 101 | max_prepared_transactions = 10 102 | max_connections = 10 103 | ---- 104 | 105 | . Start the database server. 106 | 107 | * In the same terminal, type the following command. This command does not release the terminal. In the next step you need to open a new terminal. 108 | + 109 | [source,options="nowrap"] 110 | ---- 111 | $ ./postgres -D /var/lib/pgsql/9.6/data 112 | ---- 113 | + 114 | NOTE: If you do not configure the the database to automatically start as a service, you must repeat this instruction to start the database every time you reboot your machine. 115 | 116 | . Create a database for the quickstart. As noted above, replace `__QUICKSTART_DATABASE_NAME__` with the database name provided in the quickstart `README` file. 117 | + 118 | Open a new terminal and log in again as the `postgres` user. Navigate to the `postgres/` directory, and create the database by typing the following: 119 | + 120 | [source,subs="+quotes",options="nowrap"] 121 | ---- 122 | $ su postgres 123 | # cd /usr/pgsql-9.6/bin/ 124 | # ./createdb __QUICKSTART_DATABASE_NAME__ 125 | ---- 126 | 127 | [[download_and_install_postgresql_on_macintosh]] 128 | === Download and Install PostgreSQL on Macintosh 129 | 130 | Follow these steps to install and start PostgreSQL on Mac OS X. Note that this guide covers only 'One click installer' option. 131 | 132 | . Install PostgreSQL using the Mac OS X One click installer: http://www.postgresql.org/download/macosx 133 | . Allow prepared transactions. 134 | 135 | * Log in as the `postgres` user. 136 | + 137 | [source,options="nowrap"] 138 | ---- 139 | sudo su - postgres 140 | ---- 141 | 142 | * Edit the `/Library/PostgreSQL/9.6/data/postgresql.conf` file to allow prepared transactions 143 | + 144 | [source,options="nowrap"] 145 | ---- 146 | max_prepared_transactions = 10 147 | ---- 148 | . Start the database server 149 | + 150 | [source,options="nowrap"] 151 | ---- 152 | cd /Library/PostgreSQL/9.6/bin 153 | ./pg_ctl -D ../data restart 154 | ---- 155 | 156 | . Create a database for the quickstart. As noted above, replace `__QUICKSTART_DATABASE_NAME__` with the name provided in the quickstart `README` file. 157 | + 158 | [source,subs="+quotes",options="nowrap"] 159 | ---- 160 | ./createdb __QUICKSTART_DATABASE_NAME__ 161 | ---- 162 | . Verify that everything works. As the `postgres` user using the password you specified in Step 1, type the following: 163 | + 164 | [source,options="nowrap"] 165 | ---- 166 | cd /Library/PostgreSQL/9.6/bin 167 | ./psql -U postgres 168 | ---- 169 | + 170 | At the prompt, type the following commands: 171 | + 172 | [source,options="nowrap"] 173 | ---- 174 | start transaction; 175 | select 1; 176 | prepare transaction 'foobar'; 177 | commit prepared 'foobar'; 178 | ---- 179 | 180 | [[download_and_install_postgresql_on_windows]] 181 | === Download and Install PostgreSQL on Windows 182 | 183 | Follow these steps to install and configure PostgreSQL on Windows. 184 | 185 | . Install PostgreSQL using the Windows installer: http://www.postgresql.org/download/windows 186 | . Enable password authentication and configure PostgreSQL to allow prepared transactions. 187 | 188 | * Modify the `C:\Program Files\PostgreSQL\9.6\data\pg_hba.conf` file to set the authentication scheme to `password` for TCP connections. Modify the line following the IPv4 local connections to change `trust` to `password`. The line should look like this: 189 | + 190 | [source,options="nowrap"] 191 | ---- 192 | host all all 127.0.0.1/32 password 193 | ---- 194 | * Modify the `C:\Program Files\PostgreSQL\9.6\data\postgresql.conf` file to allow prepared transactions and reduce the maximum number of connections: 195 | + 196 | [source,options="nowrap"] 197 | ---- 198 | max_prepared_transactions = 10 199 | max_connections = 10 200 | ---- 201 | 202 | . Start the database server. 203 | 204 | * Choose *Start* -> *All Programs* -> *PostgreSQL 9.6\pgAdmin III* 205 | * Server *Groups* -> *Servers (1)* -> *PostgreSQL 9.6 (localhost:5432)* 206 | * Right click -> *Stop Service* 207 | * Right click -> *Start Service* 208 | 209 | . Create a database for the quickstart. As noted above, replace `__QUICKSTART_DATABASE_NAME__` with the name provided in the quickstart `README` file. 210 | + 211 | Open a terminal and type the following: 212 | + 213 | [source,subs="+quotes",options="nowrap"] 214 | ---- 215 | > cd C:\Program Files\PostgreSQL\9.6\bin\ 216 | > createdb.exe -U postgres __QUICKSTART_DATABASE_NAME__ 217 | ---- 218 | 219 | [[create_a_database_user]] 220 | == Create a Database User 221 | 222 | . Make sure the PostgreSQL `bin/` directory is in your PATH. 223 | * Open a terminal, change to the root directory, and type the following command. 224 | + 225 | [source,options="nowrap"] 226 | ---- 227 | $ psql 228 | ---- 229 | + 230 | NOTE: If you see an error that 'psql' is not a recognized command, you need to add the PostgreSQL `bin/`` directory to your PATH environment variable. 231 | 232 | . As the `postgres` user, start the PostgreSQL interactive terminal by typing the following command. 233 | + 234 | [source,options="nowrap"] 235 | ---- 236 | $ psql -U postgres 237 | ---- 238 | . Create the user `sa` with password `sa` and all privileges on the database by typing the following commands. As noted above, replace `__QUICKSTART_DATABASE_NAME__` with the name provided in the quickstart `README` file. 239 | + 240 | [source,subs="+quotes",options="nowrap"] 241 | ---- 242 | create user sa with password 'sa'; 243 | grant all privileges on database __QUICKSTART_DATABASE_NAME__ to sa; 244 | \q 245 | ---- 246 | 247 | . Test the connection to the database using the TCP connection as user `sa`. This validates that the change to `pg_hba.conf` file was made correctly: 248 | + 249 | [source,subs="+quotes",options="nowrap"] 250 | ---- 251 | $ psql -h 127.0.0.1 -U sa __QUICKSTART_DATABASE_NAME__ 252 | ---- 253 | 254 | [[add_the_postgres_module_to_the_jboss_eap_server]] 255 | == Add the PostgreSQL Module to the JBoss EAP 256 | 257 | . Create the following directory structure: `__EAP_HOME__/modules/org/postgresql/main` 258 | 259 | . Download the `JDBC41` version of JBDC driver from http://jdbc.postgresql.org/download.html and save it into the directory you created in the previous step. It should be named something like `postgresql-42.1.4.jre7.jar`. 260 | . In the same directory, create a file named `module.xml`. Copy the following contents into the file, replacing the JAR name with the revision that matches the downloaded JAR name. 261 | + 262 | [source,xml,options="nowrap"] 263 | ---- 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | ---- 275 | 276 | [[configure_the_postgresql_driver_in_the_jboss_eap_server]] 277 | == Configure the PostgreSQL Driver in the JBoss EAP Server 278 | 279 | You configure the PostgreSQL driver in the JBoss EAP server by running management CLI commands. For your convenience, the quickstarts batch the commands into a `configure-postgresql.cli` script provided in the root directory of the quickstarts. 280 | 281 | [[configure_the_postgresql_driver_using_management_cli_script]] 282 | === Run the Management CLI Script to Configure PostgreSQL 283 | 284 | . Before you begin, back up your server configuration file. 285 | 286 | * If it is running, stop the JBoss EAP server. 287 | * Back up the configuration file: `__EAP_HOME__/standalone/configuration/standalone-full.xml` 288 | * After you have completed testing the quickstarts, you can replace this file to restore the server to its original configuration. 289 | 290 | . Start the JBoss EAP server. 291 | 292 | * If the quickstart does not provide additional instructions, type the following command. 293 | ** For Linux: `$ __EAP_HOME__/bin/standalone.sh -c standalone-full.xml` 294 | ** For Windows: `> __EAP_HOME__\bin\standalone.bat -c standalone-full.xml` 295 | 296 | * If the quickstart instructs you to pass the node ID, add the `-Djboss.tx.node.id=__UNIQUE_NODE_ID__` argument using the appropriate node ID when you start the server. 297 | ** For Linux: `$ __EAP_HOME__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=__UNIQUE_NODE_ID__` 298 | ** For Windows: `> __EAP_HOME__\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=__UNIQUE_NODE_ID__` 299 | 300 | . Review the `configure-postgres.cli` file in the root of the quickstarts directory. This script adds the PostgreSQL driver to the datasources subsystem in the server configuration. 301 | 302 | . Open a new terminal, navigate to the root directory of the quickstarts, and run the following command, replacing __EAP_HOME__ with the path to your server: 303 | * For Linux: `$ __EAP_HOME__/bin/jboss-cli.sh --connect --file=configure-postgresql.cli` 304 | * For Windows: `> __EAP_HOME__\bin\jboss-cli.bat --connect --file=configure-postgresql.cli` 305 | 306 | . You should see the following result when you run the script: 307 | + 308 | [source,subs="+quotes",options="nowrap"] 309 | ---- 310 | #1 /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource) 311 | The batch executed successfully. 312 | ---- 313 | 314 | [[review_the_postgresql_changes_to_the_server_configuration]] 315 | ==== Review the PostgreSQL Changes to the Server Configuration 316 | 317 | If you want to review and understand newly added XML configuration, stop the JBoss EAP server and open the `__EAP_HOME__/standalone/configuration/standalone-full.xml` file. 318 | 319 | The `postgresql` driver was added to the `` section in the `datasources` subsystem of the server configuration file. 320 | 321 | [source,xml,options="nowrap"] 322 | ---- 323 | 324 | org.postgresql.xa.PGXADataSource 325 | 326 | ---- 327 | 328 | [[remove_the_postgresql_configuration]] 329 | == Remove the PostgreSQL Configuration 330 | 331 | When you are done testing the quickstarts, you can remove the PostgreSQL configuration by running the `remove-postgresql.cli` script provided in the root directory of the quickstarts or by manually restoring the back-up copy the configuration file. 332 | 333 | [[remove_the_postgresql_configuration_using_cli]] 334 | === Remove the PostgreSQL Configuration by Running the Management CLI Script 335 | 336 | . Start the JBoss EAP server. 337 | 338 | * If the quickstart does not provide additional instructions, type the following command. 339 | ** For Linux: `$ __EAP_HOME__/bin/standalone.sh -c standalone-full.xml` 340 | ** For Windows: `> __EAP_HOME__\bin\standalone.bat -c standalone-full.xml` 341 | 342 | * If the quickstart instructs you to pass the node ID, add the `-Djboss.tx.node.id=__UNIQUE_NODE_ID__` argument using the appropriate node ID when you start the server. 343 | ** For Linux: `$ __EAP_HOME__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=__UNIQUE_NODE_ID__` 344 | ** For Windows: `> __EAP_HOME__\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=__UNIQUE_NODE_ID__` 345 | 346 | . Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing __EAP_HOME__ with the path to your server: 347 | + 348 | [source,subs="+quotes",options="nowrap"] 349 | ---- 350 | $ __EAP_HOME__/bin/jboss-cli.sh --connect --file=remove-postgresql.cli 351 | ---- 352 | + 353 | This script removes PostgreSQL from the `datasources` subsystem in the server configuration. You should see the following result when you run the script: 354 | + 355 | [source,subs="+quotes",options="nowrap"] 356 | ---- 357 | #1 /subsystem=datasources/jdbc-driver=postgresql:remove 358 | The batch executed successfully. 359 | {"outcome" => "success"} 360 | ---- 361 | 362 | [[remove_the_postgresql_configuration_manually]] 363 | === Remove the PostgreSQL Configuration Manually 364 | 365 | . If it is running, stop the JBoss EAP server. 366 | . Replace the `__EAP_HOME__/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. 367 | 368 | xref:configure_the_postgresql_database_for_use_with_the_quickstarts[Back to top] 369 | -------------------------------------------------------------------------------- /guides/USE_JBDS.adoc: -------------------------------------------------------------------------------- 1 | :ProductName: Red Hat JBoss Enterprise Application Platform 2 | :ProductShortName: JBoss EAP 3 | // Documentation publishing attributes 4 | :DocInfoProductNameURL: red_hat_jboss_enterprise_application_platform 5 | :DocInfoProductName: Red Hat JBoss Enterprise Application Platform 6 | :DocInfoProductNumber: 7.3 7 | // Links to JBoss EAP documentation 8 | :LinkDevelopmentGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/development_guide/ 9 | :DevelopmentBookName: Development Guide 10 | :LinkGettingStartedGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_guide/ 11 | :GettingStartedBookName: Getting Started Guide 12 | // Links to Developer Studio info 13 | :JBDSProductName: Red Hat CodeReady Studio 14 | :JBDSVersion: 12.15 15 | :LinkJBDSInstall: https://access.redhat.com/documentation/en-us/red_hat_codeready_studio/{JBDSVersion}/html-single/installation_guide/ 16 | :JBDSInstallBookName: Installation Guide 17 | :LinkJBDSGettingStarted: https://access.redhat.com/documentation/en-us/red_hat_codeready_studio/{JBDSVersion}/html-single/getting_started_with_codeready_studio_tools/ 18 | :JBDSGettingStartedBookName: Getting Started with CodeReady Studio Tools 19 | 20 | 21 | [[use_red_hat_jboss_developer_studio_or_eclipse_to_run_the_quickstarts]] 22 | = Use {JBDSProductName} or Eclipse to Run the Quickstarts 23 | 24 | You can deploy many of the quickstarts and run the Arquillian tests from Eclipse using JBoss tools. However, the EJB Client currently has limited support in the Eclipse Web Tools Platform (WTP). For that reason, some quickstarts that ship with {ProductName} are not supported in {JBDSProductName}. 25 | 26 | This guide includes the following information. 27 | 28 | * xref:where_to_find_information[Where to Find Information] 29 | * xref:important_special_instructions[Important Special Instructions] 30 | * xref:deploying_and_undeploying_quickstarts_and_running_the_arquillian_tests[Deploying and Undeploying Quickstarts and Running the Arquillian Tests] 31 | ** xref:deploy_and_undeploy_a_quickstart_war_project[Deploy and Undeploy a Quickstart WAR Project] 32 | ** xref:deploy_and_undeploy_a_quickstart_ear_project[Deploy and Undeploy a Quickstart EAR Project] 33 | ** xref:deploy_and_undeploy_a_quickstart_containing_server_and_java_client_projects[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] 34 | ** xref:deploy_and_undeploy_a_quickstart_consisting_of_multiple_interdependent_projects[Deploy and Undeploy a Quickstart Consisting of Multiple Interdependent Projects] 35 | ** xref:run_a_quickstarts_arquillian_tests[Run a Quickstart's Arquillian Tests] 36 | * xref:known_issues_for_jboss_eap_quickstarts[Known Issues for JBoss EAP Quickstarts] 37 | 38 | [[where_to_find_information]] 39 | == Where to Find Information 40 | 41 | * For information about how to download and install {JBDSProductName}, see the link:{LinkJBDSInstall}[{JBDSInstallBookName}]. 42 | * For information about how to configure {ProductShortName} within {JBDSProductName}, see link:{LinkJBDSGettingStarted}[{JBDSGettingStartedBookName}]. 43 | * For information about how to configure Maven and {JBDSProductName} for use with the quickstarts, see link:{LinkDevelopmentGuide}#configure_maven_for_use_with_red_hat_jboss_developer_studio[Configure Maven for Use with {JBDSProductName}] in the _{DevelopmentBookName}_ for {ProductShortName}. 44 | * For information about how to import the quickstarts into {JBDSProductName}, and for examples of how to build and deploy a basic quickstart, see link:{LinkGettingStartedGuide}#using_the_quickstart_examples[Using the Quickstart Examples] in the _{GettingStartedBookName}_ for {ProductShortName}. 45 | * For instructions to run the Arquillian tests using the Maven command line, see link:RUN_ARQUILLIAN_TESTS.adoc#run_the_arquillian_tests[Run the Arquillian Tests]. 46 | 47 | See https://developers.redhat.com/products/codeready-studio/overview[{JBDSProductName}] on the Red Hat Developer Program website for additional information. 48 | 49 | [[important_special_instructions]] 50 | == Important Special Instructions 51 | 52 | . Your quickstart project folder must be located outside of your IDE workspace. If your quickstart project folder is located within the IDE workspace when you import it into {JBDSProductName}, the IDE generates an invalid project name and an invalid WAR archive name. Be sure your quickstart project folder is located outside the IDE workspace before you begin! 53 | 54 | . Be sure to follow the instructions in the quickstart `README.adoc` file to add any required application users or make the appropriate server configuration changes. 55 | 56 | . More complex quickstarts may require special instructions to run properly in {JBDSProductName}. This document describes some of these special situations. 57 | 58 | . If you see errors or warnings when you import or run a quickstart, see the list of xref:known_issues_for_jboss_eap_quickstarts[Known Issues for JBoss EAP Quickstarts] below for an explanation. 59 | 60 | [[deploying_and_undeploying_quickstarts_and_running_the_arquillian_tests]] 61 | == Deploying and Undeploying Quickstarts and Running the Arquillian Tests 62 | 63 | [[deploy_and_undeploy_a_quickstart_war_project]] 64 | === Deploy and Undeploy a Quickstart WAR Project 65 | 66 | For WAR projects, you simply deploy the project. 67 | 68 | . Right-click on the project, and choose *Run As* -> *Run on Server*. 69 | . Choose the server and click *Finish*. 70 | . This starts the server, deploys the application, and opens a browser window that accesses the running application. 71 | . To undeploy the project, right-click on the project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. 72 | 73 | [[deploy_and_undeploy_a_quickstart_ear_project]] 74 | === Deploy and Undeploy a Quickstart EAR Project 75 | 76 | For EAR projects, you simply deploy the EAR subproject. The subproject name is usually appended with "-ear-ear". 77 | 78 | . Right-click on the EAR subproject, and choose *Run As* -> *Run on Server*. 79 | . Choose the server and click *Finish*. 80 | . This starts the server, deploys the application, and opens a browser window that accesses the running application. 81 | . To undeploy the project, right-click on the EAR subproject and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. 82 | 83 | [[deploy_and_undeploy_a_quickstart_containing_server_and_java_client_projects]] 84 | === Deploy and Undeploy a Quickstart Containing Server and Java Client Projects 85 | 86 | You must deploy the server project before running the client. More detailed instructions be found in the `shopping-cart` quickstart. 87 | 88 | . Right-click on the server project and choose *Run As* -> *Run on Server*. 89 | . Right-click on the Java client project and choose *Run As* -> *Java Application*. In the *Select Java Application* window, choose the client class and click *OK*. 90 | . The client output displays in the *Console* window. 91 | . To undeploy the project, right-click on the server subproject and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. 92 | 93 | [[deploy_and_undeploy_a_quickstart_consisting_of_multiple_interdependent_projects]] 94 | === Deploy and Undeploy a Quickstart Consisting of Multiple Interdependent Projects 95 | 96 | To deploy a quickstart that consists of multiple projects containing interdependencies on each other without opening a browser and running the application, use the following steps. More detailed instructions be found in the `inter-app` quickstart. 97 | 98 | . In the *Servers* tab, right-click on the JBoss EAP server and choose `Start`. 99 | . Deploy the projects in one of the following ways. 100 | * `Drag and Drop` mode: Click to multi-select the projects, then drag and drop them on the running JBoss EAP server. This deploys the projects to the server without opening the browser. 101 | * `Batch` mode: In the *Servers* tab, right-click on the server and choose *Add and Remove*. If the quickstart projects are the only projects in the list, click *Add All*. Otherwise, use multi-select to select them and click *Add*. Then click *Finish*. 102 | . Right-click on the individual projects and choose *Run As* -> *Run on Server*. A browser window appears that accesses the running application. 103 | . To undeploy the projects, right-click on the subprojects in the reverse order of how they were deployed, and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. 104 | 105 | [[run_a_quickstarts_arquillian_tests]] 106 | === Run a Quickstart's Arquillian Tests 107 | 108 | You can run the Arquillian tests that are included with many of the JBoss EAP {DocInfoProductNumber} quickstarts by following the steps below. See link:RUN_ARQUILLIAN_TESTS.adoc#run_the_arquillian_tests[Run the Arquillian Tests] for more complete information about running the Arquillian tests and for instructions for older versions of the quickstarts. 109 | 110 | . In the *Servers* tab, right-click on the JBoss EAP server and choose *Start*. 111 | . Right-click on the quickstart project in the *Project Explorer* tab and choose *Run As* -> *Maven build*. 112 | . Enter `clean verify -Parq-remote` in the *Goals* input field and click *Run*. 113 | 114 | [[known_issues_for_jboss_eap_quickstarts]] 115 | == Known Issues for JBoss EAP Quickstarts 116 | 117 | You may see one or more of the following errors or warnings when you import quickstart projects into {JBDSProductName}. 118 | 119 | EJB Problem: An EJB module must contain one or more enterprise beans.:: 120 | 121 | Eclipse Web Tools Platform (WTP) can not deploy simple JARs to the JBoss EAP server. For this reason, quickstart subprojects that would normally deploy shared artifacts as JARs deploy them instead as EJB JARs. You can ignore this warning. 122 | 123 | JPA Problem: No connection specified for project. No database-specific validation will be performed.:: 124 | 125 | If the quickstart project uses JPA to access a database, you will see the following warning when you import the project into Eclipse. You can ignore this warning as it only applies to the local connection in the Eclipse development environment and does not affect the JBoss EAP runtime deployment. To eliminate this warning, you must configure the database connection in the Eclipse project settings. 126 | 127 | JPA Problem: Failed while installing JPA 2.0. org.osgi.service.prefs.BackingStoreException: Resource '/__PROJECT_NAME__/__SUBPROJECT_NAME__/.settings' does not exist.:: 128 | 129 | This error can occur with quickstart projects that are composed of multiple subprojects. This is a known issue. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=459810. 130 | 131 | JPA Problem: Console configuration QUICKSTART_HOME does not exist. Hibernate specific validation and content assist will be limited.:: 132 | 133 | This warning is intermittent and can occur with any quickstart project that uses Hibernate. This is a known issue. For more information, see https://issues.jboss.org/browse/JBIDE-17483. 134 | 135 | JRE System Library Problem: Build path specifies execution environment JavaSE-1.6. There are no JREs installed in the workspace that are strictly compatible with this environment.:: 136 | 137 | The JBoss EAP 6 quickstarts demonstrate Java EE 6 features and are built on Java SE 6. {JBDSProductName} requires Java 8 to run, but is still capable of launching runtimes with various versions of Java. You can ignore this warning, or you can install a JDK 6 on your machine and add it to the Eclipse Java Runtime Environment by choosing *Preferences* -> *Java* -> *Installed JREs*. 138 | 139 | Knowledge Base Builder Problem: JBoss Tools Knowledge Base problem: Nature is not installed on required Java project ``. Use Quick Fix to include artifacts declared in that project into Content Assistant and Validation.:: 140 | 141 | Quickstarts that require Knowledge Base capabilities to be enabled on the project display this warning. To resolve it, right-click on the warning message in the in the {JBDSProductName} *Problems* window and choose *Quick Fix*. This opens a window with the fix *Enable Knowledge Base capabilities on project * selected. Make sure all projects are selected and click *Finish* to resolve the warning. 142 | 143 | Maven Configuration Problem: Project configuration is not up-to-date with pom.xml. Run Maven->Update Project or use Quick Fix:: 144 | 145 | This error can occur with quickstart projects that are composed of multiple subprojects. The import of a project on one thread may trigger Eclipse to refresh a project on another thread making the project state appear to be inconsistent. To resolve the errors, right-click on the parent project in {JBDSProductName} and choose *Maven* -> *Update Project*. Make sure all the projects are selected and click *OK*. This should resolve the errors. 146 | 147 | Maven Configuration Problem: Endorsed directory QUICKSTART_HOME/some-path/target/endorsed' is missing. You may need to a perform a Maven command line build in order to create it.:: 148 | 149 | This error occurs if endorsed directories are defined in the `maven-compiler-plugin` configuration of the quickstart POM file. To resolve the error, right-click on error in the {JBDSProductName} *Problems* window and choose *Quick Fix*. This opens a window with the fix `Run 'mvn process-sources' to execute dependency:copy` selected. Click *Finish* to resolve the error. For more information, see http://docs.jboss.org/tools/whatsnew/maven/maven-news-3.3.0.CR1.html[JBoss Maven Integration]. 150 | 151 | Maven pom Loading Problem: Overriding managed version 1.0.2.Final for wildfly-maven-plugin pom.xml.:: 152 | 153 | You can ignore this m2e warning. It can occur in child projects where the dependency versions are defined in the parent POM file. For more information, see https://bugs.eclipse.org/bugs/show_bug.cgi?id=346725[Bug 346725 - "Overriding managed version" in pom.xml should not be a warning severity ]. 154 | 155 | WSDL Problem: WS-I: (AP2901) A description uses neither the WSDL MIME Binding as described in WSDL 1.1 Section 5 nor WSDL SOAP binding as described in WSDL 1.1 Section 3 on each of the wsdl:input or wsdl:output elements of a wsdl:binding.:: 156 | 157 | You can ignore this error. This is a known Eclipse issue. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=415786. To turn off WSDL validation in {JBDSProductName}, choose *Windows* -> *Preferences*, select *Validation*, find *WSDL Validator* in the list, and uncheck the *Manual* and *Build* selections. 158 | 159 | WSDL Problem: WS-I: (BP2402) The wsdl:binding element does not use a soapbind:binding element as defined in section "3 SOAP Binding." of the WSDL 1.1 specification.:: 160 | 161 | You can ignore this error. This is a known Eclipse issue. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=415786. To turn off WSDL validation in {JBDSProductName}, choose *Windows* -> *Preferences*, select *Validation*, find *WSDL Validator* in the list, and uncheck the *Manual* and *Build* selections. 162 | 163 | WSDL Problem: 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.:: 164 | 165 | This warning occurs when you import a quickstart that contains a WSDL file into {JBDSProductName}. You can ignore this warning. It is a known Eclipse issue. For more information, see https://bugs.eclipse.org/bugs/show_bug.cgi?id=535813. 166 | 167 | XML Problem: Referenced file contains errors (jar:file:PATH-TO-jbdevstudio/studio/plugins/org.jboss.tools.as.catalog_3.0.0.Final-v20141016-1911-B95.jar!/schema/xsd/jboss-ejb3-2_0.xsd). For more information, right click on the message in the Problems View and select "Show Details...":: 168 | 169 | You can ignore this error. This is a known issue with the `jboss-ejb3-spec-2_0.xsd` schema file. See https://bugzilla.redhat.com/show_bug.cgi?id=1193543. 170 | 171 | XML Problem: Referenced file contains errors (jar:file:/PATH-TO-jbdevstudio/studio/plugins/org.jboss.tools.as.catalog_3.0.1.Final-v20141209-0156-B106.jar!/schema/xsd/jboss-ejb3-spec-2_0.xsd). For more information, right click on the message in the Problems View and select "Show Details...":: 172 | 173 | You can ignore this error. This is a known issue with the `jboss-ejb3-spec-2_0.xsd` schema file. See https://bugzilla.redhat.com/show_bug.cgi?id=1193543. 174 | 175 | XML Problem: cvc-complex-type.2.4.a: Invalid content was found starting with element 'iiop:iiop'. One of '{"http://java.sun.com/xml/ns/javaee":security-role, "http://java.sun.com/xml/ns/javaee":method-permission, "http://java.sun.com/xml/ns/javaee":container-transaction, "http://java.sun.com/xml/ns/javaee":interceptor-binding, "http://java.sun.com/xml/ns/javaee":message-destination, "http://java.sun.com/xml/ns/javaee":exclude-list, "http://java.sun.com/xml/ns/javaee":application-exception, "http://java.sun.com/xml/ns/javaee":assembly-descriptor-entry}' is expected.:: 176 | 177 | You can ignore this error. This is a known issue with the `jboss-ejb-iiop_1_0.xsd` schema file. See https://bugzilla.redhat.com/show_bug.cgi?id=901186 and https://bugzilla.redhat.com/show_bug.cgi?id=1192591. 178 | 179 | XML Problem: cvc-complex-type.2.4.a: Invalid content was found starting with element 'iiop:binding-name'. One of '{"urn:iiop":ejb-name}' is expected.:: 180 | 181 | You can ignore this error. This is a known issue with the ` jboss-ejb-iiop_1_0.xsd` schema file. See and . 182 | 183 | XML Problem: cvc-complex-type.2.4.a: Invalid content was found starting with element 'jee:interceptor-binding'. One of '{"http://java.sun.com/xml/ns/javaee":description, "http://java.sun.com/xml/ns/javaee":ejb-name}' is expected.:: 184 | 185 | You can ignore this error. This is a known issue with the `jboss-ejb-container-interceptors_1_0.xsd` schema file. See https://issues.jboss.org/browse/WFLY-4365. 186 | 187 | --------------------------------------------------------------------------------