BundleWorks - Example 3

Examples
#1 - Build Environment
#2 - CI Server
#3 - WebApp Deployment
#4 - WebApp Build

Example 3 - WebApp Deployment

Overview

This example shows how BundleWorks can be used to deploy a custom Java web application into multiple environments running the Tomcat servlet container. The next example shows how this same custom web application can be built and bundled using ant and BundleWorks.

In this example, there are two environments, staging and test. Each environment contains both the JDK and Tomcat deployed bundles. The JDK bundle is a loadable bundle, while the Tomcat bundle is an executable bundle. Both the staging and test environments have separate Tomcat instances, each with their own work directories but sharing the same Tomcat bundle in /opt/bundles.

In this example, the staging environment contains a more stable version (1.0) of the custom web application, helloweb. The test environment contains the latest development version of helloweb (2.0rc1). The helloweb bundle contains scripts for installing, upgrading, and rolling back the application. These scripts use a BundleWorks feature called broadcasting. This allows a bundle to broadcast a message to other bundles within an environment. In this case, the webhello bundle broadcasts wardeploy and warundeploy messages, which the Tomcat bundle handles by updating its webapp directory.

Bundles

Tomcat 5.5.25 - Apache Tomcat servlet container
JDK 1.5.0_13 - Java5 development kit
helloweb 1.0 and 2.0rc1 - Custom Java web application

Environments

staging - contains Tomcat, JDK and a stable version of helloweb (1.0)
test - contains Tomcat, JDK, and a development version of helloweb (2.0rc1)

Details

/opt/bundles

   helloweb/

      1.0/ [1]

         bundle/

            actions/ [2]

               install.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_install_workdir
prompt_for_string "Enter a message to display:" HELLO_MESSAGE
replace_vars "$WORK_DIR/config/hello.properties"
java_webapp_install_war

               rollback.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_rollback_war

               uninstall.sh

#!/bin/sh

. "BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_uninstall_war

               upgrade.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_upgrade_war

            config/

               hello.properties  [3]

message=@{HELLO_MESSAGE}

            info  [4]

         shared/

war

               helloweb.war  [5]

      2.0rc1/

         bundle/

            actions/ [6]

               install.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_install_workdir
prompt_for_string "Enter a message to display:" HELLO_MESSAGE
prompt_for_choice "Select a color:" "red orange yellow green blue indigo violet" \
   "Enter selection:" HELLO_COLOR
replace_vars "$WORK_DIR/config/hello.properties"
java_webapp_install_war

               rollback.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

if [ `echo $TO_VERSION | grep '^1.0'` ]; then
   echo "Rolling back to version '$TO_VERSION'"
   remove_property "$WORK_DIR/config/hello.properties" "color"     
fi
java_webapp_rollback_war

               uninstall.sh

#!/bin/sh

. "BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_uninstall_war

               upgrade.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

if [ `echo $FROM_VERSION | grep '^1.0'` ]; then
   echo "Upgrading from version '$FROM_VERSION'"
   prompt_for_choice "Select a color:" "red orange yellow green blue indigo violet" \
      "Enter selection:" color
   add_property "$WORK_DIR/config/hello.properties" "color" "$color"       
fi
java_webapp_upgrade_war

            config/

               hello.properties  [7]

message=@{HELLO_MESSAGE}
color=@{HELLO_COLOR}

            info

         shared/

war

               helloweb.war

   jdk/

      1.5.0_13/ [8]

         bundle/

            actions/

               load.sh

env_set JAVA_HOME /usr/java/jdk1.5.0_13
env_prepend_path PATH $JAVA_HOME/bin

               unload.sh

env_unprepend_path PATH $JAVA_HOME/bin
env_unset JAVA_HOME

            info

   tomcat/

      5.5.25/ [9]

         bundle/

            actions/ [10]

               common.sh [11]

CATALINA_HOME="$BUNDLE_HOME/shared"
CATALINA_BASE="$WORK_DIR"
export CATALINA_HOME CATALINA_BASE

               install.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

if [ -n "$WORK_DIR" -a -d "$WORK_DIR" ]; then
    HTTP_PORT=8080
    prompt_for_int "Enter port for http requests" HTTP_PORT
    HTTPS_PORT=`expr 8443 + $HTTP_PORT - 8080`
    prompt_for_int "Enter port for https requests" HTTPS_PORT
    AJP_PORT=`expr 8009 + $HTTP_PORT - 8080`
    prompt_for_int "Enter port for apache connector" AJP_PORT
    SHUTDOWN_PORT=`expr 8005 + $HTTP_PORT - 8080`
    prompt_for_int "Enter shutdown port" SHUTDOWN_PORT

    echo "Updating work directory..."
    mkdir "$WORK_DIR/logs"
    mkdir "$WORK_DIR/temp"
    mkdir "$WORK_DIR/work"
    mkdir "$WORK_DIR/webapps"
    mkdir "$WORK_DIR/conf"
    copy_contents "$BUNDLE_HOME/shared/conf" "$WORK_DIR/conf"
    if [ -d "$BUNDLE_HOME/shared/shared" ]; then
        mkdir "$WORK_DIR/shared"
        copy_contents "$BUNDLE_HOME/shared/shared" "$WORK_DIR/shared"
    fi
    if [ -d "$BUNDLE_HOME/shared/webapps/ROOT" ]; then
        mkdir "$WORK_DIR/webapps/ROOT"
        copy_contents "$BUNDLE_HOME/shared/webapps/ROOT" "$WORK_DIR/webapps/ROOT"
    fi

    chmod -R +w "$WORK_DIR"

    echo "Updating configuration..."
    replace_vars "$WORK_DIR/conf/server.xml"
else
    echo "ERROR - No working directory found."
fi

               kill.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

psexp="-Dcatalina.base=$WORK_DIR"
matches=`find_matching_processes "$psexp"`
if [ -n "$matches" ]; then
    echo "Killing '$BUNDLE_NAME'..."
    kill -9 $matches 2>/dev/null
    wait_for_stop "$psexp"
    result=$?
    if [ $result -eq 0 ]; then
        rm -f "$WORK_DIR/$BUNDLE_NAME.pid"
    fi
    exit $result
else
    echo "'$BUNDLE_NAME' is not running."
    exit 1
fi

               setup.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

change_permissions "$BUNDLE_HOME/shared/bin" "+x" "f" "*.sh"

               start.sh

#!/bin/sh

. "$BUNDLE_HOME/bundle/actions/common.sh"
. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

psexp="-Dcatalina.base=$WORK_DIR"
matches=`find_matching_processes "$psexp"`
if [ -z "$matches" ]; then
    echo "Starting '$BUNDLE_NAME'..."
    "$CATALINA_HOME/bin/startup.sh" >"$WORK_DIR/$BUNDLE_NAME.out" 2>"$WORK_DIR/$BUNDLE_NAME.err"
    wait_for_start "$psexp"
    result=$?
    if [ $result -eq 0 ]; then
        find_matching_processes "$psexp" >"$WORK_DIR/$BUNDLE_NAME.pid"
        # Check each webapp for config changes
        oldifs=$IFS
        # Set IFS to empty to handle names with whitespace
        IFS=
        for app in $WORK_DIR/webapps/*; do
            app=`basename $app`
            if [ -d "$ENVIRONMENT_HOME/$app/work" ]; then
                check_config "$ENVIRONMENT_HOME/$app"
            fi
        done
        IFS=$oldifs
    fi
    exit $result
else
    echo "'$BUNDLE_NAME' is already running ($matches)."
    exit 1
fi

               status.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

check_if_running "-Dcatalina.base=$WORK_DIR"
exit $?

               stop.sh

#!/bin/sh

. "$BUNDLE_HOME/bundle/actions/common.sh"
. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

psexp="-Dcatalina.base=$WORK_DIR"
matches=`find_matching_processes "$psexp"`
if [ -n "$matches" ]; then
    echo "Stopping '$BUNDLE_NAME'..."
    $CATALINA_HOME/bin/shutdown.sh >"$WORK_DIR/$BUNDLE_NAME.out" 2>"$WORK_DIR/$BUNDLE_NAME.err"
    wait_for_stop "$psexp"
    result=$?
    if [ $result -eq 0 ]; then
        rm -f "$WORK_DIR/$BUNDLE_NAME.pid"
    fi
    exit $result
else
    echo "'$BUNDLE_NAME' is not running."
    exit 1
fi

               wardeploy.sh [12]

#!/bin/sh

. "$BUNDLE_HOME/bundle/actions/common.sh"
. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

war_path=$1
war_name=$2
webapps_dir="$CATALINA_BASE/webapps"
work_dir="$CATALINA_BASE/work/Catalina/localhost"
result=0
matches=`find_matching_processes "-Dcatalina.base=$WORK_DIR"`
if [ -n "$matches" ]; then
    bw "$DEPLOYMENT_HOME" stop
    result=$?
fi
if [ $result -eq 0 ]; then
    echo "Deploying webapp '$war_path' as '$war_name'..."
    war_dir="$webapps_dir/$war_name"
    war_work_dir="$work_dir/$war_name"
    if [ -d "$war_dir" ]; then
        rm -rf "$war_dir"
    fi
    if [ -d "$war_work_dir" ]; then
        rm -rf "$war_work_dir"
    fi
    mkdir "$war_dir"
    `cd "$war_dir" && jar xf "$war_path"`
    echo "OK - Deployed webapp '$war_path' as '$war_name'."
    if [ -n "$matches" ]; then
        bw "$DEPLOYMENT_HOME" start
    fi
else
    exit $result
fi

               warundeploy.sh

#!/bin/sh

. "$BUNDLE_HOME/bundle/actions/common.sh"
. "$BUNDLEWORKS_INCLUDE/bundle_funcs.sh"

war_name=$1
webapps_dir="$CATALINA_BASE/webapps"
work_dir="$CATALINA_BASE/work/Catalina/localhost"
result=0
matches=`find_matching_processes "-Dcatalina.base=$WORK_DIR"`
if [ -n "$matches" ]; then
	bw "$DEPLOYMENT_HOME" stop
	result=$?
fi
if [ $result -eq 0 ]; then
	echo "Undeploying webapp '$war_name'..."
	war_dir="$webapps_dir/$war_name"
	war_work_dir="$work_dir/$war_name"
	if [ -d "$war_dir" ]; then
		rm -rf "$war_dir"
	fi
	if [ -d "$war_work_dir" ]; then
		rm -rf "$war_work_dir"
	fi
	echo "OK - Undeployed webapp '$war_name'."
	if [ -n "$matches" ]; then
		bw "$DEPLOYMENT_HOME" start
	fi
else
	exit $result
fi

            info

         shared/ [13]

            bin/, common/, conf/, ...

/var/env/

   staging/ [14]

      env/

         info

      helloweb/

         bundle [15]

/opt/bundles/helloweb/1.0

         work/

            config/

               hello.properties [16]

message=Hello BundleWorks

            logs/

      tomcat/

         bundle

/opt/bundles/tomcat/5.5.25

         work/ [17]

            conf/

            logs/

            shared/

            temp/

            tomcat.err

            tomcat.out

            tomcat.pid

            webapps/

                webhello/ [18]

            work/

      uses/

         jdk [19]

/opt/bundles/jdk/1.5.0_13

   test/

      env/

         info

      helloweb/

         bundle [20]

/opt/bundles/helloweb/2.0rc1

         work/

            config/

               hello.properties [21]

message=Hello BundleWorks
color=blue

            logs/

      tomcat/

         bundle

/opt/bundles/tomcat/5.5.25

         work/

            conf/

            logs/

            shared/

            temp/

            tomcat.err

            tomcat.out

            tomcat.pid

            webapps/

                webhello/

            work/

      uses/

jdk

/opt/bundles/jdk/1.5.0_13

This is version 1.0 of the helloweb bundle. This bundle and the later 2.0rc1 version were built using the BundleWorks java-webapp bundler which builds deployable bundles from war files.
The actions directory inside the helloweb bundle contain the various scripts need to deploy this application. These scripts, or hooks, are called in response to various BundleWorks commands like deploy and undeploy. For example, the install.sh script is called when a bundle is deployed into an environment for the first time. The upgrade.sh script is called if deploying to an environment with an older version, while the rollback.sh script is called if deploying to an environment with a newer version. Finally, the uninstall.sh script is called in respsonse to the BundleWorks undeploy command.
The hello.properties file here is a template configuration file. It contains the token @{HELLO_MESSAGE}, which will be replaced with a value entered by the user during installation. This is done in the install.sh script using the built-in BundleWorks functions prompt_for_string and replace_vars.
The info file inside the helloweb bundle contains information about when the bundle was built. It also contains the following line which indicates where its configuration is kept:
```
Runtime-Config: config/*.properties
```
This line helps BundleWorks track changes to configuration within any helloweb deployment. BundleWorks stores a complete history of all configuration changes and provides various commands for accessing this history.
The helloweb.war file is a standard Java war file. This web application takes advantage of the configuration versioning feature of BundleWorks by storing its configuration outside the war file, but otherwise it is a standard Java web application. The next example shows how this war file is built and bundled using ant and the BundleWorks ant tasks.
This actions directory contains the scripts needed to deploy the 2.0 version of the helloweb application. These scripts need to handle the extra property added to the hello.properties file. They use the built-in BundleWork functions add_property and remove_property to handle this extra property during upgrade and rollback.
The hello.properties file inside the helloweb 2.0rc1 bundle contains an extra property from the 1.0 version. The bundle scripts handle this extra property correctly whether this bundle is being installed for the first time or being upgraded from a previous version.
This is version 1.5.0_13 of the Java Development Kit bundled using the BundleWorks jdk bundler. See the first example for details about this bundle.
This Tomcat bundle was built using the BundleWorks tomcat bundler and the 5.5.25 distribution of Tomcat from Apache.
The actions directory of the Tomcat 5.5.25 bundle contains the scripts needed to set up and manage an instance of Tomcat within an environment. BundleWorks automatically generates these scripts.
This common script is shared by a number of the Tomcat bundle scripts. It sets two environment variables: CATALINA_HOME and CATALINA_BASE, taking advantage of Tomcat's ability to have multiple "base" directories which share the same "home" directory. The CATALINA_HOME variable is set to $BUNDLE_HOME/shared to point to the Tomcat distribution inside the bundle. The CATALINA_BASE variable is set to $WORK_DIR, which is the work directory of a Tomcat deployment.
The wardeploy script and the warundeploy script define Tomcat's response to the messages broadcast by web applications during deployment. In this case, Tomcat responds by updating its webapp and work directories as needed.
This shared directory contains the entire 5.5.25 distribution of Tomcat from Apache. No modifications to the distribution are necessary to use Tomcat with BundleWorks.
The staging environment was created using the BundleWorks envcreate command. The helloweb, jdk, and tomcat bundles were deployed to this environment using the BundleWorks deploy command.
This bundle reference inside the helloweb deployment within the 'staging' environment points to version 1.0 of the application (/opt/bundles/helloweb/1.0). When the application is upgraded, this reference is changed to point to the new bundle.
This hello.properties is the result of deploying the helloweb bundle to the staging environment. This file contains the single property needed by the 1.0 version of helloweb.
This work directory inside the tomcat deployment within the staging environment defines a separate instance of Tomcat. This directory is created and populated when the tomcat bundle is installed into an environment. It contains all of the runtime files needed by Tomcat as well as files created by BundleWorks to capture the standard out, standard error, and process id of the launched Tomcat.
This Tomcat webapp directory contains the exploded war file from the helloweb 1.0 bundle. In the 'test' environment, the webapp directory contains the exploded war file from the helloweb 2.0rc1 bundle.
This jdk file is a reference to the jdk 1.5.0_13 bundle inside /opt/bundles. It determines which version of Java is used by this environment.
This bundle reference inside the helloweb deployment within the 'test' environment points to version 2.0rc1 of the application (/opt/bundles/helloweb/2.0rc1).
This hello.properties is the result of upgrading the helloweb bundle in the test environment from 1.0 to 2.0rc1. This file contains the extra property needed by the 2.0 version of helloweb.