Windows service package deployment example

From ControlTier

Requires Version: 3.4.4

Note: this document describes how to run the example on Windows. for Unix instructions, see Service Package Deployment Example.

This example shows the basics of using an object of the Service type to manage the deploy life cycle of a long running application Service. The Service type defines several commands useful for managing the package installation, and startup shutdown cycle of a software service.

This example shows you how to do the following things:

1. upload a Zip file containing the Apache Tomcat distribution to the repository
2. use a finish script to customize the Zip post-installation step
3. use the Deploy life cycle command
4. use the Start, Stop, and Status life cycle commands
5. customize the implementation of these commands using your shell or batch scripts to perform the logic
6. use the project.xml resource model format to define a Service resource

This example provides a working set of scripts to implement the logic to manage a Tomcat application deployment. Both the Tomcat software itself along with a simple webapp application will be deployed using the Service.

The Deploy life cycle command provides a consistent interface to managing the normal steps of software deployment to a Service. The Service type defines it as a workflow command that calls Stop, Packages-Install, Configure, Start.

Services can be configured to deploy one or more software packages, coordinated by the Packages-Install command. Packages-Install iterates over each package, invoking the Package type's Install command on each package that has been associated as a resource to a Service. The Package type's Install command provides a consistent interface to manage the normal steps of a package deployment.

The life cycle commands Start and Stop work in a similar way. Each one runs another command designed to "assert" that the run-state of the process is as expected. For example, the Start command runs assertServiceIsUp. This "assert" command merely does one thing: it checks that the service is in the state specified (running or not running), and if it doesn't meet that expectation, it fails. If it succeeds, then the Start/Stop command knows it doesn't have to do anything else, and the entire command succeeds. However, if the "assert" command fails, then the Start/Stop command has to change the state of the service. It does this by subsequently invoking the startService or stopService command. These commands are meant to perform whatever action is necessary to start or stop the underlying service. If this command succeeds, then the Start/Stop command has succeeded, otherwise it has failed.

This mechanism separates the logic of managing the run-state of a service into discrete tasks that have clear semantics, allowing this abstract pattern to apply to the wide range of software services that need to be managed.

This example will use a set of simple shell scripts to plug in to each of these discrete tasks, allowing us to demonstrate the behavior of the life cycle commands while only simulating an actual running service. You will see that the implementation of each of these tasks is simple and easy to customize for your own service management needs.

• For more information, see the Service Concepts and Package Concepts documents.

Contents 1 Dependencies 2 Building the Example 3 Running the Example 3.1 Run Deploy 3.1.1 What the Example Shows 4 How it Works 4.1 The Package definitions 4.2 The Service definition 4.2.1 Settings 4.2.2 Service 4.3 Command dispatching 4.4 The Output 5 Stopping the Example 6 Related Topics

Dependencies

This demo depends on these dependencies.

• ControlTier — 3.4.4
  • Meet the prerequisites and install ControlTier according to the Installing ControlTier instructions.
• Tomcat — 5.5.26
  • Download Zip: http://tomcat.apache.org/download-55.cgi
  • Copy the downloaded Zip to %CTIER_ROOT%\examples\service-package-deployment\pkgs\apache-tomcat-5.5.26.zip

Note: A WAR file is included in the %CTIER_ROOT%\examples\service-package-deployment\pkgs directory so there is no external dependency for that.

Building the Example

Follow the instructions in this section to setup the example code into your environment.

Note: Don't worry about what these commands do, as they just bootstrap the example code to work in your environment and to pre-load the resource model for you. (For complete detail about how to use the Examples see Using the Examples):

Execute these bootstrap steps:

1. cd %CTIER_ROOT%\examples\service-package-deployment

   • Navigate to the examples\service-package-deployment directory under your %CTIER_ROOT% directory.
2. Edit the file: templates\defaults.xml (optional)
   • Update the file with your node name if it is not the default of "localhost".

3. ctl -p demo -m ProjectBuilder -c Register -- -xml projectbuilder.xml -install

   • This loads a ProjectBuilder object definition into the ControlTier Server.

4. ctl -p demo -m zip -c upload -- -filename pkgs\apache-tomcat-5.5.26.zip -xml templates\apache-tomcat-5.5.26.zip.xml

   • Upload the "apache-tomcat-5.5.26.zip" file to the package repository. Remember you had to obtain this from the Apache Tomcat project download page mentioned in the #Dependencies section above!

5. ctl -p demo -t ProjectBuilder -r service-package-deployment -c Build

   • Builds a working example based on template files and your working environment. Later see Further Customization

The result of these bootstrap steps results in a Service resource named "simpleTomcat" that you can use to control the deploy life cycle of a Tomcat instance via CTL commands.

You are now ready to run the examples.

Running the Example

You can run any of the Service commands like so: ctl -p demo -t Service -r simpleTomcat -c <command-name>

If you run the command without the "-c <command-name>" parameter you will see a listing of commands.

Run Deploy

The Deploy command executes the entire deployment life cycle for a Service stopping it, installing configured package resources, configuring the service and then running startup.

ctl -p demo -t Service -r simpleTomcat -c Deploy

Once the command completes you should be able to access the deployed Tomcat and "simple" application. Visit the link like so (eg, http://localhost:18080/simple/):

You should see the current date and time displayed in the browser page.

What the Example Shows

You saw a lot of output from the Deploy but what did it do? The nitty gritty is explained in the #How it Works and #The Output sections but here's what occurred at a high level:

1. The resource model describing the simpleTomcat Service was synchronized to the CTL framework. This resource model drives all the automation commands.
   • This resource model described where the Tomcat instance runs, what packages it uses, what listening port it binds to, as well as, the scripts to use to drive various steps of the end-to-end process.
2. Deploy calls the Stop command to shutdown the running Tomcat instance in case it had already been running. The shutdown procedure used scripts that are configured for this step.
   • One of these scripts used information from the resource model to lookup the Tomcat connector port to see if it was listening on that socket.
3. Deploy's next step handled the package installation workflow. This step downloads, extracts and installs two packaged software artifacts: a War and Zip, also part of the resource model.
   • During the installation phase of the Zip, a "finish" script was called to customize the Tomcat server.xml file so it will run on non-standard ports.
4. The final step called by Deploy was to run the Start command which handles the Tomcat startup.
   • This used two scripts named in the resource model to check if the Tomcat was already up and if not to call the Tomcat startup.bat script.

How it Works

The diagram below describes the resource model for this example. The model describes a Service deployed to one Node. The Service is configured to install two Packages one with a finish script. The service uses several script settings to control stop/start actions. Lastly, a setting is used to describe a network port value.

From Workbench you can see the simpleTomcat Service's resource model in the "Service Manager" page:

You can see two Packages defined along with one Node, the host where simpleTomcat is deployed.

The simpleTomcat Service resource model is defined in a project XML file generated into the %CTIER_ROOT%\examples\service-package-deployment. directory. The following sections walk through the XML definition files used to define the simpleTomcat resource model. Each type of resource has an associated set of metadata. First the metadata describing the packages are reviewed and then the metadata for the Service.

The Package definitions

Two packages were defined for this example: apache-tomcat.5.5.26.zip and simple-123.war.

Package metadata is defined using the package tag. This tag uses a set of attributes to define the various bits of information describing each package.

Below you can see metadata about the apache-tomcat.5.5.26.zip file includes information like build time, install root directory, version among other properties. This metadata defines a package named "apache-tomcat.5.5.26.zip" that is of type, "zip". The normal naming convention for a package is to use its filename as the resource name. The type name (in this case "zip") specifies which Package subtype to use. Package subtypes can provide their own install life cycle implementations. For example, the "zip" type defines an extract command that understands how to extract Zip archives.

Along with the metadata describing the apache-tomcat.5.5.26.zip[zip] package, there is also a PackageFinishScript setting used to define a "finish" script for it. This script will be called by the finish command at the end of the apache-tomcat.5.5.26.zip installation to customize a configuration file. The resources tag is used to associate the PackageFinishScript as a package resource.

File listing: %CTIER_ROOT%\examples\service-package-deployment\apache-tomcat-5.5.26.zip.xml

 <setting type="PackageFinishScript" name="apache-tomcat-5.5.26.zip" 
           description="The script used during finish" 
           settingValue="${env.CTIER_ROOT}/examples/service-package-deployment/finish.xml" settingType="script"/>
  <package 
      arch="noarch"
      base="apache-tomcat-5.5.26" 
      buildtime="2008061570109" 
      description="The Tomcat application server." 
      filename="apache-tomcat-5.5.26.zip" 
      filetype="zip" 
      installroot="${env.CTIER_ROOT}/examples/service-package-deployment/apache-tomcat-5.5.26"
      installrank="" 
      name="apache-tomcat-5.5.26.zip" 
      release=""
      releasetag=""
      repoUrl="/zip/zips/apache-tomcat-5.5.26.zip" 
      restart="false"
      type="zip"
      vendor=""
      version="5.5.26"      
     >
    <resources>
      <resource type="PackageFinishScript" name="apache-tomcat-5.5.26.zip"/>
    </resources>
  </package>

The next package defined here describes the WAR file that will be deployed into the Tomcat container. This metadata defines a package named "simple-123.war" that is of type, "war".

No extra finish step is needed for the WAR deployment so no PackageFinishScript setting is defined. The metadata describing the "simple-123.war" war object is shown in the file listing below:

File listing: %CTIER_ROOT%\examples\service-package-deployment\simple-123.war.xml

<package 
    arch="noarch"
    base="simple" 
    buildtime="123" 
    description="A simple webapp"
    filename="simple-123.war" 
    filetype="war" 
    installroot="${env.CTIER_ROOT}/examples/service-package-deployment/apache-tomcat-5.5.26/webapps"
    installrank="2" 
    name="simple-123.war" 
    release=""
    releasetag=""
    repoUrl="/war/wars/simple-123.war" 
    restart="false"
    type="war"
    vendor=""
    version="123"      
    />

Review the two package XML definitions again and notice the installrank property. The apache-tomcat-5.5.26.zip had installrank=1 while simple-123.war definition has installrank=2. The installrank property provides a relative ordering to package installation. The install rank values are sorted in ascending order, ensuring packages with lower installrank will before those with higher values.

Both the package metadata and archive files were loaded into your project by the steps in the #Building the Example section. Had you uploaded the packages your self you would have run these commands:

ctl -p demo -m zip -c upload -- -filename pkgs/apache-tomcat-5.5.26.zip -xml templates/apache-tomcat-5.5.26.zip.xml
ctl -p demo -m war -c upload -- -filename pkgs/simple-123.war -xml simple-123.war.xml

The upload command uploads the specified file to the repository and registers it. The upload command is shown with two arguments: -filename and -xml. The filename references the archive file you want to upload while the -xml option specifies the file containing the package metadata. You'll also notice that the different arguments to the -m option (war vs zip). The -m option specifies the Package type you want to use to upload the package. The "zip" type is used to upload Zip files while the "war" type is used to upload War files.

The ProjectBuilder repoFind command can be used to query the package repository at any time. Below is an example that shows how to lookup the two files that were uploaded and registered:

ctl -p demo -t ProjectBuilder -r service-package-deployment -c repoFind --^
 -packagename "(?:simple-.*|apache-tomcat.*)" -packagetype Package

The output shows both packages in the repository.

Querying model for matching package objects ...
|
|--(zip) apache-tomcat-5.5.26.zip
|
|--(war) simple-123.war

The -packagename option used a regex argument to specify a filter pattern to limit the search to just packages that have names matching that pattern. The -packagetype option specifies to look for packages of any subtype of "Package".

The Service definition

This section describes the definition of the Service resource. One Service was defined for this example: "simpleTomcat" of type Service. The Service definition is broken into two parts: one for script settings and the other for the Service itself. The section will walk through the XML definition found in the file listing contained in %CTIER_ROOT%\examples\service-package-deployment\default-object-win.xml.

Settings

The Service type defines a set of standard workflows to drive the startup and shutdown processes. The resource model provides a set of setting types that let you configure the commands called by these workflows to call your scripts. The table below shows each command has a particular setting type where you declare the path to your script you want called by the command. Additionally, the ServiceSpawn setting value of true indicates that the script called by startService should spawn in a separate process.

Setting	Command	Value
ServiceStartScript	startService	start.bat
ServiceStopScript	stopService	stop.bat
ServiceIsUpScript	assertServiceIsUP	isup.xml
ServiceIsDownScript	assertServiceIsDown	isdown.xml
ServiceSpawn	startService	true

Below is the XML used to define these settings for the simpleTomcat Service resource model. The setting tag is used to define the each setting type and corresponding script. You can see that each setting specifies the script to call using the settingValue tag, and the ServiceSpawn setting specifies "true" as the settingValue.

<setting type="ServiceStartScript" name="simpleTomcat" 
   description="The script used by startService" 
   settingValue="${env.CTIER_ROOT}/examples/service-package-deployment/start.bat" settingType="shell"/>
<setting type="ServiceStopScript" name="simpleTomcat" 
   description="The script used by stopService" 
   settingValue="${env.CTIER_ROOT}/examples/service-package-deployment/stop.bat" settingType="shell"/>
<setting type="ServiceIsUpScript" name="simpleTomcat" 
   description="The script used by assertServicesIsUp" 
   settingValue="${env.CTIER_ROOT}/examples/service-package-deployment/isup.xml" settingType="ant"/>
<setting type="ServiceIsDownScript" name="simpleTomcat" 
   description="The script used by assertServicesIsDown" 
   settingValue="${env.CTIER_ROOT}/examples/service-package-deployment/isdown.xml" settingType="ant"/>
<setting type="ServiceSpawn" name="simpleTomcat" 
   description="Whether to spawn separate process for the start script"
   settingValue="true" />

Settings can be used to describe any kind of information that is essentially a named key/value pair. Here is a setting that captures the port number Tomcat uses to accept client connections.

<setting type="Port" name="simpleTomcat-connector" 
   description="The connector port used by Tomcat" 
   settingValue="18080" settingType="TCP"/>

Setting information like this is accessible to all the commands for the Service. In this case, the connector port value can be referenced from inside the Service commands as: ${setting.Port.simpleTomcat-connector.settingValue}

Service

This section describes how to put the Service resource model all together. The resource model describing the example Service entails referencing the setting information just described as well as referencing the packages that should be installed during deployment. For the simpleTomcat service that means referencing the five settings and the two packages.

A service is defined using a deployment tag. The deployment tag uses a set of attributes to name and specify the type of resource (eg name="simpleTomcat" type="Service"). The installRoot and basedir attributes declare the location of the Tomcat installation (c.f., CATALINA_HOME/CATALINA_BASE).

The settings and packages are referenced as resource elements inside the resources element. The node where this Service is to be deployed is referenced in the referrers element.

Here's the XML that ties the information together:

<deployment 
     type="Service"
     name="simpleTomcat" 
     description="The Tomcat deployment." 
     installRoot="${env.CTIER_ROOT}/examples/service-package-deployment/apache-tomcat-5.5.26" 
     basedir="${env.CTIER_ROOT}/examples/service-package-deployment/apache-tomcat-5.5.26">

   <resources>
	   <!-- 
	  **
	  ** References the scripts to be run by the Service lifecycle commands 
	  **
	   -->
     <resource name="simpleTomcat" type="ServiceStopScript" />
     <resource name="simpleTomcat" type="ServiceStartScript" />
     <resource name="simpleTomcat" type="ServiceIsDownScript" />
     <resource name="simpleTomcat" type="ServiceIsUpScript" />
     <resource name="simpleTomcat" type="ServiceSpawn" />
     <!-- 
    **
    ** References the Tomcat connector port setting
    **
     -->
     <resource name="simpleTomcat-connector" type="Port" />
     <!-- 
    **
    ** References the zip and war Packages
    **
     -->
     <resource name="apache-tomcat-5.5.26.zip" type="zip" />
     <resource name="simple-123.war" type="war" />

   </resources>

   <!--
 **
 ** Define a parent dependency to the node where you are running this example. 
 **
   -->
   <referrers replace="false">
     <!--
   ** Change this line to one that matches your node name:
     -->
     <resource type="Node" name="localhost"/>
   </referrers>

 </deployment>

This concludes the explanation of the example's resource model. The next section describes the Service commands that support the deploy and startup/shutdown cycles.

Command dispatching

The Service type defines a set of standard workflow commands that support the typical steps of deployment and startup/shutdown. The idea is to define a resource model that drives these commands, letting you configure the model to tie in calls to your scripts or expose environment information (like the Tomcat connector port) to the commands.

The startup and shutdown processes are managed via two Service workflow commands: Start and Stop. Both workflows share a common design. Each check for a condition and if the condition is not met, an action is performed. Let's look at each of these workflows.

Service provides a program skeleton supporting a generic start up procedure that first checks if the service is up and if not, to then run a command to start the service.

You can see in the diagram that Start calls assertServiceIsUp first. If it fails because the service is not running, then startService is executed.

Service also provides a program skeleton supporting a generic shutdown procedure that first checks if the service is down and if not, to then run a command to stop the service.

You can see in the diagram that Stop calls assertServiceIsDown first. If it fails because the service is running, then stopService is executed.

Underlying these Service commands are the scripts that were configured via the setting definitions discussed above. All the service life cycle commands that call scripts assume a basic convention. If the script exits with a non-zero exit code, the command will fail otherwise it's interpreted as successful.

The scripts called by our simpleTomcat Service are trivial but are representative of how you can incorporate your own procedures via scripts attached to Service commands. The four hook commands can be configured to call shellscript, Windows batch or Ant build files. Let's look at each of the four scripts used in this example.

The "isdown.xml" is an Ant build file called by assertServiceIsDown. This command checks to see if the Service is down. In this case, the isdown.xml checks if Tomcat is listening on its connector socket. If it is, a fail is thrown. Notice the ${setting.Port.simpleTomcat-connector.settingValue} setting value is used to lookup the port to check. It's advantageous to expose resource model information like the Tomcat port value to scripts since it makes them inherently more reusable across environments.

File listing: %CTIER_ROOT%\examples\service-package-deployment\isdown.xml

<project default="execute">
  <!--
  **
  ** Check the listening port to see if Tomcat is running
  **
  -->
  <target name="execute">
    <!--
    ** Fail if it IS listening
    -->
    <fail message="Service is UP (Listening on port: ${setting.Port.simpleTomcat-connector.settingValue})">
      <condition>
	  <!--
	  **
	  ** This hook command has access to the context data of the
	  ** calling object. The Setting referenced via this property: 
	  **   setting.Port.simpleTomcat-connector.settingValue
	  ** contains the port value
	  -->
	<socket port="${setting.Port.simpleTomcat-connector.settingValue}" server="localhost"/>
      </condition>
    </fail>
    <echo>DOWN</echo>
  </target>

</project>

The "isup.xml" file is called by assertServiceIsUp. This command checks if the service is running. In this case, if the Tomcat server is not listening on the connector port, a fail is thrown.

File listing: %CTIER_ROOT%\examples\service-package-deployment\isup.xml

<project name="isup.xml" default="execute">
  <!--
  **
  ** Check the listening port to see if Tomcat is running
  **
  -->
  <target name="execute">
    <!--
    ** Fail if it is not listening
    -->
    <fail message="Service is DOWN">
      <condition>
	<not>
	  <!--
	  **
	  ** This hook command has access to the context data of the
	  ** calling object. The Setting referenced via this property: 
	  **   setting.Port.simpleTomcat-connector.value
	  ** contains the port value
	  -->
	  <socket port="${setting.Port.simpleTomcat-connector.value}" server="localhost"/>
	</not>
      </condition>
    </fail>
    <!--
    ** The service is running so print an informative message
    -->
    <echo>UP (Listening on port: ${setting.Port.simpleTomcat-connector.value})</echo>
  </target>
</project>

The "start.bat" script is called by the startService command. The "start.bat" file is a batch script and calls the Tomcat startup.bat script included in the Tomcat distribution.

File listing: %CTIER_ROOT%\examples\service-package-deployment\start.bat

@echo off
setlocal

::
:: set the necessary environment variables
::
set CATALINA_HOME=%CTIER_ROOT%\examples\service-package-deployment\apache-tomcat-5.5.26
set CATALINA_BASE=%CATALINA_HOME%

::
:: call the tomcat startup script
::
call %CATALINA_HOME%\bin\startup.bat

File listing: %CTIER_ROOT%\examples\service-package-deployment\stop.bat

@echo off
setlocal

::
:: set the necessary environment variables
::
set CATALINA_HOME=%CTIER_ROOT%\examples\service-package-deployment\apache-tomcat-5.5.26
set CATALINA_BASE=%CATALINA_HOME%

::
:: call the tomcat startup script
::
call %CATALINA_HOME%\bin\shutdown.bat

These four scripts cover the Tomcat startup and shutdown procedures and will be called via the Start and Stop workflow commands.

Besides managing the runtime state of the deployed Tomcat instance, there is one more requirement for this example. We need to customize the Tomcat installation to not use its default set of ports. This is accomplished by hooking a script to the Package finish command. You may recall that a PackageFinishScript setting declared for the apache-tomcat-5.5.26.zip Package referenced an Ant build file called "finish.xml".

There are actually several steps carried out in the finish.xml:

1. Set the execute bit on the Tomcat scripts in %CATALINA_HOME%\bin. (This step is performed for the benefit of unix systems).
2. Create a backup of the %CATALINA_BASE%\conf\server.xml
3. Re-write the %CATALINA_BASE%\conf\server.xml to replace the standard ports with ones that won't conflict with our environment.

These steps are implemented in the "finish.xml" Ant build file. The finish command provides access to the resource model for the "finish.xml" as a set of Ant properties. Notice in the file below that the resource.package-install-root is used to locate the installation root directory. Using resource model data from inside commands makes them data driven and hence more flexible and reusable.

File listing: %CTIER_ROOT%\examples\service-package-deployment\finish.xml

<project name="finish.xml" default="execute">
  <!--
      ** The "finish" command can access metadata about the package it is processing.
	  ** One piece of information used here is "resource.package-install-root". This
	  ** is the directory where the package archive is extracted.
	  ** For this example it is also synonymous with the Tomcat install root (ie, CATALINA_HOME)
  -->

  <!--
      **
      ** Customize the Tomcat install
      **
  -->
  <target name="execute">
    <echo level="info">Finishing tomcat installation ...</echo>

    <tstamp/>
    <!-- set start/stop scripts execute bit-->
    <chmod dir="${resource.package-install-root}/bin" perm="ugo+rx" 
	   includes="**/*.sh"/>
    <!-- backup the current config file-->
    <copy file="${resource.package-install-root}/conf/server.xml" 
	  tofile="${resource.package-install-root}/conf/server.xml.${DSTAMP}${TSTAMP}"/>
    <!-- global replace the stock port values -->
    <replace dir="${resource.package-install-root}"
	     token="8005" 
	     value="18105">
      <include name="conf/server.xml"/>
    </replace>
    <replace dir="${resource.package-install-root}"
	     token="8009" 
	     value="18009">
      <include name="conf/server.xml"/>
    </replace>
    <replace dir="${resource.package-install-root}"
	     token="8080" 
	     value="18080">
      <include name="conf/server.xml"/>
    </replace>
    <echo level="info">Customized ${resource.package-install-root}/conf/server.xml</echo>
  </target>
</project>

The Output

The Deploy command is a workflow that calls a sequence of four commands: Stop, Packages-Install, Configure, Start.

You can preview the actions of the Deploy workflow from Workbench. Navigate to the simpleTomcat[Service] object in the "Service Manager" and press the "Commands" tab. Locate the "Deploy" workflow and press the yellow button to right.

You will see the Process Flow view display workflow structure across the commands that are dispatched by Deploy.

Since there's quite a lot of output messages from Deploy we'll call each command in turn and examine output from each.

First let's look at the Stop command.

ctl -p demo -t Service -r simpleTomcat -c Stop

Stop calls assertServiceIsDown command which is configured to call our "isdown.xml" Ant file.

begin workflow command (1/1) -> "assertServiceIsDown " ...
Executing ant file: /Users/alexh/ctier/examples/service-package-deployment/isdown.xml
DOWN
end workflow command (1/1) -> "assertServiceIsDown "

The isdown.xml detected the Tomcat instance was already down so Stop just exits. Had it been running, Stop would have called stopService which is configured to run the "stop.bat" script.

Next let's look at the Packages-Install command.

ctl -p demo -t Service -r simpleTomcat -c Packages-Install

This command is a workflow that iterates over each of the assigned Package resources and for each calls its Install command. The Install command is a Package type workflow that kicks off each step in the package installation life cycle.

It's easiest to break up this output and discuss each step.

The first line shows there are two Packages to install for the simpleTomcat Service (ie, simple-123.war[war], apache-tomcat-5.5.26.zip[zip]):

Start: "Install the configured package dependencies for the deployment." Beginning installation for packages:   simple-123.war[war],  apache-tomcat-5.5.26.zip[zip] ...
Dispatching command 'assertPackageIsVerified' to objects: apache-tomcat-5.5.26.zip[zip], simple-123.war[war] ...
starting: apache-tomcat-5.5.26.zip[zip]->assertPackageIsVerified ...
starting: simple-123.war[war]->assertPackageIsVerified ...

The first step in the package installation cycle is assertPackageIsVerified which wraps each of the package installation cycles to ensure a verified result. It begins with apache-tomcat-5.5.26.zip because it had installrank=1:

Getting: http://localhost:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/zip-head.jar
To: C:\ctier\ctl\var\tmp\downloads\demo\zip-head.jar
Not modified - so not downloaded
zip up to date
Attempting to get Package-head.jar ...
Getting: http://localhost:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/Package-head.jar
To: C:\ctier\ctl\var\tmp\downloads\demo\Package-head.jar
Not modified - so not downloaded
Package up to date
Packages-Install invoking: apache-tomcat-5.5.26.zip[zip]->Install -installroot 
    C:\ctier/examples/service-package-deployment

The Package Install command does a couple things:

• downloads the needed command module jar files that contains the Zip specific install cycle commands (eg zip-head.jar).
• checks if the package was previously installed and then calls installPackage which does all the work of getting, extracting and finishing the installation (ie, steps 1-5).

Start: "Install object and run the package installation cycle." commands: assertPackageIsInstalled
begin workflow command (1/1) -> "assertPackageIsInstalled -installroot C:\ctier/examples/service-package-deployment" ...
Executing ant file: C:/ctier/ctl/projects/demo/modules/Package/bin/is-installed.xml
Running handler command: installPackage
begin workflow command (1/5) -> "installDependencies -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip" ...
Dispatching command 'Install' to objects:  ...
end workflow command (1/5) -> "installDependencies -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip"
begin workflow command (2/5) -> "prepare -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip" ...
end workflow command (2/5) -> "prepare -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip"
begin workflow command (3/5) -> "get -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip" ...
Getting: http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip
To: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26.zip
end workflow command (3/5) -> "get -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip"
begin workflow command (4/5) -> "extract -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip" ...
Expanding: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26.zip into C:\ctier\examples\service-package-deployment
end workflow command (4/5) -> "extract -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip"

Here is our "finish.xml" called by the finish command. You can see the messages about the server.xml file being backed up and customized. Recall that the finish.xml used the property resource.package-install-root to locate the install root directory.

begin workflow command (5/5) -> "finish -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip" ...
Executing ant build file
Finishing tomcat installation ...
Copying 1 file to C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\conf
Customized C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/conf/server.xml
Deleting: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26.zip
end workflow command (5/5) -> "finish -filename apache-tomcat-5.5.26.zip -installroot C:\ctier/examples/service-package-deployment 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip"
end workflow command (1/1) -> "assertPackageIsInstalled -installroot C:\ctier/examples/service-package-deployment"
[command.timer.demo.Package.Install: 32.891 sec]
Workflow completed. execution time: 32.891 sec
Executing script: C:/ctier/ctl/projects/demo/modules/Package/bin/is-verified.xml ...
Package is VERIFIED

The apache-tomcat-5.5.26 installation completed and was verified. Next, the simple-123.war package goes through the same sequence. It had installrank=2 and thus follows after apache-tomcat-5.5.26.zip.

Getting: http://localhost:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/war-head.jar
To: C:\ctier\ctl\var\tmp\downloads\demo\war-head.jar
Not modified - so not downloaded
war up to date
Attempting to get Package-head.jar ...
Getting: http://localhost:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/Package-head.jar
To: C:\ctier\ctl\var\tmp\downloads\demo\Package-head.jar
Not modified - so not downloaded
Package up to date
Packages-Install invoking: simple-123.war[war]->Install -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps
Start: "Install object and run the package installation cycle." commands: assertPackageIsInstalled
begin workflow command (1/1) -> "assertPackageIsInstalled -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps" ...
Executing ant file: C:/ctier/ctl/projects/demo/modules/Package/bin/is-installed.xml
Running handler command: installPackage
begin workflow command (1/5) -> "installDependencies -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war" ...
Dispatching command 'Install' to objects:  ...
end workflow command (1/5) -> "installDependencies -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war"
begin workflow command (2/5) -> "prepare -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war" ...
end workflow command (2/5) -> "prepare -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war"
begin workflow command (3/5) -> "get -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war" ...
Getting: http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war
To: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\webapps\simple-123.war
end workflow command (3/5) -> "get -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war"

begin workflow command (4/5) -> "extract -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war" ...
Created dir: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\webapps\simple
Expanding: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\webapps\simple-123.war into C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\webapps\simple
end workflow command (4/5) -> "extract -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war"
begin workflow command (5/5) -> "finish -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war" ...
Deleting: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\webapps\simple-123.war
end workflow command (5/5) -> "finish -filename simple-123.war -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps 
    -url http://localhost:8080/jackrabbit/repository/controltier/projects/pkgs/demo/war/wars/simple-123.war"
end workflow command (1/1) -> "assertPackageIsInstalled -installroot C:\ctier/examples/service-package-deployment/apache-tomcat-5.5.26/webapps"
[command.timer.demo.Package.Install: 32.891 sec]
Workflow completed. execution time: 32.891 sec
Executing script: C:/ctier/ctl/projects/demo/modules/Package/bin/is-verified.xml ...
Package is VERIFIED

The last line shows both packages were installed successfully.

Completed: Installed packages:   simple-123.war[war],  apache-tomcat-5.5.26.zip[zip]

After the Packages-Install command, the next command in the Deploy sequence is Configure

ctl -p demo -t Service -r simpleTomcat -c Configure

The Configure workflow calls Docs-Generate which generates any registered configuration documents from templates. Our simpleTomcat example does not do this so it's just an empty step here. See Generating_Configuration_Files for information about using Docs-Generate.

begin workflow command (1/1) -> "Docs-Generate " ...
end workflow command (1/1) -> "Docs-Generate "

The last step in the Deploy workflow is the Start command.

ctl -p demo -t Service -r simpleTomcat -c Start

The Start workflow calls assertServiceIsUp which is configured to call our "isup.xml" Ant file. The "isup.xml" detects the Tomcat instance is down so Start calls the startService command which is in turn, configured to execute our "start.bat" script.

begin workflow command (1/1) -> "assertServiceIsUp " ...
Executing ant file: C:\ctier/examples/service-package-deployment/isup.xml
Running handler command: startService
Executing windows batch file: C:\ctier/examples/service-package-deployment/start.bat
end workflow command (1/1) -> "assertServiceIsUp "

The "start.bat" script calls Tomcat %CATALINA_HOME%\bin\startup.bat. Since we have set the ServiceSpawn setting to the value of "true", the start.bat script is executed in a separate process.

You should see a new command window open with the output from startup.bat.

You can verify the Tomcat runtime state is UP via the Status command:

$ ctl -p demo -t Service -r simpleTomcat -c Status
begin workflow command (1/1) -> "assertServiceIsUp " ...
Executing ant file: C:\ctier/examples/service-package-deployment/isup.xml
UP (Listening on port: 18080)
end workflow command (1/1) -> "assertServiceIsUp "

Stopping the Example

You can run the "Stop" command for the Service, to stop the running tomcat server:

Execute:

ctl -p demo -t Service -r simpleTomcat -c Stop

The "isdown.xml" script will check if the service is running. If so, then the stopService command will execute. This will run our stop.bat script, which finally invokes the Tomcat "shutdown.bat" script and the server will stop.

output:

begin workflow command (1/1) -> "assertServiceIsDown " ...
Executing ant file: C:\ctier/examples/service-package-deployment/isdown.xml
Running handler command: stopService
Executing windows batch file: C:\ctier/examples/service-package-deployment/stop.bat
Using CATALINA_BASE:   C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26
Using CATALINA_HOME:   C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26
Using CATALINA_TMPDIR: C:\ctier\examples\service-package-deployment\apache-tomcat-5.5.26\temp
Using JRE_HOME:        C:\ctier\pkgs\jdk1.5.0_17
end workflow command (1/1) -> "assertServiceIsDown "

Related Topics

• Mock Unix Service Example explains the very basic essentials to manage the runtime state of a long running application service.
• Prepare Finish Scripts describes how to hook in your own scripts to the Package prepare and finish commands.
• Generating Configuration Files explains several methods to generate configuration files for a Service.
• See more about the Service type in the Core Type Guide

v • d • e Modeler Guide Introduction Modeler Guide · Concepts · Modeler Getting started · Model-driven approach · CTL architecture · Model-driven command dispatching · File share Resource modeling Resource Model · Graphical resource editor · Graphical type editor · ProjectBuilder · Core Type Guide  · Type modeling · Attributes · Constraints Module development Module Development Guide · Modules · First type module · Workflow command · Command options Examples Creating packages · Mock Unix Service Example  · Mock Site Example  · Service Package Deployment Example  · Windows service  · Windows site  · Windows deployment · Builder Simple Example  · Continuous Deployment Example with Tomcat · Dukes Bank J2EE examples