Repo layout
=========== 
deployments/ - location for built wars (Details below)
src/ - maven src structure
pom.xml - maven build file  
.openshift/ - location for openshift specific files
.openshift/config/ - location for configuration files such as standalone.xml (used to modify jboss config such as datasources) 
../data - For persistent data (also in env var OPENSHIFT_DATA_DIR)
.openshift/action_hooks/build - Script that gets run every push, just prior to
    starting your app


Details about layout and deployment options
==================
There are two options for deploying content to the JBoss Application Server within OpenShift Express:

1) (Typical) You can upload your content in a maven src structure as is this sample project and on 
git push have the application built and deployed.  For this to work you'll need your pom.xml at the 
root of your repository and a maven-war-plugin like in this sample to move the output from the build
to the deployments directory.  By default the warName is ROOT within pom.xml.  This will cause the 
webapp contents to be rendered at http://app_name-namespace.rhcloud.com/.  If you change the warName in 
pom.xml to app_name, your base url would then become http://app_name-namespace.rhcloud.com/app_name.

Note: If you are building locally you'll also want to add any output wars/ears under deployments 
from the build to your .gitignore file.

or

2) You can git push prebuilt wars (with the corresponding .dodeploy file for exploded wars) into deployments/.  To do this
with the default repo you'll want to first run 'git rm -r src/ pom.xml' from the root of your repo.

Basic workflows for deploying prebuilt content (each operation will require associated git add/commit/push operations to take effect):

A) Add new zipped content and deploy it:

1. cp target/example.war deployments/

B) Add new unzipped content and deploy it:

1. cp -r target/example.war/ deployments/
2. touch deployments/example.war.dodeploy

C) Undeploy currently deployed content:

1. git rm deployments/example.war.dodeploy deployments/example.war

D) Replace currently deployed zipped content with a new version and deploy it:

1. cp target/example.war deployments/

E) Replace currently deployed unzipped content with a new version and deploy it:

1. git rm -rf deployments/example.war/
2. cp -r target/example.war/ deployments/
3. touch deployments/example.war.dodeploy



Whether you choose option 1) or 2) the end result will be the application 
deployed into the deployments directory. The deployments directory in the 
JBoss Application Server distribution is the location end users can place 
their deployment content (e.g. war, ear, jar, sar files) to have it 
automatically deployed into the server runtime.

The filesystem deployment scanner in AS 7 and later works differently from 
previous JBoss AS releases. The scanner will no longer attempt to directly 
monitor the deployment content and decide if or when the end user wishes 
the content to be deployed. Instead, the scanner relies on a system of marker 
files, with the user's addition or removal of a marker file serving as a sort
of command telling the scanner to deploy, undeploy or redeploy content.

The marker files always have the same name as the deployment content to which
they relate, but with an additional file suffix appended. For example, the 
marker file to indicate the example.war should be deployed is named 
example.war.dodeploy. Different marker file suffixes have different meanings.

The relevant marker file types are:

.dodeploy     -- Placed by the user to indicate that the given content should 
                 be deployed into the runtime (or redeployed if already 
                 deployed in the runtime.)

.deploying    -- Placed by the deployment scanner service to indicate that it 
                 has noticed a .dodeploy file and is in the process of 
                 deploying the content. This marker file will be deleted when 
                 the deployment process completes.
              
.deployed     -- Placed by the deployment scanner service to indicate that the 
                 given content has been deployed into the runtime. If an end 
                 user deletes this file, the content will be undeployed.
               
.faileddeploy -- Placed by the deployment scanner service to indicate that the 
                 given content failed to deploy into the runtime. The content 
                 of the file will include some information about the cause of 
                 the failure.

.undeploying  -- Placed by the deployment scanner service to indicate that it 
                 has noticed a .deployed file has been deleted and the 
                 content is being undeployed. This marker file will be deleted 
                 when the undeployment process completes.
              
.undeployed   -- Placed by the deployment scanner service to indicate that the 
                 given content has been undeployed from the runtime. If an end 
                 user deletes this file, it has no impact.


Environment Variables
=====================

OpenShift Express provides several environment variables to reference for ease
of use.  The following list are some common variables but far from exhaustive:

    System.getenv("OPENSHIFT_APP_NAME")  - Application name
    System.getenv("OPENSHIFT_APP_DIR")   - Application dir
    System.getenv("OPENSHIFT_DATA_DIR")  - For persistent storage (between pushes)
    System.getenv("OPENSHIFT_TMP_DIR")   - Temp storage (unmodified files deleted after 10 days)

When embedding a database using rhc-ctl-app, you can reference environment
variables for username, host and password:

    System.getenv("OPENSHIFT_DB_HOST")      - DB host
    System.getenv("OPENSHIFT_DB_PORT")      - DB Port
    System.getenv("OPENSHIFT_DB_USERNAME")  - DB Username
    System.getenv("OPENSHIFT_DB_PASSWORD")  - DB Password

To get a full list of environment variables, simply add a line in your
.openshift/action_hooks/build script that says "export" and push.