Creating packages

From ControlTier

This document describes how to create and store packages in the ControlTier repository.

ControlTier includes a set of package types, one of which can be used to manage the creation and installation life cycle for your build artifacts:

• bin: A self extracting shar package
• ear: An EAR package (J2EE)
• jar: An JAR package (J2SE)
• pkg: A SVR4 package (System V Release 4)
• rpm: An RPM package (Redhat)
• tgz: A GZip compressed TAR package
• war: A WAR package (J2EE)
• zip: A Zip package
• file: A single file package

Each of these types has steps to create, upload and install the packaged files of its archive format. You can override the behavior of any step through subtyping. If you have an archive format or set of steps that is not covered by an existing type, then subtype the closest Package type and add or implement the needed steps.

The table below gives a brief description for each of the attributes of a package type. The ones with an asterisk are required during the deployment cycle.

attribute	description
arch	Hardware architecture.
base*	Package base.
buildtime	Build identifier
description	Description of the package.
filename*	Name of the file.
filetype	Archive format.
installroot*	Directory where archive will be extracted.
installrank*	Relative ordering.
name*	Name of the package. Usually, the same as filename
release	Version release.
releasetag	Release identifier.
repoUrl*	URL to the file in the repository.
restart	Signifies if the service should restart after installation.
type	Name of Package type or subtype
vendor	Organization that created the package
version*	Package version

The remainder of this page shows how to use one of the standard package types to create and upload artifacts to the repository. You can create packages of other types by following the same procedures.

Contents 1 Upload an existing file as a package 1.1 Define the package metadata file 1.2 Upload the file to the repository 2 Creating a package from a directory 2.1 Prepare reference directory 2.2 Archive the files and upload the archive to the repository 2.3 Uploading without an XML metadata file 3 Install Package 4 Related Topics

Upload an existing file as a package

In this example you will see how to upload the zip distribution of Apache Tomcat 5.5 downloaded from here: http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.26/bin/. Download the apache-tomcat-5.5.26.zip file to the directory, $CTIER_ROOT/pkgs.

Storing an existing file in the repository is done in two steps:

Define the package metadata file

Metadata is used to describe the archive file in the repository. This metadata is needed later during the deployment cycle.

Create a metadata file describing the package using the attributes described earlier in the table above. The package XML tag has attributes for each of the ones described in the table. This file will be used during the upload process to register the package.

Use your favorite text editor and create an XML file like the one below and save it to the same directory where the archive exists (e.g., $CTIER_ROOT/pkgs).

File listing: apache-tomcat-5.5.26.zip.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE project PUBLIC "-//ControlTier Software Inc.//DTD Project Document 1.0//EN" 
    "project.dtd">
<project>
  <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}/demo/apache-tomcat-5.5.26"
      installrank="1" 
      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"      
     />
</project>

The attributes in the XML shows the package is of type, "zip" and is named "apache-tomcat-5.5.26.zip" and will be installed to "$CTIER_ROOT/demo/apache-tomcat-5.5.26". You can see other metadata describing version buildtime, repository URL among others.

Upload the file to the repository

The next step is to upload the file to the repository using the metadata defined in the xml file above.

Use the upload command from the "zip" type to upload the zip file and the metadata XML file:

	ctl -m zip -c upload -- \
            -xml $CTIER_ROOT/pkgs/apache-tomcat-5.5.26.zip.xml \
	    -filename $CTIER_ROOT/pkgs/apache-tomcat-5.5.26.zip 

Output from the upload should resemble the text below:

Uploading to: http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip
Uploading: apache-tomcat-5.5.26.zip
Puted 1 file to http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/apache-tomcat-5.5.26.zip
Set registration params from xml file: /demo/object.xml

After the package has been registered you can query the repository and see it listed.

Use the find-resources command to list all "zip" packages:

	$ ctl -p demo -m ProjectBuilder -c find-resources -- -type zip
	|
	|--(zip) apache-tomcat-5.5.26.zip

For a graphical alternative, you can use the PackageManager in Workbench and view the packages there.

Go to Workbench → PackageManager → Package List. You will see it list all packages.

Creating a package from a directory

You might have a directory of files that you want to archive and then later extract during deployment. In this section you will see how to create an archive from a reference directory and then upload it to the repository.

Prepare reference directory

A reference directory is a directory that contains the files and directories as you want them on the target hosts relative to its installation root directory.

For this example, imagine we have a reference directory named "foo-agent" that contains an executable called foo.agent, and a configuration subdirectory.

Follow the steps below to simulate the foo-agent reference directory:

• First create the installation root directory:

cd $CTIER_ROOT/pkgs
mkdir -p foo-agent/conf

• Populate the directory with the foo agent files:

touch foo-agent/foo.agent
touch foo-agent/conf/foo.conf

The reference directory now contains one subdirectory, "conf" and two files: foo.agent and foo.conf.

$ ls -lR foo-agent
foo-agent:
total 12
drwxrwxr-x  2 alexh alexh 4096 Jan 17 19:35 conf
-rw-rw-r--  1 alexh alexh    0 Jan 17 19:35 foo.agent

foo-agent/conf:
total 4
-rw-rw-r--  1 alexh alexh 0 Jan 17 19:35 foo.conf

Archive the files and upload the archive to the repository

With the reference installation directory prepared you are ready to create the package. This is done via the "create" command.

The create command takes several options.

• The -installroot option references your reference directory.
• The -filename option specifies the package file that will be the archive of the installroot.

Use the create command with the following options to create the archive:

ctl -m zip -c create -- -installroot $CTIER_ROOT/pkgs/foo-agent -filename foo-agent-1.zip -buildstamp 1

Packaging files in directory: /home/alexh/ctier/pkgs/foo-agent ...
Building zip: /home/alexh/ctier/pkgs/foo-agent-1.zip
Copying 1 file to /home/alexh/ctier/pkgs
Generated package metadata file: /home/alexh/ctier/pkgs/foo-agent/../object.xml
Done.

As you can tell by reading through the message output, the files were packaged into an archive called "foo-agent-1.zip" .

Next create a metdata file to describe it:

File listing: foo-agent-1.zip.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE project PUBLIC "-//ControlTier Software Inc.//DTD Project Document 1.0//EN" 
    "project.dtd">
<project>
  <package 
      arch="noarch"
      base="foo-agent" 
      buildtime="20090117" 
      description="The Foo Agent archive." 
      filename="foo-agent-1.zip" 
      filetype="zip" 
      installroot="${env.CTIER_ROOT}/pkgs/foo-agent" 
      installrank="" 
      name="foo-agent-1.zip" 
      release=""
      releasetag=""
      repoUrl="/zip/zips/foo-agent-1.zip" 
      restart="false"
      type="zip"
      vendor=""
      version="1"      
      />
</project>	

Use the upload command to upload and register the package to the repository:

$ ctl -m zip -c upload --\
   -xml $CTIER_ROOT/pkgs/foo-agent-1.zip.xml \
   -filename $CTIER_ROOT/pkgs/foo-agent-1.zip

Uploading to: http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip
Uploading: foo-agent-1.zip
Puted 1 file to http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip
Loading metadata from XML file: '/home/alexh/ctier/pkgs/foo-agent-1.zip.xml' ...
Loading "/home/alexh/ctier/pkgs/foo-agent-1.zip.xml" ...
1 file(s) have been successfully validated.
Processing /home/alexh/ctier/pkgs/foo-agent-1.zip.xml to /home/alexh/ctier/ctl/var/tmp/projectxml-34564367.xml
Loading stylesheet /home/alexh/ctier/ctl/projects/demo/modules/ProjectBuilder/lib/load-resources/projectxml/project.xsl
Mapping XML to properties ...
Collecting object attributes ...
Batching object attribute updates ...
Batching resource and referrer updates ...
Executing batch update ...

After the package has been registered you can query the repository and now see it listed:

	$ ctl -p demo -m ProjectBuilder -c find-resources -- -type zip
	|
	|--(zip) apache-tomcat-5.5.26.zip
	|
	|--(zip) foo-agent-1.zip

Uploading without an XML metadata file

It's also possible to create and upload a package without creating an XML metadata file. This makes creation and upload one operation.

In this mode, you do not need to provide an XML file. The package will be registered based on the information provided by create's arguments.

cd $CTIER_ROOT/pkgs
ctl -m zip -c create -- -installroot `pwd`/foo-agent -filename foo-agent-1.zip -upload 
Copying 1 file to /tmp 
Generated package metadata file: /home/alexh/ctier/pkgs/foo-agent/../object.xml 
Packaging files in directory: /home/alexh/ctier/pkgs/foo-agent ... 
Building zip: /home/alexh/ctier/pkgs/foo-agent-1.zip 
Uploading to: 
http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip 
Uploading: foo-agent-1.zip 
Puted 1 file to 
http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip 
Set registration params from xml file: /home/alexh/ctier/pkgs/foo-agent/../object.xml 
Done. 

As you can tell by reading through the output, the files were packaged up into a new archive called "foo-agent-1.zip" and uploaded to the repository. At the end the archive was registered as a package using metadata generated by the create command.

Install Package

Now that the archive file is created, uploaded and registered it is ready for deployment.

All packages' installation cycle is driven by the Install command. This command is actually a workflow that has a number of steps including: checking installation status, download from repository, extraction and finish.

You can deploy the desired package via the Install command by specifying its package name and type. The "-t" and "-o" options specify the zip type and the name, "foo-agent-1.zip":

$ ctl -t zip -r foo-agent-1.zip -c Install 

Start: "Install object and run the package installation cycle." commands: assertPackageIsInstalled
begin workflow command (1/1) -> "assertPackageIsInstalled " ...
Executing ant file: /home/alexh/ctier/ctl/projects/demo/modules/Package/bin/is-installed.xml
Running handler command: installPackage
begin workflow command (1/5) -> "installDependencies -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip" ...
Dispatching command 'Install' to objects:  ...
end workflow command (1/5) -> "installDependencies -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip"
begin workflow command (2/5) -> "prepare -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip" ...
end workflow command (2/5) -> "prepare -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip"
begin workflow command (3/5) -> "get -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip" ...
Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip
To: /home/alexh/ctier/pkgs/foo-agent/foo-agent-1.zip
end workflow command (3/5) -> "get -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip"
begin workflow command (4/5) -> "extract -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip" ...
Expanding: /home/alexh/ctier/pkgs/foo-agent/foo-agent-1.zip into /home/alexh/ctier/pkgs/foo-agent
end workflow command (4/5) -> "extract -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip"
begin workflow command (5/5) -> "finish -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip" ...
Deleting: /home/alexh/ctier/pkgs/foo-agent/foo-agent-1.zip
end workflow command (5/5) -> "finish -filename foo-agent-1.zip -installroot /home/alexh/ctier/pkgs/foo-agent -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/foo-agent-1.zip"
end workflow command (1/1) -> "assertPackageIsInstalled "
[command.timer.demo.Package.Install: 3.620 sec]
Workflow completed. execution time: 3.620 sec

The output shows a message for each of the workflow steps. When the installation is complete the files will have been extracted to the registered "installroot".

The Install command accepts the "-installroot" parameter in case you want to change the installation root directory:

$ ctl -t zip -r foo-agent-1.zip -c Install  -- -installroot /tmp/baba
.
.
.
end workflow command (1/1) -> "assertPackageIsInstalled -installroot /tmp/baba"
Workflow completed. execution time: 3.539 sec

The directory listing below shows the archive content extracted to "/tmp/baba":

$ ls /tmp/baba
conf  foo.agent

Related Topics

You might have a build process that is generating artifacts you would like to add to the repository. Consult the Builder page for information on integrating with build tools.

You might want to deploy these packages to application services. Consult the Deploying Packages to a Service and Service Package Deployment Example.

v • d • e User Guide Introduction User Guide · ControlTier · Getting started · Architecture · Presentations · Screencasts Projects Projects overview · Creating a project · Bulk Node registration · View resources · View events Command execution Command execution · Running ad hoc commands · Running defined commands · Dispatcher options  · CTL Center · Creating jobs · Running jobs Examples Replace your SSH loop script  · Automate deployment with Jobs  · Automate deployment with ctl-exec · Scripters cookbook

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