diff --git a/demo/settings.xml b/demo/settings.xml new file mode 100644 index 000000000..4e391beca --- /dev/null +++ b/demo/settings.xml @@ -0,0 +1,89 @@ + + + + + + + + + jboss-ga-repository + + + jboss-ga-repository + http://maven.repository.redhat.com/techpreview/all + + true + + + false + + + + + + jboss-ga-plugin-repository + http://maven.repository.redhat.com/techpreview/all + + true + + + false + + + + + + + jboss-earlyaccess-repository + + + jboss-earlyaccess-repository + http://maven.repository.redhat.com/earlyaccess/all/ + + true + + + false + + + + + + jboss-earlyaccess-plugin-repository + http://maven.repository.redhat.com/earlyaccess/all/ + + true + + + false + + + + + + + + + + jboss-ga-repository + jboss-earlyaccess-repository + + + diff --git a/tutorial/Deployment.asciidoc b/tutorial/Deployment.asciidoc new file mode 100644 index 000000000..9605ad09e --- /dev/null +++ b/tutorial/Deployment.asciidoc @@ -0,0 +1,174 @@ += Appendix A: Deploying the application +:Author: Vineet Reynolds + +This appendix demonstrates how to get the application running in various environments. We'll cover the use of both command-line tools as well as the IDE (JBoss Developer Studio). Deployments of the application against JBoss Enterprise Application Platform (EAP) on the local workstation as well as the OpenShift cloud platform, would be covered. The choice of the database could be one of the in-memory H2 database (embedded with JBoss EAP), MySQL, or PostgreSQL. + +== How can you run it? + +If you've not already copied the project sources to your workstation, you should do so now. + +=== Pre-requisites + +You need the following software to build and run TicketMonster: + +* Java Development Kit (JDK) 6 or higher, to run Maven as well as the JBoss application server. Any of the following would suffice: +** OpenJDK +** Oracle Java SE +** Oracle JRockit +* JBoss Developer Studio (optional), to build and deploy TicketMonster from the IDE. +* Maven 3.0 or later, to build and deploy the examples. ++ +If you are using JBoss Developer Studio, it comes embedded with Maven, so you don't need to install it externally. +* The JBoss EAP distribution, extracted and installed in a directory. + + +You may have some of these installed these already. + +=== Running TicketMonster on the command-line + +[CAUTION] +=================================================================================== +In order to build the application, you will need you to +configure Maven to use the JBoss Enterprise Maven repositories. For instructions on +configure the Maven repositories, visit the link:https://access.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Development_Guide/index.html#Install_the_JBoss_Enterprise_Application_Platform_6_Maven_Repository[JBoss Enterprise Application Platform 6.3 documentation]. +=================================================================================== + +TicketMonster can be built from Maven, by runnning the following commands on the command-line: + +---- +cd /demo +mvn clean package +---- + +or, if you have not configured the Maven settings, use the settings.xml file supplied in the project sources: + +---- +cd /demo +mvn clean package -s ./settings.xml +---- + +This prepares a WAR file that you can deploy right away in a JBoss Enterprise Application Platform instance. It would use the in-built H2 database. + +==== Running Arquillian tests during build + +If you want to run the Arquillian tests as part of the build, you can enable one of the two available Arquillian profiles. + +For running the tests in an _already running_ JBoss application server instance, use the `arq-jbossas-remote` profile. + +---- +mvn clean package -Parq-jbossas-remote +---- + +If you want the test runner to _start_ a JBoss application server instance, use the `arq-jbossas-managed` profile. You must set up the `JBOSS_HOME` property to point to the server location, or update the `src/main/test/resources/arquillian.xml` file. + +---- +mvn clean package -Parq-jbossas-managed +---- + +=== + +If you intend to deploy into link:http://openshift.com[OpenShift] with the PostgreSQL cartridge, you can use the `postgresql-openshift` profile: + +---- +mvn clean package -Ppostgresql-openshift +---- + +Doing so would create a WAR file with a JPA persistence deployment descriptor tailored for the PostgreSQL cartridge on OpenShift. + +If you intend to deploy into link:http://openshift.com[OpenShift] with the MySQL cartridge, you can use the `mysql-openshift` profile: + +---- +mvn clean package -Pmysql-openshift +---- + +And just like the profile for PostgreSQL, this would create a WAR file tailored for the MySQL cartridge on OpenShift. + + +=== Running TicketMonster + +You can run TicketMonster into a local JBoss EAP 6.3 instance or on OpenShift. + + +==== Running TicketMonster locally + +===== From the command-line + +_Start JBoss Enterprise Application Platform 6.3_. + +1. Open a command line and navigate to the root of the JBoss server directory. +2. The following shows the command line to start the server with the web profile: ++ +---- +For Linux: JBOSS_HOME/bin/standalone.sh +For Windows: JBOSS_HOME\bin\standalone.bat +---- + +Then, _deploy TicketMonster_. + + +1. Make sure you have started the JBoss Server as described above. +2. Type this command to build and deploy the archive into a running server instance. ++ +---- +mvn clean package jboss-as:deploy +---- + +3. This will deploy `target/ticket-monster.war` to the running instance of the server. +4. Now you can see the application running at http://localhost:8080/ticket-monster. + +===== From JBoss Developer Studio + + +==== Running TicketMonster in OpenShift + + +First, _create an OpenShift project_. + +1. Make sure that you have an OpenShift domain and you have created an application using the `jbosseap-6` cartridge (for more details, get started link:https://openshift.redhat.com/app/getting_started[here]). If you want to use PostgreSQL, add the `postgresql-9.2` cartridge too. Or for MySQL, add the `mysql-5.5` cartridge. +2. Ensure that the Git repository of the project is checked out. + +Then, _build and deploy it_. + +1. Build TicketMonster using either: + * the default profile (with H2 database support) ++ +---- +mvn clean package +---- + + * the `postgresql-openshift` profile (with PostgreSQL support) if the PostgreSQL cartrdige is enabled in OpenShift. ++ +---- +mvn clean package -Ppostgresql-openshift +---- + + * the `mysql-openshift` profile (with MySQL support) if the MySQL cartrdige is enabled in OpenShift. ++ +---- +mvn clean package -Pmysql-openshift +---- + +2. Copy the `target/ticket-monster.war` file in the OpenShift Git repository (located at ``). ++ +---- +cp target/ticket-monster.war /deployments/ROOT.war +---- + +3. Navigate to `` folder. + +4. Remove the existing `src` folder and `pom.xml` file. ++ +---- +git rm -r src +git rm pom.xml +---- + +5. Add the copied file to the repository, commit and push to Openshift ++ +---- +git add deployments/ROOT.war +git commit -m "Deploy TicketMonster" +git push +---- + +6. Now you can see the application running at at `http://-.rhcloud.com` \ No newline at end of file diff --git a/tutorial/JBossDeployment.asciidoc b/tutorial/JBossDeployment.asciidoc new file mode 100644 index 000000000..5b247a973 --- /dev/null +++ b/tutorial/JBossDeployment.asciidoc @@ -0,0 +1,255 @@ +[[DeployingToJBossEAP]] += Appendix A - Deploying to JBoss EAP locally +:Author: Vineet Reynolds + +== What Will You Learn Here? + +This appendix demonstrates how to import, develop and deploy the TicketMonster example using JBoss Developer Studio: + +* Obtain and import the TicketMonster example source code +* Deploy the application to JBoss EAP with JBoss Server Tools + +== Pre-requisites + +We don't recommend using the *Internal Web Browser*, although it is configured as the default web browser in the IDE. +In certain environments, it may lack features present in modern web browsers, thus providing a sub-optimal user and developer experience. + +We shall therefore set the IDE default web browser to be your default system web browser. Click *Window*→*Web +Browser*→*Default system web browser*. + +== Import the Project source code + +Once the TicketMonster source code is obtained and unpackaged, you must import it into JBoss +Developer Studio, as detailed in the procedure below. TicketMonster is a Maven-based project so a +specific Import Maven Project wizard is used for the import. + +. Click *File*→*Import* to open the *Import* wizard. +. Expand *Maven*, select *Existing Maven Projects* and click *Next*. +. In the *Root Directory* field, enter the path to the TicketMonster source code. Alternatively, +click *Browse* to navigate to the source code location. The *Import Maven Project* wizard +recursively searches the path for a *pom.xml* file. The *pom.xml* file identifies the project as a +Maven project. The file is listed under *Projects* once it is found. ++ +.pom.xml File Listed in the Projects Pane +image::gfx/pom-file-projects-pane.png[] +. Click *Finish*. When the import process is complete, the project is listed in the *Project Explorer* view. + + +== Deploying to JBoss EAP using JBoss Developer Studio + +Once you have imported the TicketMonster source code into JBoss Developer Studio, the project +application can be deployed to the JBoss EAP server and the running application viewed in the +default system web browser, as detailed in the procedure below: + +. In the *Project Explorer* view, right-click *ticket-monster* and click *Run As*→*Run on +Server*. +. Under *How do you want to select the server?*, ensure *Choose an existing +server* is selected. +. In the *Server* table, expand *localhost*, select *jboss-eap-version* where version +denotes the JBoss EAP version, and click *Next*. ++ +[[jboss-eap-selected-deployment]] +.JBoss EAP 6.x Server Selected +image::gfx/jboss-eap-selected-deployment.png[] +. Ensure *ticket-monster* is listed in the *Configured* column and click Finish. The +*Console* view automatically becomes the view in focus and displays the output from the +JBoss EAP server. Once deploying is complete, the web application opens in the default +system web browser. ++ +[[ticketmonster-configured-jboss-eap]] +.ticket-monster Listed in the Configured Column +image::gfx/ticketmonster-configured-jboss-eap.png[] + + +== Deploying to JBoss EAP using the command-line + +_Start JBoss Enterprise Application Platform 6.3_. + +1. Open a command line and navigate to the root of the JBoss server directory. +2. The following shows the command line to start the server with the web profile: ++ +---- +For Linux: JBOSS_HOME/bin/standalone.sh +For Windows: JBOSS_HOME\bin\standalone.bat +---- + +Then, _deploy TicketMonster_. + + +1. Make sure you have started the JBoss Server as described above. +2. Type this command to build and deploy the archive into a running server instance. ++ +---- +mvn clean package jboss-as:deploy +---- ++ +(You can use the `arq-jbossas-remote` profile for running tests as well) ++ +If you have not configured the Maven settings, to use the Red Hat Enterprise Maven repositories: ++ +---- +mvn clean package jboss-as:deploy -s TICKETMONSTER_MAVEN_PROJECT_ROOT/settings.xml +---- +3. This will deploy `target/ticket-monster.war` to the running instance of the server. +4. Now you can see the application running at http://localhost:8080/ticket-monster. + +== Using MySQL as the database + +You can deploy TicketMonster to JBoss EAP, making use of a 'real' database like MySQL, instead of the default in-memory H2 database. You can follow the procedure outlined as follows: + +. Install the MySQL JBDC driver as a new JBoss module. +.. Define a new JBoss module named `com.mysql` under the `modules` directory of the JBoss EAP installation. Under the `modules/system/layers/base` directory structure, create a directory named `com`, containing sub-directory named `mysql`, containing a sub-directory named `main`. Place the MySQL JBDC driver in the `main` directory. Finally, define the module via a `module.xml` file with the following contents: ++ +.EAP_HOME/system/layers/base/com/mysql/main/module.xml +---- + + + + + + + + + + + +---- ++ +This module declares the MySQL JDBC driver as a resource (from which to load classes) for the module. It also declares a dependency on the `javax.api` and `javax.transaction.api` modules, since the JDBC driver depends on classes from these modules. Remember to make corrections to the JBDC driver resource path, if you are using a driver JAR with a different name. +The JBoss EAP directory structure should now look like this: ++ +---- +modules ++---system +¦ +---layers +¦ ¦ +---base +¦ ¦ ¦ +---com +¦ ¦ ¦ ¦ +---mysql +¦ ¦ ¦ ¦ ¦ +---main +¦ ¦ ¦ ¦ ¦ ¦ +-------module.xml +¦ ¦ ¦ ¦ ¦ ¦ +-------mysql-connector-java-5.1.34-bin.jar +---- +. Register the MySQL datasource used by the application. Edit the server configuration file (`standalone.xml`), to add the datasource definition: ++ +---- + + + jdbc:mysql://localhost:3306/ticketmonster + com.mysql + TRANSACTION_READ_COMMITTED + + 10 + 100 + true + + + test + test + + + 32 + + + + + + com.mysql.jdbc.Driver + com.mysql.jdbc.jdbc2.optional.MysqlXADataSource + + + +---- ++ +Replace the values for the `connection-url`, `user-name` and `password` with the correct ones for your environment. +. Build and deploy the application, using the `mysql` profile defined in the project POM : +.. In JBoss Developer Studio, you can do this by opening the project's context menu: right-click on the project, click *Maven*→*Select Maven Profiles...*, and activate the `mysql` profile by selecting it's checkbox. Once you have activated the profile, you can publish the project to a JBoss EAP instance from JBoss Developer Studio in the same manner described previously. +.. If you are building and deploying from the command-line, activate the `mysql` profile, by specifying it during the build command like so: ++ +---- +mvn clean package jboss-as:deploy -Pmysql +---- +.. If you have not configured the Maven settings, to use the Red Hat Enterprise Maven repositories: ++ +---- +mvn clean package jboss-as:deploy -Pmysql -s TICKETMONSTER_MAVEN_PROJECT_ROOT/settings.xml +---- + + +== Using PostgreSQL as the database + +Just like MySQL, you can deploy TicketMonster to JBoss EAP, making use of a 'real' database like PostgreSQL, instead of the default in-memory H2 database. You can follow the procedure outlined as follows: + +. Install the PostgreSQL JBDC driver as a new JBoss module. +.. Define a new JBoss module named `com.mysql` under the `modules` directory of the JBoss EAP installation. Under the `modules/system/layers/base` directory structure, create a directory named `org`, containing sub-directory named `postgresql`, containing a sub-directory named `main`. Place the PostgreSQL JBDC driver in the `main` directory. Finally, define the module via a `module.xml` file with the following contents: ++ +.EAP_HOME/system/layers/base/com/mysql/main/module.xml +---- + + + + + + + + + + +---- ++ +This module declares the PostgreSQL JDBC driver as a resource (from which to load classes) for the module. It also declares a dependency on the `javax.api` and `javax.transaction.api` modules, since the JDBC driver depends on classes from these modules. Remember to make corrections to the JBDC driver resource path, if you are using a driver JAR with a different name. +The JBoss EAP directory structure should now look like this: ++ +---- +modules ++---system +¦ +---layers +¦ ¦ +---base +¦ ¦ ¦ +---org +¦ ¦ ¦ ¦ +---postgresql +¦ ¦ ¦ ¦ ¦ +---main +¦ ¦ ¦ ¦ ¦ ¦ +-------module.xml +¦ ¦ ¦ ¦ ¦ ¦ +-------postgresql-9.3-1102.jdbc4.jar +---- +. Register the PostgreSQL datasource used by the application. Edit the server configuration file (`standalone.xml`), to add the datasource definition: ++ +---- + + + jdbc:postgresql://localhost:5432/ticketmonster + org.postgresql + TRANSACTION_READ_COMMITTED + + 10 + 100 + true + + + test + test + + + 32 + + + + + + org.postgresql.xa.PGXADataSource + + + +---- ++ +Replace the values for the `connection-url`, `user-name` and `password` with the correct ones for your environment. +. Build and deploy the application, using the `postgresql` profile defined in the project POM : +.. In JBoss Developer Studio, you can do this by opening the project's context menu: right-click on the project, click *Maven*→*Select Maven Profiles...*, and activate the `postgresql` profile by selecting it's checkbox. Once you have activated the profile, you can publish the project to a JBoss EAP instance from JBoss Developer Studio in the same manner described previously. +.. If you are building and deploying from the command-line, activate the `postgresql` profile, by specifying it during the build command like so: ++ +---- +mvn clean package jboss-as:deploy -Ppostgresql +---- +.. If you have not configured the Maven settings, to use the Red Hat Enterprise Maven repositories: ++ +---- +mvn clean package jboss-as:deploy -Ppostgresql -s TICKETMONSTER_MAVEN_PROJECT_ROOT/settings.xml +---- \ No newline at end of file diff --git a/tutorial/OpenShiftDeployment.asciidoc b/tutorial/OpenShiftDeployment.asciidoc new file mode 100644 index 000000000..cf591db97 --- /dev/null +++ b/tutorial/OpenShiftDeployment.asciidoc @@ -0,0 +1,328 @@ +[[DeployingToOpenShift]] += Appendix B - Deploying to OpenShift +:Author: Vineet Reynolds + +== What Will You Learn Here? + +This appendix demonstrates how to import, develop and deploy the TicketMonster example using JBoss Developer Studio: + +* Obtain and import the TicketMonster example source code +* Deploy the application to OpenShift Online with OpenShift Tools + +== Import the Project source code + +Once the TicketMonster source code is obtained and unpackaged, you must import it into JBoss +Developer Studio, as detailed in the procedure below. TicketMonster is a Maven-based project so a +specific Import Maven Project wizard is used for the import. + +. Click *File*→*Import* to open the *Import* wizard. +. Expand *Maven*, select *Existing Maven Projects* and click *Next*. +. In the *Root Directory* field, enter the path to the TicketMonster source code. Alternatively, +click *Browse* to navigate to the source code location. The *Import Maven Project* wizard +recursively searches the path for a *pom.xml* file. The *pom.xml* file identifies the project as a +Maven project. The file is listed under *Projects* once it is found. ++ +.pom.xml File Listed in the Projects Pane +image::gfx/pom-file-projects-pane.png[] +. Click *Finish*. When the import process is complete, the project is listed in the *Project Explorer* view. + + +== Pre-requisites + +We will be pushing the TicketMonster sources to a git repository on OpenShift, where the application would be built and deployed. +The build on OpenShift, and hence the `git push` can timeout, since Maven dependencies will have to be fetched from the Red Hat Enterprise Maven repository or other repositories. + +We'll get around this drawback by configuring JBoss Developer Studio to not time out sooner. To do do, set the Git connection timeout to 300 seconds. Click *Window* → *Preferences*, expand *Team* and +select *Git*. In the *Remote connection timeout (seconds)* field, type *300* and click *Apply* and click *OK*. + +[[git-remote-connection-timeout]] +.Modify the git remote connection timeout +image::gfx/git-remote-connection-timeout.png[] + +== Deploying to OpenShift using JBoss Developer Studio + +To deploy TicketMonster to OpenShift Online, you must create a new OpenShift Online application based on the existing workspace project using OpenShift Tools, as detailed in the procedure below. + +[NOTE] +===================================================================================== +This procedure documents the deploying process for first-time OpenShift Online users. This +includes one-time steps, such as signing up for an OpenShift Online account, creating an +OpenShift Online domain and uploading SSH keys. If you have previously used OpenShift +Online and OpenShift Tools, omit the one-time steps as appropriate. +===================================================================================== + +. In JBoss Central, under Start from scratch, click OpenShift Application. +. Click the _Please sign up here_ link to create an OpenShift Online account and follow the +instructions on the OpenShift web page displayed in your default system web browser. Once +you have completed the sign-up process, restart the New OpenShift Application wizard. ++ +. Complete the fields about your OpenShift Online account as follows: +* From the Connection list, select New Connection. +* Ensure the Use default server check box is selected. +* In the Username and Password fields, type your account credentials. ++ +[[completed-username-password-fields]] +.Completed Username and Password Fields +image::gfx/completed-username-password-fields.png[] +. Click Next. +. In the *Domain Name* field, type a name for your new OpenShift Online domain and click Finish. The provided domain name must be unique across all domains on OpenShift Online; if it is not unique, you will be instructed to provide a unique domain name. +. From the Type list, select JBoss Enterprise Application Platform 6 (jbosseap-6). ++ +[[completed-fields-application-wizard]] +.Completed Fields in the New OpenShift Application Wizard +image::gfx/completed-fields-application-wizard.png[] +. Click Next. +. Complete the fields about the new OpenShift Online application as follows: +* In the Domain name field, select an existing OpenShift Online domain. +* In the Name field, type ticketmonster. +* From the Domain list, ensure the domain you have previously created is selected. +* From the Gear profile list, select small. ++ +[[completed-fields-application-wizard-step2]] +.Completed Fields in the New OpenShift Application Wizard +image::gfx/completed-fields-application-wizard-step2.png[] +. Click Next. +* Clear the Create a new project check box. +* In the Use existing project field, type ticket-monster. Alternatively, click Browse to select the ticket-monster project. +* Ensure the Create and set up a server for easy publishing check box is selected. ++ +[[completed-fields-application-wizard-step3]] +.Completed Fields in the New OpenShift Application Wizard +image::gfx/completed-fields-application-wizard-step3.png[] +. Click Next. +. Click SSH Keys wizard and click New. +. Complete the fields about the SSH Keys to be created as follows: +* In the Name field, type a name for the SSH key. +* From the Key Type list, ensure SSH_RSA is selected. +* In the SSH2 Home field, ensure your .ssh directory path is shown. +* In the Private Key File Name field, type a name for the private key file name. The Public Key File Name field populates automatically with the name of the private key file name with .pub appended. +. Click Finish. +. Click OK to close the Manage SSH Keys window. +. Click Finish to create the new OpenShift application based on the existing workspace ticket-monster project. This process may take some time to complete. ++ +[[new-openshift-application-wizard]] +.New OpenShift Application Wizard +image::gfx/new-openshift-application-wizard.png[] +. At the prompt stating OpenShift application ticketmonster will be enabled on project ticket-monster ..., click OK. This configures the workspace ticket-monster project for OpenShift and connects it to the OpenShift Online Git repository system used for version control. ++ +[[import-openShift-application-prompt]] +.Import OpenShift Application Prompt +image::gfx/import-openShift-application-prompt.png[] +. At the prompt stating the authenticity of the host cannot be established and asking if you are sure you want to continue connecting, verify the host information is correct and click Yes. +. At the prompt asking if you want to publish committed changes to OpenShift, click Yes. The Console view automatically becomes the view in focus and displays the output from the OpenShift Online server. Once the OpenShift Online ticketmonster application is created and deployed, the Console view displays the following message: ++ +`Deployment completed with status: success` ++ +[[completed-deployment-openshift]] +.New OpenShift Application Wizard +image::gfx/completed-deployment-openshift.png[] + + +== Deploying to OpenShift using the command-line + +To deploy TicketMonster to OpenShift Online, you must create a new OpenShift Online application based on the existing workspace project using OpenShift Tools, as detailed in the procedure below. + +[NOTE] +===================================================================================== +This procedure documents the deploying process for first-time OpenShift Online users. This +includes one-time steps, such as signing up for an OpenShift Online account, creating an +OpenShift Online domain and uploading SSH keys. If you have previously used OpenShift +Online and OpenShift Tools, omit the one-time steps as appropriate. +===================================================================================== + +=== Create an OpenShift Account and Domain + +If you do not yet have an OpenShift account and domain, link:browse to OpenShift[https://openshift.com/] to create the account and domain. + +link:Get Started with OpenShift[https://openshift.redhat.com/app/getting_started] details how to install the OpenShift Client tools. + +=== Create the OpenShift Application + +[NOTE] +===================================================================================== +The following variables are used in these instructions. Be sure to replace them as follows: + +YOUR_DOMAIN_NAME should be replaced with the OpenShift domain name. +APPLICATION_UUID should be replaced with the UUID generated by OpenShift for your application, for example: 52864af85973ca430200006f +TICKETMONSTER_MAVEN_PROJECT_ROOT is the location of the Maven project sources for the TicketMonster application. +===================================================================================== + +Open a shell command prompt and change to a directory of your choice. Enter the following command to create a JBoss EAP 6 application: + +---- +rhc app create -a ticketmonster -t jbosseap-6 +---- + +[NOTE] +===================================================================================== +The domain name for this application will be `ticketmonster-YOUR_DOMAIN_NAME.rhcloud.com` +===================================================================================== + +This command creates an OpenShift application named ticketmonster and will run the application inside the jbosseap-6 container. You should see some output similar to the following: + +---- +Application Options +------------------- +Domain: YOUR_DOMAIN +Cartridges: jbosseap-6 (addtl. costs may apply) +Gear Size: default +Scaling: no + +Creating application 'ticketmonster' ... done + + +Waiting for your DNS name to be available ... done + +Cloning into 'ticketmonster'... +Warning: Permanently added the RSA host key for IP address '54.90.10.115' to the list of known hosts. + +Your application 'ticketmonster' is now available. + + URL: http://ticketmonster-YOUR_DOMAIN.rhcloud.com/ + SSH to: APPLICATION_UUID@ticketmonster-YOURDOMAIN.rhcloud.com + Git remote: ssh://APPLICATION_UUID@ticketmonster-YOUR_DOMAIN.rhcloud.com/~/git/ticketmonster.git/ + Cloned to: /Users/vineet/openshiftapps/ticketmonster + +Run 'rhc show-app ticketmonster' for more details about your app. +---- + +The create command creates a git repository in the current directory with the same name as the application. + +You do not need the generated default application, so navigate to the new git repository directory created by the OpenShift command and tell git to remove the source and pom files: + +---- +cd ticketmonster +git rm -r src pom.xml +---- + +Copy the TicketMonster application sources into this new git repository: + +---- +cp -r TICKETMONSTER_MAVEN_PROJECT_ROOT/src . +cp -r TICKETMONSTER_MAVEN_PROJECT_ROOT/pom.xml . +---- + +You can now deploy the changes to your OpenShift application using git as follows: + +---- +git add src pom.xml +git commit -m "TicketMonster on OpenShift" +git push +---- + +The final push command triggers the OpenShift infrastructure to build and deploy the changes. + +Note that the `openshift` profile in pom.xml is activated by OpenShift, and causes the WAR build by OpenShift to be copied to the deployments/ directory, and deployed without a context path. + +Now you can see the application running at http://ticketmonster-YOUR_DOMAIN/. + +== Using MySQL as the database + +You can deploy TicketMonster to OpenShift, making use of a 'real' database like MySQL, instead of the default in-memory H2 database within the JBoss EAP cartridge. You can follow the procedure outlined as follows, to first deploy the TicketMonster application to a JBoss EAP cartridge, and to then add a : + +. Create the OpenShift application from the TicketMonster project sources, as described in the previous sections. +. Add the MySQL cartridge to the application. +.. If you are using JBoss Developer Studio, select the `ticketmonster` application in the *OpenShift Explorer* view. Open the context-menu by right-clicking on it, and navigate to the *Edit Embedded Cartridges...* menu item. ++ +[[edit-embedded-cartridge-openshift-for-mysql]] +.Edit Embedded Cartidges for an OpenShift application +image::gfx/edit-embedded-cartridge-openshift.png[] ++ +Select the MySQL 5.5 cartidge, and click *Finish*. ++ +[[add-mysql-embedded-cartridge]] +.Add MySQL cartridge +image::gfx/add-mysql-embedded-cartridge.png[] +.. If you are using the command-line, execute the following command, to add the MySQL 5.5 cartridge to the `ticketmonster` application: ++ +---- +rhc cartridge add mysql-5.5 -a ticketmonster +---- +. Configure the OpenShift build process, to use the `mysql-openshift` profile within the project POM. As you would know, the Maven build on OpenShift uses the `openshift` profile by default - this profile does not contain any instructions or configuration to create a WAR file with the JPA deployment descriptor for MySQL on OpenShift. The `mysql-openshift` profile contains this configuration. Since it is not activated during the build on OpenShift, we need to instruct OpenShift to use it as well. ++ +To do so, create a file named `pre_build_jbosseap` under the `.openshift/action_hooks` directory located in the git repository of the OpenShift application, with the following contents: ++ +.TICKET_MONSTER_OPENSHIFT_GIT_REPO/.openshift/build_hooks/pre_build_jbosseap +---- +export MAVEN_ARGS="clean package -Popenshift,mysql-openshift -DskipTests" +---- ++ +This OpenShift action hook sets up the `MAVEN_ARGS` environment variable used by OpenShift to configure the Maven build process. The exported variable now activates the `mysql-openshift` profile, in addition to the default values originally present in the variable. + +. Publish the changes to OpenShift: +.. If you are using JBoss Developer Studio, right-click the project, go to *Team*→*Commit...* to commit the changes. Select the `pre_build_jbosseap` file to add to the commit. Choose the *Commit and Push* button during committing, to push the changes to the OpenShift repository. +.. If you are using the command line, add the `pre_build_jbosseap` file to the git index, and commit it, and push to the OpenShift repository, as follows: ++ +---- +cd +git add .openshift/build_hooks/pre_build_jbosseap +git commit -m "Added pre-build action hook for MySQL" +git push +---- + +[NOTE] +====== +On Windows, you will need to run the following command to set the executable bit to the `pre_build_jbosseap` file: + + git update-index --chmod=+x .openshift/build_hooks/pre_build_jbosseap + +This ensures the executable bit is recognized on OpenShift even though the file was committed in Windows. + +Since JBoss Developer Studio does not have a git console, you will need to run this from the command line. +====== + + +== Using PostgreSQL as the database + +You can deploy TicketMonster to OpenShift, making use of a 'real' database like PostgreSQL, instead of the default in-memory H2 database within the JBoss EAP cartridge. You can follow the procedure outlined as follows: + +. Create the OpenShift application from the TicketMonster project sources, as described in the previous sections. +. Add the PostgreSQL cartridge to the application. +.. If you are using JBoss Developer Studio, select the `ticketmonster` application in the *OpenShift Explorer* view. Open the context-menu by right-clicking on it, and navigate to the *Edit Embedded Cartridges...* menu item. ++ +[[edit-embedded-cartridge-openshift-for-postgres]] +.Edit Embedded Cartidges for an OpenShift application +image::gfx/edit-embedded-cartridge-openshift.png[] ++ +Select the PostgreSQL 9.2 cartidge, and click *Finish*. ++ +[[add-postgresql-embedded-cartridge]] +.Add PostgreSQL cartridge +image::gfx/add-postgresql-embedded-cartridge.png[] +.. If you are using the command-line, execute the following command, to add the PostgreSQL 9.2 cartridge to the `ticketmonster` application: ++ +---- +rhc cartridge add postgresql-9.2 -a ticketmonster +---- +. Configure the OpenShift build process, to use the `postgresql-openshift` profile within the project POM. As you would know, the Maven build on OpenShift uses the `openshift` profile by default - this profile does not contain any instructions or configuration to create a WAR file with the JPA deployment descriptor for MySQL on OpenShift. The `postgresql-openshift` profile contains this configuration. Since it is not activated during the build on OpenShift, we need to instruct OpenShift to use it as well. ++ +To do so, create a file named `pre_build_jbosseap` under the `.openshift/action_hooks` directory located in the git repository of the OpenShift application, with the following contents: ++ +.TICKET_MONSTER_OPENSHIFT_GIT_REPO/.openshift/build_hooks/pre_build_jbosseap +---- +export MAVEN_ARGS="clean package -Popenshift,postgresql-openshift -DskipTests" +---- ++ +This OpenShift action hook sets up the `MAVEN_ARGS` environment variable used by OpenShift to configure the Maven build process. The exported variable now activates the `postgresql-openshift` profile, in addition to the default values originally present in the variable. + +. Publish the changes to OpenShift: +.. If you are using JBoss Developer Studio, right-click the project, go to *Team*→*Commit...* to commit the changes. Select the `pre_build_jbosseap` file to add to the commit. Choose the *Commit and Push* button during committing, to push the changes to the OpenShift repository. +.. If you are using the command line, add the `pre_build_jbosseap` file to the git index, and commit it, and push to the OpenShift repository, as follows: ++ +---- +cd +git add .openshift/build_hooks/pre_build_jbosseap +git commit -m "Added pre-build action hook for MySQL" +git push +---- + +[NOTE] +====== +On Windows, you will need to run the following command to set the executable bit to the `pre_build_jbosseap` file: + + git update-index --chmod=+x .openshift/build_hooks/pre_build_jbosseap + +This ensures the executable bit is recognized on OpenShift even though the file was committed in Windows. + +Since JBoss Developer Studio does not have a git console, you will need to run this from the command line. +====== \ No newline at end of file diff --git a/tutorial/gfx/add-mysql-embedded-cartridge.png b/tutorial/gfx/add-mysql-embedded-cartridge.png new file mode 100644 index 000000000..6a2556d63 Binary files /dev/null and b/tutorial/gfx/add-mysql-embedded-cartridge.png differ diff --git a/tutorial/gfx/add-postgresql-embedded-cartridge.png b/tutorial/gfx/add-postgresql-embedded-cartridge.png new file mode 100644 index 000000000..e7867dad2 Binary files /dev/null and b/tutorial/gfx/add-postgresql-embedded-cartridge.png differ diff --git a/tutorial/gfx/completed-deployment-openshift.png b/tutorial/gfx/completed-deployment-openshift.png new file mode 100644 index 000000000..7d65f8581 Binary files /dev/null and b/tutorial/gfx/completed-deployment-openshift.png differ diff --git a/tutorial/gfx/completed-fields-application-wizard-step2.png b/tutorial/gfx/completed-fields-application-wizard-step2.png new file mode 100644 index 000000000..a5a2189f2 Binary files /dev/null and b/tutorial/gfx/completed-fields-application-wizard-step2.png differ diff --git a/tutorial/gfx/completed-fields-application-wizard-step3.png b/tutorial/gfx/completed-fields-application-wizard-step3.png new file mode 100644 index 000000000..94c68fcc1 Binary files /dev/null and b/tutorial/gfx/completed-fields-application-wizard-step3.png differ diff --git a/tutorial/gfx/completed-fields-application-wizard.png b/tutorial/gfx/completed-fields-application-wizard.png new file mode 100644 index 000000000..ec35de692 Binary files /dev/null and b/tutorial/gfx/completed-fields-application-wizard.png differ diff --git a/tutorial/gfx/completed-username-password-fields.png b/tutorial/gfx/completed-username-password-fields.png new file mode 100644 index 000000000..63f0110af Binary files /dev/null and b/tutorial/gfx/completed-username-password-fields.png differ diff --git a/tutorial/gfx/edit-embedded-cartridge-openshift.png b/tutorial/gfx/edit-embedded-cartridge-openshift.png new file mode 100644 index 000000000..7c3996040 Binary files /dev/null and b/tutorial/gfx/edit-embedded-cartridge-openshift.png differ diff --git a/tutorial/gfx/git-remote-connection-timeout.png b/tutorial/gfx/git-remote-connection-timeout.png new file mode 100644 index 000000000..e30c026e7 Binary files /dev/null and b/tutorial/gfx/git-remote-connection-timeout.png differ diff --git a/tutorial/gfx/import-openShift-application-prompt.png b/tutorial/gfx/import-openShift-application-prompt.png new file mode 100644 index 000000000..21ece4775 Binary files /dev/null and b/tutorial/gfx/import-openShift-application-prompt.png differ diff --git a/tutorial/gfx/jboss-eap-selected-deployment.png b/tutorial/gfx/jboss-eap-selected-deployment.png new file mode 100644 index 000000000..6c98efdcc Binary files /dev/null and b/tutorial/gfx/jboss-eap-selected-deployment.png differ diff --git a/tutorial/gfx/new-openshift-application-wizard.png b/tutorial/gfx/new-openshift-application-wizard.png new file mode 100644 index 000000000..a21a5d9f4 Binary files /dev/null and b/tutorial/gfx/new-openshift-application-wizard.png differ diff --git a/tutorial/gfx/pom-file-projects-pane.png b/tutorial/gfx/pom-file-projects-pane.png new file mode 100644 index 000000000..f65b25f05 Binary files /dev/null and b/tutorial/gfx/pom-file-projects-pane.png differ diff --git a/tutorial/gfx/ticketmonster-configured-jboss-eap.png b/tutorial/gfx/ticketmonster-configured-jboss-eap.png new file mode 100644 index 000000000..c31871237 Binary files /dev/null and b/tutorial/gfx/ticketmonster-configured-jboss-eap.png differ diff --git a/tutorial/ticket-monster.asciidoc b/tutorial/ticket-monster.asciidoc index 361df2eee..12d01fac7 100644 --- a/tutorial/ticket-monster.asciidoc +++ b/tutorial/ticket-monster.asciidoc @@ -23,3 +23,6 @@ include::DashboardHTML5.asciidoc[] include::HybridUI.asciidoc[] +include::JBossDeployment.asciidoc[] + +include::OpenShiftDeployment.asciidoc[] \ No newline at end of file