diff --git a/CONTRIBUTING.html b/CONTRIBUTING.html new file mode 100644 index 000000000..ad8b01107 --- /dev/null +++ b/CONTRIBUTING.html @@ -0,0 +1,553 @@ +README +

Quickstarts Contributing Guide

+ +

Purpose of the quickstarts

+ + + +

Basic Steps

+ +

To contribute to the quickstarts, fork the quickstart repository to your own Git, clone your fork, commit your work on topic branches, and make pull requests.

+ +

If you don’t have the Git client (git), get it from: http://git-scm.com/

+ +

Here are the steps in detail:

+ +
    +

  1. Fork the project. This creates a the project in your own Git with the default remote name ‘origin’.

    2. +

  2. Clone your fork. This creates and populates a directory in your local file system.

    +
    git clone https://github.com/<your-username>/jboss-wfk-quickstarts.git
+
    3. +

  3. Change to the jboss-wfk-quickstarts directory.

    4. +

  4. Add the remote upstream repository so you can fetch any changes to the original forked repository.

    +
    git remote add upstream https://github.com/jboss-developer/jboss-wfk-quickstarts.git
+
    5. +

  5. Get the latest files from the upstream repository.

    +
    git fetch upstream
+
    6. +

  6. Create a new topic branch to contain your new quickstart, features, changes, or fixes using the git checkout -b <topic-branch-name> upstream/master command. For example:

    +
    git checkout -b helloworld-fix upstream/master
+
    7. +

  7. Contribute new code or make changes to existing files. Make sure that you follow the General Guidelines below.

    8. +

  8. To verify if your code followed the General Guidelines you can run QS Tools on your project.

    + +
    9. +

  9. Use the git add command to add new or changed file contents to the staging area.

    + +
    10. +

  10. Use the git status command to view the status of the files in the directory and in the staging area and ensure that all modified files are properly staged:

    +
    git status        
+
    11. +

  11. Commit your changes to your local topic branch.

    +
    git commit -m 'Description of change...'
+
    12. +

  12. Update your branch with any changes made upstream since you started.

    + +
    13. +

  13. Push your local topic branch to your github forked repository. This will create a branch on your Git fork repository with the same name as your local topic branch name.

    +
    git push origin HEAD            
+
    +

    Note: The above command assumes your remote repository is named ‘origin’. You can verify your forked remote repository name using the command git remote -v.

    14. +

  14. Browse to the branch on your forked Git repository and open a Pull Request. Give it a clear title and description.

    15. +
+ +

General Guidelines

+ + + +

Kitchensink variants

+ +

There are multiple quickstarts based on the kitchensink example. Each showcases different technologies and techniques including pure EE6, JSF, HTML5, and GWT.

+ +

If you wish to contribute a kitchensink variant is it important that you follow the look and feel of the original so that useful comparisons can be made. This does not mean that variants can not expand, and showcase additional functionality. Multiple variants already do that. These include mobile interfaces, push updates, and more.

+ +

Below are rules for the look and feel of the variants:

+ + + +

Setup your environment

+ +

The quickstart README.html files are converted to HTML using markdown. We recommend using redcarpet, as that is what github uses, but you can use any markdown tool really.

+ +

There are two scripts, dist/github-flavored-markdown.rb, that will convert an individual file, and dist/release-utils.sh -m, that will convert all the files.

+ +

To setup the environment you need to follow these steps.

+ +
    +

  1. Install Ruby 1.9.X

    + +

    For RHEL you can use this spec

    + +

    In general, you’re better off not relying on your OSs ruby install, they are often quite broken.

    2. +

  2. Install Ruby GEMs

    +
    gem install nokogiri pygments.rb redcarpet fileutils
+
    3. +

  3. Install Python Eggs

    + +

    You’ll need python eggs installed, which often isn’t available on OS installs of python. Try to read and use setuptools installation-instructions

    4. +

  4. Install pygments

    +
        sudo easy_install pygments
+
    5. +
+ +

Configure Maven

+ +

If you are working with quickstarts currently under development in the master branch, you need access to artifacts currently under development. The JBoss developer Maven repository, which contains newly staged artifacts, is located at jboss-developer.github.io.

+ +

To access these artifacts, do one of the following:

+ + + +

Note: Regardless of the method you choose to configure your Maven settings, you must also delete the existing ${user.home}/.m2/repository/.

+ +

License Information and Contributor Agreement

+ +

JBoss Developer Framework is licensed under the Apache License 2.0, as we believe it is one of the most permissive Open Source license. This allows developers to easily make use of the code samples in JBoss Developer Framework.

+ +

There is no need to sign a contributor agreement to contribute to JBoss Developer Framework. You just need to explicitly license any contribution under the AL 2.0. If you add any new files to JBoss Developer Framework, make sure to add the correct header.

+ +

Java, Javascript and CSS files

+
  /** 
+   * JBoss, Home of Professional Open Source
+   * Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual
+   * contributors by the @authors tag. See the copyright.txt in the 
+   * distribution for a full listing of individual contributors.
+   *
+   * Licensed under the Apache License, Version 2.0 (the "License");
+   * you may not use this file except in compliance with the License.
+   * You may obtain a copy of the License at
+   * http://www.apache.org/licenses/LICENSE-2.0
+   * Unless required by applicable law or agreed to in writing, software
+   * distributed under the License is distributed on an "AS IS" BASIS,  
+   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   * See the License for the specific language governing permissions and
+   * limitations under the License.
+   */
+
+

HTML, XML, XSD and XHTML files

+
  <!--
+   JBoss, Home of Professional Open Source
+   Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual
+   contributors by the @authors tag. See the copyright.txt in the 
+   distribution for a full listing of individual contributors.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,  
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   -->
+
+

Properties files and Bash Scripts

+
   # JBoss, Home of Professional Open Source
+   # Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual
+   # contributors by the @authors tag. See the copyright.txt in the 
+   # distribution for a full listing of individual contributors.
+   #
+   # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   # http://www.apache.org/licenses/LICENSE-2.0
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,  
+   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   # See the License for the specific language governing permissions and
+   # limitations under the License.
+
+

SQL files

+
  --
+  -- JBoss, Home of Professional Open Source
+  -- Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual
+  -- contributors by the @authors tag. See the copyright.txt in the
+  -- distribution for a full listing of individual contributors.
+  --
+  -- Licensed under the Apache License, Version 2.0 (the "License");
+  -- you may not use this file except in compliance with the License.
+  -- You may obtain a copy of the License at
+  -- http://www.apache.org/licenses/LICENSE-2.0
+  -- Unless required by applicable law or agreed to in writing, software
+  -- distributed under the License is distributed on an "AS IS" BASIS,
+  -- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  -- See the License for the specific language governing permissions and
+  -- limitations under the License.
+  --
+
+

JSP files

+
  <%--
+  JBoss, Home of Professional Open Source
+  Copyright 2013, Red Hat, Inc. and/or its affiliates, and individual
+  contributors by the @authors tag. See the copyright.txt in the
+  distribution for a full listing of individual contributors.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+  http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  --%>
+
+

Quickstart Cheat Sheet Contributing Guide

+ +

Purpose of the Cheat Sheets

+ + + +

Basic Steps to Create a Cheat Sheet

+ +

You can create a cheat sheet using the Eclipse Wizard or you can copy and modify an existing cheat sheet from another quickstart. This section describes how to create a cheat sheet using the Eclipse wizard.

+ +

Note: Be sure your project folder is located outside of the Eclipse workspace before you begin this process.

+ +
    +
  1. Import your quickstart into JBoss Developer Studio (JDBS) + +
      +
    1. From the menu, choose File –> Import –> Maven –> Existing Maven Projects, then click Next.
      2. +
    2. Navigate to your quickstart, select it, then click OK.
      3. +
    3. Click Finish.
      4. +
    2. +
  2. Create the cheat sheet. + +
      +
    1. Select the imported quickstart project.
      2. +
    2. From the menu, choose File –> New –> Other –> User Assistance –> Cheat Sheet, then click Next.
      3. +
    3. Select the quickstart folder, give it a name ‘cheatsheet.xml’, and choose Simple Cheat Sheet.
      4. +
    4. Click Finish. When it prompts you to open the cheatsheet for the quickstart project, click Yes.
      5. +
    3. +

  3. Populate the cheatsheet with useful information to help a user understand the quickstart.

    + +
      +
    1. Expand the Title in the content section on the left.
      2. +
    2. Select the Title field and modify it to something useful, for example: helloworld
      3. +
    3. Select the intro field and add introduction text to the Body, for example: This quickstart demonstrates the use of CDI 1.0 and Servlet 3.0. It is a simple application that can be used to verify the JBoss EAP server is configured and running correctly.
      4. +

    4. Select item, then under Command, click browse and select ‘Get current project’ under Uncategorized. This adds the following XML to the cheat sheet:

      +
      <command 
+required="true" 
+returns="currentProject"
+serialization="org.jboss.tools.project.examples.cheatsheet.getProjectForCheatsheet"/>
+
      +

      This command allows you to use the variable ${currentProject} instead of a hard-coded path name and ensures your cheat sheet will work regardless of the project location.

      5. +

    5. Add an item for each file or class you want to describe.

      + +
        +
      • This is dependent on the quickstart features you plan to demonstrate.
        • +
      • Provide a good description.
        • +
      • Add subitems to describe code sections and provide the line numbers that are referenced.
        • +
      6. +
    4. +

  4. Test your cheat sheet by opening it in JDBS.

    + +
      +
    1. Go through each step and make sure the descriptions are valid.
      2. +
    2. Click on each link to make sure it opens the file and highlights the correct lines of code.
      3. +
    5. +

  5. When you finish testing the cheat sheet, rename the file from cheatsheet.xml to .cheatsheet.xml and make sure it is located in the root directory of the quickstart.

    6. +

  6. Add the .cheatsheet.xml file using git add, commit the change, push it to your forked repository, and issue a pull.

    7. +

  7. If your cheat sheet is for the quickstart based on an archetype, it will automatically generate the cheat sheet for the archetype. However, you must add an <include>.cheatsheet.*</include> to the fileset for the root directory in the corresponding archetype’s archetype-metadata.xml file. See the jboss-javaee6-webapp-archetype archetype for an example.

    8. +
+ +

General Guidelines

+ + + +

Find Help

+ +

You can find additional help at the following locations:

+ + + +

Copy a Quickstart to Another Repository and Preserve Its History

+ +
    +

  1. In the source repository that currently contains the quickstarts, for example jboss-eap-quickstarts, create a branch for each quickstart you want to move. For example:

    +
    git fetch upstream
+git checkout -b <source_branch_name> upstream/master
+
    2. +

  2. To extract only one quickstart, in each source branch, run:

    +
    git filter-branch --subdirectory-filter <quickstart_name> -- --all
+
    3. +

  3. The previous step places the quickstart at the root of the tree. You need to create a directory using the quickstart name and move the files under it. To accomplish that task, in each source branch, run:

    +
    git filter-branch --tree-filter '(ls -A; mkdir <quickstart_name>; echo <quickstart_name>) | xargs mv'
+
    4. +

  4. Push each branch up to your own GitHub repository to make merging into the destination repository easy.

    +
    git push <your_remote_source_github> HEAD
+
    5. +

  5. Navigate to the target directory that does not yet contain the quickstarts, for example, jboss-sandbox-quickstarts.

    6. +

  6. Add the source GitHub repository as a remote to the local target destination repository.

    +
    git remote add <your_remote_source_github> https://github.com/<your_remote_source_github>/jboss-eap-quickstarts.git
+
    7. +

  7. Create a branch, into which you will merge the quickstarts.

    +
    git fetch upstream
+git checkout -b <target_branch_name> upstream/master 
+
    8. +

  8. For each quickstart source branch you want to merge, run:

    +
    git merge -s ours --no-commit <your_remote_source_github>/<source_branch_name>
+git read-tree --prefix=<quickstart_name> -u <your_remote_source_github>/<source_branch_name>
+git commit -m "Merge <quickstart_name> to XXX."
+
    9. +

  9. Now, rebase out the merges. Run:

    +
    git rebase upstream/master
+
    10. +

  10. This should succeed with no problems as you are merging into new subdirectories.

    11. +

  11. This process leaves your GitHub repository with a lot of unwanted junk in it, so you need to do some cleaning up! Run:

    +
    git gc --prune=all
+
    12. +

  12. Now push this branch to your target GitHub:

    +
    git push <your_remote_target_github> HEAD
+
    13. +

  13. Verify that it looks correct and send a pull request.

    14. +

  14. Remove the quickstarts from the source repository if they are no longer needed.

    15. +
+ +

Configure Maven on OpenShift

+ +

If your quickstart needs a Maven repository other than the standard repository configured on OpenShift, you can use the following procedure to configure Maven.

+ +

Note: The following substitution variables are used in these instructions:

+ + + +
    +

  1. When you create your OpenShift application using the rhc app create -a <app-name> -t jbosseap-6 command, you see messages similar to the following:

    + +

    Your application ‘YOUR_APP_NAME’ is now available.

    +
      URL:        http://YOUR_APP_NAME-YOUR_ACCOUNT_NAME.rhcloud.com/
+  SSH to:     APPLICATION_UUID@YOUR_APP_NAME-YOUR_ACCOUNT_NAME.rhcloud.com
+  Git remote: ssh://APPLICATION_UUID@YOUR_APP_NAME-YOUR_ACCOUNT_NAME.rhcloud.com/~/git/YOUR_APP_NAME.git/
+  Cloned to:  /CURRENT_PATH/YOUR_APP_NAME
+
    +

    Make note of the SSH to URL that is returned. You will need that URL later to copy files to your OpenShift application.

    2. +

  2. Create a Maven settings file that contains profiles for the repositories you need to test your quickstart.

    + +
    3. +

  3. Upload your settings.xml file to the OpenShift application app-root/data/ directory using the ‘SSH to’ URL displayed when you created the application. For example:

    +
    $ scp <SETTINGS_DIRECTORY>/settings.xml APPLICATION_UUID@YOUR_APP_NAME-YOUR_ACCOUNT_NAME.rhcloud.com:app-root/data
+
    4. +

  4. If you specified a local Maven repository, upload the zip file to the OpenShift application app-root/data/ directory using the ‘SSH to’ URL displayed when you created the application. For example:

    +
    $ scp <MAVEN_ZIP_DIRECTORY>/jboss-eap-6.2.0.CR1-maven-repository.zip  APPLICATION_UUID@YOUR_APP_NAME-YOUR_ACCOUNT_NAME.rhcloud.com:app-root/data
+
    +

    Wait until the upload completes before performing the next step. This takes a very long time!! When the upload process is complete, SSH into the same URL and unzip the Maven repository:

    +
    $ ssh APPLICATION_UUID@YOUR_APP_NAME-YOUR_ACCOUNT_NAME.rhcloud.com
+cd app-root/data
+unzip jboss-eap-6.2.0.CR1-maven-repository.zip 
+
    5. +

  5. To direct Maven to use the uploaded settings.xml file, create a file in the .openshift/action_hooks/ directory named pre_build_jbosseap, containing this line:

    +
    export MAVEN_ARGS="clean package -Popenshift -s ${OPENSHIFT_DATA_DIR}settings.xml -DskipTests"
+
    6. +

  6. Use git add to add the above file, along with the updated src/ and pom.xml files to GitHub.

    +
    $ git add src/ pom.xml .openshift/action_hooks/pre_build_jbosseap
+
    7. +

  7. Issue the git commit and git push in the usual manner.

    8. +
+ diff --git a/README.html b/README.html new file mode 100644 index 000000000..ed087ddab --- /dev/null +++ b/README.html @@ -0,0 +1,546 @@ +README +

Red Hat JBoss Web Framework Kit (WFK) Quickstarts

+ +

Summary: The quickstarts demonstrate Java EE 6 and a few additional technologies from the JBoss stack. They provide small, specific, working examples that can be used as a reference for your own project.

+ +

Introduction

+ +

These quickstarts run on Red Hat JBoss Enterprise Application Platform 6.1 or later with the Red Hat JBoss Web Framework Kit. We recommend using the JBoss EAP ZIP file. This version uses the correct dependencies and ensures you test and compile against your runtime environment.

+ +

Be sure to read this entire document before you attempt to work with the quickstarts. It contains the following information:

+ + + +

Available Quickstarts

+ +

The following is a list of the currently available quickstarts. The table lists each quickstart name, the technologies it demonstrates, gives a brief description of the quickstart, and the level of experience required to set it up. For more detailed information about a quickstart, click on the quickstart name.

+ +

Some quickstarts are designed to enhance or extend other quickstarts. These are noted in the Prerequisites column. If a quickstart lists prerequisites, those must be installed or deployed before working with the quickstart.

+ +

Quickstarts with tutorials in the Get Started Developing Applications are noted with two asterisks ( ** ) following the quickstart name.

+ +

Note: The quickstart README files use the replaceable value EAP_HOME to denote the path to the JBoss EAP 6 installation. When you encounter this value in a README file, be sure to replace it with the actual path to your JBoss EAP 6 installation. The ‘JBOSS_HOME’ environment variable, which is used in scripts, continues to work as it has in the past.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Quickstart NameDemonstrated TechnologiesDescriptionExperience Level RequiredPrerequisites
cdi-add-interceptor-binding DeltaSpike, CDICreating a basic CDI extension to automatically add an interceptor bindingIntermediate
contacts-mobile-basic HTML5, JavaScript, REST, jQuery, jQuery MobileA basic example of CRUD operations in a mobile only website.Beginner
deltaspike-authorization CDI, Deltaspike, JSFDemonstrate the creation of a custom authorization example using @SecurityBindingType from DeltaSpikeBeginner
deltaspike-beanbuilder DeltaSpike, CDIShows how to create new beans using DeltaSpike utilities.Advanced
deltaspike-beanmanagerprovider Deltaspike, JPA, JSF, CDIShows how to use DeltaSpike BeanManagerProvider to access CDI in a EntityListenerIntermediate
deltaspike-deactivatable DeltaSpike, CDIDemonstrate usage of Deactivatable.Beginner
deltaspike-exception-handling DeltaSpike, JSF, CDIException being handled by different handlers and purposeIntermediate
deltaspike-helloworld-jms CDI, DeltaSpike, JMSDemonstrates a JMS client using DeltaSpike configuration propertiesIntermediate
deltaspike-partialbean-advanced DeltaSpike, CDIDemonstrates a partial bean providing a dynamic implementation of a generic Entity Query serviceAdvanced
deltaspike-partialbean-basic DeltaSpike, CDIDemonstrates a class providing a dynamic implementation of a DeltaSpike Partial BeanAdvanced
deltaspike-projectstage CDI, Deltaspike, JSFDemonstrate usage of DeltaSpike project stage and shows usage of a conditional @ExcludeBeginner
helloworld-errai GWT, JAX-RS, ErraiHelloworld using the Errai frameworkBeginner
helloworld-gwt GWTDemonstrates the use of CDI 1.0 and JAX-RS with a GWT front-end clientBeginner
helloworld-html5 HTML5, JAX-RS, CDIBasic HTML5 |Demonstrates the use of CDI 1.0 and JAX-RS using the HTML5 architecture and RESTful services on the backendBeginner
helloworld-rf JSF, RichFaces, CDISimilar to the helloworld quickstart, but with a JSF and RichFaces front endBeginner
kitchensink-angularjs BV, CDI, EJB, JAX-RS, JPA, JPA, AngularJSAn example that incorporates multiple technologiesIntermediate
kitchensink-angularjs-bootstrap BV, CDI, EJB, JAX-RS, JPA, JPA, AngularJSAn example that incorporates multiple technologiesIntermediate
kitchensink-backbone BV, CDI, EJB, JAX-RS, JPA, JPA, BackboneAn example of Backbone.js integrated with jQuery, REST, and a Java back-end running on JBoss.Intermediate
kitchensink-cordova Apache Cordova, REST, HTML5Based on kitchensink, but uses hybrid HTML5 running as a native application on mobilesIntermediate
kitchensink-cordova-contacts Apache Cordova, REST, HTML5Based on kitchensink, but uses hybrid HTML5 running as a native application on mobilesIntermediate
kitchensink-deltaspike BV, DeltaSpike, JAX-RS, JPA, JPA, JSF, CDIA version of kitchensink that uses DeltaSpike @TransactionalIntermediate
kitchensink-html5-mobile HTML5, REST, CDIBased on kitchensink, but uses HTML5, making it suitable for mobile and tablet computersBeginner
kitchensink-rf BV, EJB, JAX-RS, JPA, JPA, JSF, RichFaces, CDIThe canonical JSF kitchensink quickstart implemented with JSF and RichFacesIntermediate
richfaces-validation RichFacesDemonstrates RichFaces and bean validationBeginner
shrinkwrap-resolver Arquillian, Shrinkwrap, CDIDemonstrate usage of some Shrinkwrap resolver use casesIntermediate
spring-greeter JSP, and JPA 2.0, Spring MVCDemonstrates the use of JPA 2.0 and JSP in Red Hat JBoss Enterprise Application Platform 6.1 or later.Beginner
spring-kitchensink-asyncrequestmapping JPA, JSON, JUnit, Spring, JSPAn example that incorporates multiple technologiesIntermediate
spring-kitchensink-basic JPA, JSON, JUnit, Spring, JSPAn example that incorporates multiple technologiesIntermediate
spring-kitchensink-controlleradvice JPA, JSON, JUnit, Spring, JSPAn example that incorporates multiple technologiesIntermediate
spring-kitchensink-matrixvariables JPA, JSON, JUnit, Spring, JSPAn example that incorporates multiple technologiesIntermediate
spring-kitchensink-springmvctest JPA, JSON, JUnit, Spring, JSPAn example that incorporates multiple technologiesIntermediate
spring-petclinic AOP, JMX, JSP, Junit, Spring Data, Spring MVC Annotations, and Dandellion, webjars, JPA 2.0An example that incorporates multiple technologies in Red Hat JBoss Enterprise Application Platform 6.1 or later.Advanced
spring-resteasy Spring, ResteasyBasic example demonstrating how a spring application can be packaged for JBoss EAPBeginner
+ +

Suggested Approach to the Quickstarts

+ +

We suggest you approach the quickstarts as follows:

+ + + +

System Requirements

+ +

The application this project produces is designed to be run on Red Hat JBoss Enterprise Application Platform (EAP) 6.1 or later with the Red Hat JBoss Web Framework Kit (WFK) 2.5.

+ +

To run these quickstarts with the provided build scripts, you need the following:

+ +
    +

  1. Java 1.6, to run JBoss AS and Maven. You can choose from the following:

    + +
    2. +

  2. Maven 3.0.0 or later, to build and deploy the examples

    + +
    3. +

  3. The JBoss EAP distribution ZIP.

    + +
    4. +

  4. You can also use JBoss Developer Studio or Eclipse to run the quickstarts.

    5. +
+ +

Configure Maven

+ +

Configure Maven to Build and Deploy the Quickstarts

+ +

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.

+ +

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.

+ +
    +

  1. Locate the Maven install directory for your operating system. It is usually installed in ${user.home}/.m2/.

    +
        For Linux or Mac:   ~/.m2/
+    For Windows: "\Documents and Settings\USER_NAME\.m2\"  -or-  "\Users\USER_NAME\.m2\"
+
    2. +

  2. If you have an existing settings.xml file, rename it so you can restore it later.

    +
        For Linux or Mac:  mv ~/.m2/settings.xml ~/.m2/settings-backup.xml
+    For Windows: ren "\Documents and Settings\USER_NAME\.m2\settings.xml" settings-backup.xml
+            -or- ren "\Users\USER_NAME\.m2\settings.xml" settings-backup.xml
+
    3. +

  3. If you have an existing repository/ directory, rename it so you can restore it later. For example

    +
        For Linux or Mac:  mv ~/.m2/repository/ ~/.m2/repository-backup/
+    For Windows: ren "\Documents and Settings\USER_NAME\.m2\repository\" repository-backup
+            -or- ren "\Users\USER_NAME\.m2\repository\" repository-backup
+
    4. +

  4. Copy the settings.xml file from the root of the quickstarts directory to your Maven install directory.

    +
        For Linux or Mac:  cp QUICKSTART_HOME/settings.xml  ~/.m2/settings.xml
+    For Windows: copy QUICKSTART_HOME/settings.xml "\Documents and Settings\USER_NAME\.m2\settings.xml"
+            -or- copy QUICKSTART_HOME/settings.xml "\Users\USER_NAME\.m2\settings.xml"
+
    5. +
+ +

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

+ +

Restore Your Maven Configuration When You Finish Testing the Quickstarts

+ +
    +

  1. Locate the Maven install directory for your operating system. It is usually installed in ${user.home}/.m2/.

    +
        For Linux or Mac:   ~/.m2/
+    For Windows: "\Documents and Settings\USER_NAME\.m2\"  -or-  "\Users\USER_NAME\.m2\"
+
    2. +

  2. Restore the settings.xml file/

    +
        For Linux or Mac:  mv ~/.m2/settings-backup.xml ~/.m2/settings.xml
+    For Windows: ren "\Documents and Settings\USER_NAME\.m2\settings-backup.xml" settings.xml
+            -or- ren "\Users\USER_NAME\.m2\settings-backup.xml" settings.xml
+
    3. +

  3. Restore the repository/ directory

    +
        For Linux or Mac:  mv ~/.m2/repository-backup/ ~/.m2/repository/
+    For Windows: ren "\Documents and Settings\USER_NAME\.m2\repository-backup\" repository
+            -or- ren "\Users\USER_NAME\.m2\repository-backup\" repository
+
    4. +
+ +

Maven Profiles

+ +

Profiles are used by Maven to customize the build environment. The pom.xml in the root of the quickstart directory defines the following profiles:

+ + + +

Run the Quickstarts

+ +

The root folder of each individual quickstart contains a README file with specific details on how to build and run the example. In most cases you do the following:

+ + + +

Start the JBoss EAP Server

+ +

Before you deploy a quickstart, in most cases you need a running JBoss EAP server. A few of the Arquillian tests do not require a running server. This will be noted in the README for that quickstart.

+ +

The JBoss EAP server can be started a few different ways.

+ + + +

The README for each quickstart will specify which configuration is required to run the example.

+ +

Start the Default JBoss EAP Server

+ +

To start JBoss EAP:

+ +
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +

  2. The following shows the command line to start the JBoss EAP server:

    +
    For Linux:   EAP_HOME/bin/standalone.sh
+For Windows: EAP_HOME\bin\standalone.bat
+
    3. +
+ +

Start the JBoss EAP Server with the Full Profile

+ +

To start JBoss EAP with the Full Profile:

+ +
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +

  2. The following shows the command line to start the JBoss EAP server with the full profile:

    +
    For Linux:   EAP_HOME/bin/standalone.sh -c standalone-full.xml
+For Windows: EAP_HOME\bin\standalone.bat -c standalone-full.xml
+
    3. +
+ +

Start the JBoss EAP Server with Custom Configuration Options

+ +

To start JBoss EAP with custom configuration options:

+ +
    +
  1. Open a command line and navigate to the root of the JBoss EAP directory.
    2. +

  2. The following shows the command line to start the JBoss EAP server. Replace the CUSTOM_OPTIONS with the custom optional parameters specified in the quickstart.

    +
    For Linux:   EAP_HOME/bin/standalone.sh CUSTOM_OPTIONS
+For Windows: EAP_HOME\bin\standalone.bat CUSTOM_OPTIONS
+
    3. +
+ +

Build and Deploy the Quickstarts

+ +

See the README file in each individual quickstart folder for specific details and information on how to run and access the example.

+ +

Build the Quickstart Archive

+ +

In some cases, you may want to build the application to test for compile errors or view the contents of the archive.

+ +
    +
  1. Open a command line and navigate to the root directory of the quickstart you want to build.
    2. +

  2. Use this command if you only want to build the archive, but not deploy it:

    +
        mvn clean package
+
    3. +
+ +

Build and Deploy the Quickstart Archive

+ +
    +
  1. Make sure you start the JBoss EAP server as described in the README.
    2. +
  2. Open a command line and navigate to the root directory of the quickstart you want to run.
    3. +

  3. Use this command to build and deploy the archive:

    +
        mvn clean package jboss-as:deploy
+
    4. +
+ +

Undeploy an Archive

+ +

The command to undeploy the quickstart is simply:

+
    mvn jboss-as:undeploy
+
+

Verify the Quickstarts Build with One Command

+ +
+ +

You can verify the quickstarts build using one command.

+ +

To build the quickstarts:

+ +
    +
  1. Do not start the JBoss EAP server.
    2. +
  2. Open a command line and navigate to the root directory of the quickstarts.
    3. +

  3. Use this command to build the quickstarts:

    +
        mvn clean install
+
    4. +
+ +

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.

+
    For Linux:   export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"
+    For Windows: SET MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"
+
+

Undeploy the Deployed Quickstarts with One Command

+ +
+ +

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.

+ +

You can undeploy quickstarts using the following procedure:

+ +
    +
  1. Start the JBoss EAP server.
    2. +
  2. Open a command line and navigate to the root directory of the quickstarts.
    3. +

  3. Use this command to undeploy any deployed quickstarts:

    +
        mvn jboss-as:undeploy -fae
+
    4. +
+ +

To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart’s README file.

+ +

Run the Arquillian Tests

+ +
+ +

Some of the quickstarts provide Arquillian tests. By default, these tests are configured to be skipped, as Arquillian tests an application on a real server, not just in a mocked environment.

+ +

You can either start the server yourself or let Arquillian manage its lifecycle during the testing. The individual quickstart README should tell you what to expect in the console output and the server log when you run the test.

+ +
    +

  1. Test the quickstart on a remote server

    + +
    2. +

  2. Test the quickstart on a managed server

    + +

    Arquillian’s managed container adapter requires that your server is not running as it will start the container for you. However, you must first let it know where to find the JBoss EAP directory. The simplest way to do this is to set the JBOSS_HOME environment variable to the full path to your JBoss EAP directory. Alternatively, you can set the path in the jbossHome property in the Arquillian configuration file.

    + +
    3. +
+ +

Use JBoss Developer Studio or Eclipse to Run the Quickstarts

+ +

You can also deploy the quickstarts from Eclipse using JBoss tools. For more information on how to set up Maven and the JBoss tools, refer to the JBoss Enterprise Application Platform Development Guide or Get Started Developing Applications.

+ +

Build and Deploy the Quickstart - to OpenShift

+ +

Note: The following variables are used in these instructions. Be sure to replace them as follows:

+ + + +

Create an OpenShift Account and Domain

+ +

If you do not yet have an OpenShift account and domain, Sign in to OpenShift to create the account and domain.

+ +

Get Started with OpenShift details how to install the OpenShift Express command line interface.

+ +

Create the OpenShift 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 APPLICATION_NAME -t jbosseap-6
+
+

NOTE: The domain name for this application will be APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com`. Be sure to replace the variables as noted above.

+ +

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:

+
Application Options
+-------------------
+  Namespace:  YOUR_DOMAIN_NAME
+  Cartridges: jbosseap-6 (addtl. costs may apply)
+  Gear Size:  default
+  Scaling:    no
+
+Creating application 'APPLICATION_NAME' ... done
+
+Waiting for your DNS name to be available ... done
+
+Cloning into 'APPLICATION_NAME'...
+Warning: Permanently added the RSA host key for IP address '54.237.58.0' to the list of known hosts.
+
+Your application 'APPLICATION_NAME' is now available.
+
+  URL:        http://APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com/
+  SSH to:     APPLICATION_UUID@APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com
+  Git remote: ssh://APPLICATION_UUID@APPLICATION_NAME-YOUR_DOMAIN_NAME.rhcloud.com/~/git/APPLICATION_NAME.git/
+  Cloned to:  CURRENT_DIRECTORY/APPLICATION_NAME
+
+Run 'rhc show-app APPLICATION_NAME' for more details about your app.
+
+

The create command creates a git 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 APPLICATION_NAME and YOUR_DOMAIN_NAME with your OpenShift application and account domain name.

+ +

Migrate the Quickstart Source

+ +

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 created by the OpenShift command and tell git to remove the source and pom files:

+
cd APPLICATION_NAME
+git rm -r src pom.xml
+
+

Copy the source for the QUICKSTART_NAME quickstart into this new git repository:

+
cp -r QUICKSTART_HOME/QUICKSTART_NAME/src .
+cp QUICKSTART_HOME/QUICKSTART_NAME/pom.xml .
+
+

Configure the OpenShift Server

+ +

See individual quickstart README file for any specific server configuration requiremens.

+ +

Deploy the OpenShift Application

+ +

You can now deploy the changes to your OpenShift application using git as follows:

+
git add src pom.xml
+git commit -m "QUICKSTART_NAME quickstart 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.

+ +

Test the OpenShift Application

+ +

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 APPLICATION_NAME and YOUR_DOMAIN_NAME variables in the URL with your OpenShift application and account domain name.

+ + + +

You can use the OpenShift command line tools or the OpenShift web console to discover and control the application.

+ +

Delete the OpenShift Application

+ +

When you are finished with the application you can delete it as follows:

+
rhc app-delete -a APPLICATION_NAME
+
+

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.

+ + + +

Optional Components

+ +

The following components are needed for only a small subset of the quickstarts. Do not install or configure them unless the quickstart requires it.

+ + + +

Add a Management or Application User

+ +

By default, JBoss EAP is now 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.

+ +

The following procedures describe how to add a user with the appropriate permissions to run the quickstarts that depend on them.

+ +

Add a Management User

+ +

You can choose to run the script interactively or you can pass arguments on the command line.

+ +
Add a Management User Interactively
+ +
    +
  1. Open a command line.
    2. +

  2. Type the command for your operating system

    +
    For Linux:   EAP_HOME/bin/add-user.sh
+For Windows: EAP_HOME\bin\add-user.bat
+
    3. +

  3. You should see the following response:

    +
    What type of user do you wish to add? 
+
+a) Management User (mgmt-users.properties) 
+b) Application User (application-users.properties)
+(a):
+
    +

    At the prompt, press enter to use the default Management User.

    4. +

  4. You should see the following response:

    +
    Enter the details of the new user to add.
+Using realm 'ManagementRealm' as discovered from the existing property files.
+Username :
+
    5. +

  5. Enter the Username and, at the next prompt, enter the Password.

    +
    Username : admin
+Password : (choose a password for the admin user)
+
    +

    Repeat the password.

    6. +

  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.

    7. +

  7. Choose yes for the remaining prompts.

    8. +
+ +
Add a Management User Passing Arguments on the Command Line
+ +

If you prefer, you can create the management user non-interactively by passing each argument on the command line.

+ +

For example, to add the Management User admin in the default ManagementRealm realm with password adminPass1!, type the following:

+
    For Linux:   EAP_HOME/bin/add-user.sh -u 'admin' -p 'adminPass1!'
+    For Windows: EAP_HOME\bin\add-user.bat -u 'admin' -p 'adminPass1!'
+
+

Add an Application User

+ +

You can choose to run the script interactively or you can pass arguments on the command line.

+ +
Add an Application User Interactively
+ +
    +
  1. Open a command line
    2. +

  2. Type the command for your operating system

    +
    For Linux:   EAP_HOME/bin/add-user.sh
+For Windows: EAP_HOME\bin\add-user.bat
+
    3. +

  3. You should see the following response:

    +
    What type of user do you wish to add? 
+
+a) Management User (mgmt-users.properties) 
+b) Application User (application-users.properties)
+(a):
+
    +

    At the prompt, type: b

    4. +

  4. You should see the following response:

    +
    Enter the details of the new user to add.
+Using realm 'ApplicationRealm' as discovered from the existing property files.
+Username :
+
    5. +

  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!.

    +
    Username : quickstartUser
+Password : quickstartPwd1!
+
    6. +

  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

    7. +
+ +

Add an Application User Passing Arguments on the Command Line

+ +

If you prefer, you can create the application user non-interactively by passing each argument on the command line.

+ +

For example, to add the Application User quickstartUser in the ApplicationRealm realm with password quickstartPwd1! in group guest, type the following:

+
    For Linux:   EAP_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+    For Windows: EAP_HOME\bin\add-user.bat  -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest'
+
diff --git a/RELEASE_PROCEDURE.html b/RELEASE_PROCEDURE.html new file mode 100644 index 000000000..70ed69a53 --- /dev/null +++ b/RELEASE_PROCEDURE.html @@ -0,0 +1,86 @@ +README +

Quickstarts Release Procedure

+ +

Testing the quickstarts

+ +

Profiles are used in the root POM to separate out these groups, allowing you to test the quickstarts easily. For example, to run those that require only started Server:

+
  mvn clean install jboss-as:deploy jboss-as:undeploy -Parq-jbossas-remote 
+
+

Quickstarts in other repositories

+ +

If the quickstarts are stored in another repository, you may wish to merge them in from there, do this:

+ +
    +

  1. Add the other repo as a remote

    +
     git remote add -f <other repo> <other repo url>
+
    2. +

  2. Merge from the tag in the other repo that you wish to use. It is important to use a tag, to make tracking of history easier. We use a recursive merge strategy, always preferring changes from the other repo, in effect overwriting what we have locally.

    +
     git merge <tag> -s recursive -Xtheirs -m "Merge <Other repository name> '<Tag>'"
+
    3. +

  3. Review and push to upstream

    +
     git push upstream HEAD:master
+
    4. +
+ +

Rendering Markdown

+ +

The quickstarts use Redcarpet to process the markdown, the same processor used by GitHub. This builds on the basic markdown syntax, adding support for tables, code highlighting, relaxed code blocks etc). We add a couple of custom piece of markup - [TOC] which allows a table of contents, based on headings, to be added to any file, and [Quickstart-TOC], which adds in a table listing the quickstarts.

+ +

To render the quickstarts README’s you will need, a working Ruby and Python install, with the various gems and eggs set up.

+ +

To setup the environment you need to follow these steps. Certify to use the correct versions.

+ +
    +

  1. Install Ruby 1.9.X

    + +

    For RHEL you can use this spec

    2. +

  2. Install Ruby GEMs

    +
    gem install redcarpet nokogiri pygments.rb
+
    3. +
+ +

Then just run

+
    ./dist/release-utils.sh -m
+
+

To render all markdown files to HTML.

+ +

Publishing builds to Maven

+ +
    +
  1. You must have gpg set up and your key registered, as described at hhttp://blog.sonatype.com/people/2010/01/how-to-generate-pgp-signatures-with-maven/
    2. +

  2. You must provide a property gpg.passphrase in your settings.xml in the release profile e.g.

    +
      <profile>
+        <id>release</id>
+        <properties>
+            <gpg.passphrase>myPassPhrase</gpg.passphrase>
+        </properties>
+  </profile>
+
    3. +

  3. You must have a JBoss Nexus account, configured with the server id in settings.xml with the id jboss-releases-repository e.g.

    +
      <server>
+      <id>jboss-releases-repository</id>
+      <username>myUserName</username>
+      <password>myPassword</password>
+  </server>
+
    4. +

  4. Add org.sonatype.plugins plugin group to your settings.xml so nexus plugin can be available for publishing scripts.

    +
      <pluginGroups>
+      <pluginGroup>org.sonatype.plugins</pluginGroup>
+  </pluginGroups>
+
    5. +
+ +

Release Procedure

+ +
    +
  1. Make sure you have access to rsync files to filemgmt.jboss.org/download_htdocs/jbossas
    2. +
  2. Release the archetypes
    3. +

  3. Regenerate the quickstart based on archetypes

    +
     dist/release-utils.sh -r
+
    4. +

  4. Release

    +
     dist/release.sh -s <old snapshot version> -r <release version>
+
    +

    This will update the version number, commit and tag, build the distro zip and upload it to . Then it will reset the version number back to the snapshot version number.

    5. +
+