This manual describes how to package applications for use in Deployit.
See the Deployit Reference Manual for background information on Deployit and deployment concepts.
The Deployit deployment automation tool is designed to help you deploy application packages to target middleware. To make it possible to deploy your applications, they must be packaged in a format that Deployit understands. This manual describes Deployit's standard package format (the Deployment ARchive (DAR)) and various other topics related to packaging applications. Note that it is also possible to implement a custom importer that recognizes a different format.
Deployit uses the Unified Deployment Model (UDM) to structure it's deployments (see the Deployit Reference Manual for more information). In this model, deployment packages are containers to distribute complete applications, including both the application artifacts (EAR files, static content) as well as the resource specifications (datasources, topics, queues, etc.) that the application needs to run.
Packages should be independent of the target environment and contain customization points (for instance placeholders in configuration files) that supply environment-specific values to the deployed application. This enables a single artifact to make the entire journey from development to production.
Out of the box, Deployit supports it's own DAR format for packages. A valid DAR package consists of the following components:
Valid DAR archives can be produced using standard command line tools, such as the Java jar utility, the Maven jar plugin or the Ant jar task. There is also a Deployit maven plugin to facilitate packaging. See the section Using the Maven plugin below.
In addition to packages in a compressed archive format, Deployit can also import exploded DARs or archives that have been extracted.
The manifest file included in a DAR describes the contents of the archive for Deployit. When importing a package, the manifest is used to construct CIs in Deployit's repository based on the contents of the imported package. For background information on the JAR format and manifest, see the JAR file specification.
A valid Deployit manifest starts with the following preamble:
Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
This identifies the Java manifest version and the Deployit package format version.
A deployment package contains a specific version of an application. These entries tell Deployit that the package contains the AnimalZoo application version 4.0:
CI-Application: AnimalZoo-ear
CI-Version: 4.0
These entries are part of the manifest preamble.
Artifacts are represented by files or folders in the deployment package. To import an artifact as a CI in Deployit, use:
Name: AnimalZooBE-1.0.ear
CI-Type: jee.Ear
CI-Name: AnimalZooBE
The standard Name entry must refer to an actual file included in the DAR. The CI-Type specifies a CI type name that is available in the system. The required CI-Name property indicates the name of the CI to be created.
Similarly, this construct can be used to create a folder CI:
Name: conf
CI-Type: file.Folder
CI-Name: configuration-files
Resource specifications are not represented by files in the deployment package. They represent resources that must be created on the target middleware when the application is deployed. Resource specifications are constructed completely based on the information in the manifest. The manifest also specifies values for properties of the CI.
For example, this manifest snippet constructs a was.OracleDatasourceSpec CI:
Name: petclinicDS
CI-Type: was.OracleDatasourceSpec
CI-driver: com.mysql.jdbc.Driver
CI-url: jdbc:mysql://localhost/petclinic
CI-username: petclinic
CI-password: my$ecret
The Name entry specifies the name of the CI to be created. In contrast to the manifest specification, the Name property in a Deployit manifest does not refer to a physical file present in the DAR in the case of a resource specification. The CI-Type specifies a CI type that is available in the system.
Note: the names of artifacts in your package must conform to platform requirements. For instance, a file.Folder CI with name "q2>2" cannot be deployed to a Windows host, because ">" may not be part of a file or directory name in Windows.
The other entries, CI-url, CI-username and CI-password refer to properties on the datasource CI. These properties will be set to the values specified. In general, any property on a CI can be set using the CI-<propertyname> notation. See the Command Line Interface (CLI) Manual for information or how to obtain the list of properties that a particular CI type supports, or consult the relevant CI reference documentation.
Note that it is also possible to add resource specifications to a package that is already imported in Deployit. See the Command Line Interface (CLI) Manual for more information.
The above example showed how to set string properties to a certain value. In addition to strings, Deployit also supports references to other CIs in the package, sets, booleans and enumerations.
Properties that are a set of strings are configured as follows:
CI-setproperty-entryvalue: a
CI-setproperty-entryvalue: b
CI-setproperty-entryvalue: c
Properties referring to other CIs or a set of CIs are configured as follows:
CI-artifactRef: myArtifactCiName
CI-resourceSpecRef: myResourceSpecName
Note that references to artifacts use the referent's CI-Name property and references to resource specifications use the referent's Name property.
Boolean and enumeration properties are configured as follows:
CI-bool: true
CI-bool: false
CI-enum: ENUM1
Deployit supports the use of placeholders to customize a package for deployment to a specific environment. CI properties specified in a manifest file can also contain placeholders. These placeholders are resolved from dictionary CIs during a deployment (see the Deployit Reference Manual for an explanation of placeholders and dictionaries). This is an example of using placeholders in CI properties in a was.OracleDatasourceSpec CI:
Name: petclinicDS
CI-Type: was.OracleDatasourceSpec
CI-driver: com.mysql.jdbc.Driver
CI-url: jdbc:mysql://localhost/petclinic
CI-username: {{DB_USERNAME}}
CI-password: {{DB_PASSWORD}}
To illustrate the way a deployment package can be created, let's describe a complete example of how to do this by hand. There is a lot of work involved in creating packages by hand, so this is not the recommended way. Subsequent sections will describe how to automate this by using the Deployit maven plugin, the maven jar plugin or the ant jar task.
Let's say we want to create a package for version 1.0 of our brand new PetClinic application. The application contains an EAR file with the application code, a configuration folder containing configuration files and a datasource. Start by creating a directory petclinic-package to hold the package content:
mkdir petclinic-package
cd petclinic-package
Now, collect the EAR file and configuration directory and store them in the newly created directory. The datasource is a resource specification, not an artifact, so there is no file to include:
cp /some/path/petclinic-1.0.ear .
cp -r /some/path/conf .
Now, let's create the DAR manifest for these entries. After the required preamble, add the application and version
CI-Application: PetClinic
CI-Version: 1.0
Now add the EAR and configuration folder:
Name: petclinic-1.0.ear
CI-Type: jee.Ear
CI-Name: PetClinic-Ear
Name: conf
CI-Type: file.Folder
CI-Name: PetClinic-Config
Add the datasource to the manifest as follows:
Name: PetClinic-ds
CI-Type: was.OracleDatasourceSpec
CI-driver: com.mysql.jdbc.Driver
CI-url: jdbc:mysql://localhost/petclinic
CI-username: {{DB_USERNAME}}
CI-password: {{DB_PASSWORD}}
Note how the datasource uses placeholders because the username and password are be different per environment.
The complete manifest looks like this:
Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: PetClinic
CI-Version: 1.0
Name: petclinic-1.0.ear
CI-Type: jee.Ear
CI-Name: PetClinic
Name: conf
CI-Type: file.Folder
CI-Name: PetClinic-Config
Name: PetClinic-ds
CI-Type: was.OracleDatasourceSpec
CI-driver: com.mysql.jdbc.Driver
CI-url: jdbc:mysql://localhost/petclinic
CI-username: {{DB_USERNAME}}
CI-password: {{DB_PASSWORD}}
Save the manifest outside of the package directory, so for instance in the /tmp directory. Finally, create the DAR archive with the command:
jar cmf ../petclinic-1.0.dar /tmp/MANIFEST.MF *
The resulting archive can be imported into Deployit.
To enable continuous deployment, Deployit can be integrated with the Maven build system. A maven plugin exists that exposes some of Deployit's functionality via maven. Specifically, the plugin supports:
For more information, see the Deployit maven plugin documentation.
The standard maven jar plugin can also be used to create a Deployit package.
In the maven POM, configure the jar plugin as follows (the manifest file is assumed to be in the project's src/main/resources/META-INF directory):In the maven POM, configure the jar plugin as follows (the manifest file is assumed to be in the project's src/main/resources/META-INF directory):
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
...
<configuration>
<includes>
<include>**/*</include>
</includes>
<archive>
<manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
</archive>
</configuration>
...
</plugin>
</plugins>
</build>
...
</project>
The Deployit package can be generated by invoking the command:
mvn package
Creating a Deployit package via Ant is possible using the jar task.
In the Ant build file, include a jar task invocation as follows (the manifest file is assumed to be called MANIFEST.MF):
<jar destfile="package.jar"
basedir="."
includes="**/*"
manifest="MANIFEST.MF"/>
Deployit ships with several sample packages. These examples are stored in the Deployit server's importablePackages directory.