Jenkins
=======

A note about this repository.  By default it is useless, users can safely
delete it.

Repo layout
=========== 
.openshift/action_hooks/pre_build - Script that gets run every git push before the build
.openshift/action_hooks/build - Script that gets run every git push as part of the build process
.openshift/action_hooks/deploy - Script that gets run every git push after build but before the app is restarted
.openshift/action_hooks/post_deploy - Script that gets run every git push after the app is restarted


Quickstart
==========

Jenkins integrates with other openshift applications.  To use start building
against Jenkins, embed the jenkins-client into an existing application.  The
below example will cause app "myapp" to start building against Jenkins.

 $ rhc app cartridge add -a myapp -c jenkins-client-1.4

From then on, running a "git push" will cause the build process to happen
inside a Jenkins builder instead of inside your normal application compute
space.

Benefits
========
. Archived build information
. No application downtime during the build process
. Failed builds do not get deployed (leaving the previous working version in place). 
. Jenkins builders have additional resources like memory and storage
. A large community of Jenkins plugins

Build/Deploy Process
====================

In OpenShift the Build/Deploy process has 4 steps.

1) Pre-Receive - This happens as you git push, but before the push is fully
    committed
2) Pre-Build - This happens after the application is stopped and the new 
     repo dir has been deployed but before the build.  Runs the 
     .openshift/action_hooks/pre_build script
3) Build - This builds your application, downloads required deps, executes the
    .openshift/action_hooks/build script and preps everything for deployment.
4) Deploy - This does any prep work to get the application ready to be started
    including running the .openshift/action_hooks/deploy script.  This step
    happens right before the application is issued a start
5) Post-Deploy - This step allows for interaction with the running application
    including running the .openshift/action_hooks/post_deploy script.  This step
    happens right after the application is started


Building Without Jenkins
------------------------

Building without Jenkins uses your application space as part of the build
and test process.  Because of this, the application is shut down so its memory
can be used for building.  The following steps take place

1) User issues a 'git push'
2) Application is shut down.
3) Git application files are put in place
4) .openshift/action_hooks/pre_build is executed
5) .openshift/action_hooks/build is executed
6) .openshift/action_hooks/deploy is executed
7) .openshift/action_hooks/post_deploy is executed
8) Application is started

Building with Jenkins
---------------------

Building with Jenkins uses dedicated application space that can be larger
then the application runtime space.  Because the build happens in its own
dedicated jail, the running application is not shutdown or changed in any way
until after the build is a success.  If it is not, the current active running
application will continue to run.  However, a failure in the deploy process 
(deploy/start/post_deploy) may still leave the app partially deployed or 
inaccessible.  During a build the following steps take place:

1) User issues a git push
2) Jenkins is notified a new push is ready.
3) A dedicated Jenkins slave (builder) is created.  It can be seen by using
   the 'rhc domain show' command.  The app name will be the same as the originating
   app plus "bldr" tagged onto the end.  Note:  This requires the first 28 chars
   of app name be unique or builders will be shared (can cause issues).
4) Jenkins runs the build
5) Content from originating app is downloaded to the builder app through git and rsync
   (Git for source code and rsync for existing libraries).
6) ci_build.sh is called from the Jenkins shell which sets up the builder app for the 
   Jenkins environment
6a) .openshift/action_hooks/pre_build is executed on the Jenkins builder
6b) Any built in bundling steps (php pear processing, python virtual env, etc) are
    performed.
6c) .openshift/action_hooks/build is executed on the Jenkins builder
7) Any additional desired steps are executed from the Jenkins shell (Maven build, 
   Gem install, test cases, etc).
8) Jenkins stops the current running application
9) Jenkins rsyncs all new content over to the originating application
10) .openshift/action_hooks/deploy is executed on the originating application
11) Jenkins starts the originating application
12) .openshift/action_hooks/post_deploy is executed on the originating application
13) Jenkins archives build artifacts for later reference
14) After 15 minutes of idle time, the 'build app' will be destroyed and will
    no longer show up with the 'rhc domain show' command.  The build artifacts
    however, will still exist in Jenkins and can be viewed there.

Users can look at the build job by clicking on it in the Jenkins interface and
going to "configure".  It is the Jenkins' build job to stop, sync and start the
application once a build is complete.