shared-doc/attributes.adoc

{productNameFull} ({productName}) Quickstarts

The quickstarts demonstrate {javaVersion} and a few additional technologies from the {productNameFull} stack. They provide small, specific, working examples that can be used as a reference for your own project.

Important

The quickstart README files are written in AsciiDoc, not only because the language is much more powerful than Markdown, but also also because it is possible to extract common instructions into separate files to be reused across the quickstarts. While this makes them more flexible and easier to maintain, unfortunately, included files do not render in a readable format in GitHub or in most text editors. The Maven plugin that is used to build and deploy the quickstarts can also generate fully rendered README.html instructions from the README.adoc files. For instructions on how to generate these files, see Build the README.html Files in the CONTRIBUTING guide.

Introduction

These quickstarts run on {productNameFull}. Each quickstart folder contains a README.adoc file that describes the quickstart features and provides instructions about how to build and run it.

The quickstarts are configured to use the correct Maven dependencies and ensure that you test and compile the quickstarts against the correct runtime environment.

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

• Suggested Approach to the Quickstarts: A suggested approach on how to work with the quickstarts.

• System Requirements: List of software required to run the quickstarts.

• Configure Maven: How to configure the Maven repository for use by the quickstarts.

• Run the Quickstarts: General instructions for building, deploying, and running the quickstarts.

• Run the Arquillian Tests: How to run the Arquillian tests provided by some of the quickstarts.

• Optional Components: How to install and configure optional components required by some of the quickstarts.

• Contributing Guide: This document contains information targeted for developers who want to contribute to {productName} developer projects.

• Available Quickstarts: List of the available quickstarts and details about each one.

Use of {jbossHomeName} and JBOSS_HOME Variables

The quickstart README files use the replaceable value {jbossHomeName} to denote the path to the {productName} installation. When you encounter this value in a README file, make sure you replace it with the actual path to your {productName} installation. The installation path is described in detail here: Use of {jbossHomeName} and JBOSS_HOME Variables.

shared-doc/suggested-approach.adoc

System Requirements

The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later.

All you need to build these projects is {buildRequirements}. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.

To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the {LinkGettingStartedGuide}[{GettingStartedBookName}] located on the Red Hat Customer Portal.

You can also run the quickstarts in {JBDSProductName} or Eclipse.

Run the Quickstarts

Build and Deploy a Quickstart

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

• Start the {productName} server.

• Build the archive.

• Deploy the quickstart.

• Undeploy the quickstart when you are finished testing.

Verify All Quickstarts Build with One Command

You can also verify that all of the quickstarts build using one command. However, quickstarts that have complex dependencies must be skipped. For example, the resteasy-jaxrs-client quickstart is a RESTEasy client that depends on the deployment of the helloworld-rs quickstart. The root pom.xml file defines a complex-dependencies profile to exclude these quickstarts from the root build process.

To build all of the quickstarts:

1. Open a terminal and navigate to the root directory of the quickstarts.

2. Use the following command to build the quickstarts that do not have complex dependencies:

   $ mvn clean install '-Pdefault,!complex-dependencies'

Undeploy All Deployed Quickstarts with One Command

To undeploy all of the 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 or only have Arquillian tests and do not deploy archives to the server.

You can undeploy quickstarts using the following procedure:

1. Start the {productName} server.

2. Open a terminal and navigate to the root directory of the quickstarts.

3. Use the following command to undeploy any deployed quickstarts.

   $ mvn wildfly:undeploy -fae

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

Run the Quickstarts in {JBDSProductName} or Eclipse

You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see Use {JBDSProductName} or Eclipse to Run the Quickstarts.

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.

• Create Users Required by the Quickstarts: Add a Management or Application user for the quickstarts that run in a secured mode.

• Configure the PostgreSQL Database for Use with the Quickstarts: The PostgreSQL database is used for the distributed transaction quickstarts.

• Configure Byteman for Use with the Quickstarts: This tool is used to demonstrate crash recovery for distributed transaction quickstarts.

shared-doc/available-quickstarts.adoc