Preparing your application for Deploy

This topic explains how Deploy uses the Unified Deployment Model (UDM) to structure deployments. In this model, deployment packages are containers for complete application distribution. These include application artifacts (EAR files, static content) and resource specifications (datasources, topics, queues, and others) that the application requires to run.

A Deployment ARchive, or DAR file, is a ZIP file that contains application files and a manifest file that describes the package content. In addition to packages in a compressed archive format, Deploy can also import exploded DARs or archives that have been extracted.

Packages should be independent of the target environment and contain customization points (for example, 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.

Contents of an application deployment package

An application deployment package contains deployables. These are:

• The physical files (artifacts) that define a specific version of the application. Examples: an application binary, configuration files, or web content.
• The middleware resource specifications that are required for the application. Example: a datasource, queue, or timer configuration.

The deployment package should contain everything your application requires to run and that should be removed if your application is undeployed, excluding resources that are shared with multiple applications.

Deployment commands and scripts

The deployment package for an application should not contain deployment commands or scripts. When you prepare a deployment in Deploy, a deployment plan is automatically generated. This plan contains all the steps required to deploy your application to a target environment.

Environment-specific values

An environment is a grouping of infrastructure and middleware items such as hosts, servers, clusters, and other. An environment is used as the target of a deployment. You can map deployables to containers of the environment.

A deployment package should be independent of the environment where it will be deployed. The deployables in the package should not contain environment-specific values. Deploy supports placeholders for environment-specific values.

Deploying shared resources

If you have resources that are shared by more than one application, ensure you package these resources so that Deploy can deploy them. Do not include the resources in the deployment package for an individual application that uses them. Create a deployment package that contains shared resources and use placeholders to refer to these shared resources from your application packages.

Understanding deployable types

Every deployable in a package has a configuration item (CI) type that describes the deployable. The CI also determines the steps that Deploy will add to the deployment plan when you map the item to a target container.

The plugins that are included in your Deploy installation determine the CI types that are available for you to use.

Exploring CI types

Before you create a deployment package, explore the CI types that are available. To do this in the Deploy interface, import a sample deployment package:

1. Go to Explorer.
2. Hover over Applications, click , and select Import > From Deploy server.
3. Select the PetClinic-ear/1.0 sample package.
4. Click Import. Deploy imports the package.
5. Click Close.
6. Click to refresh the CI Library.
7. Expand an application, hover over a deployment package, click , and select New to see the CI types that are available.

Select the CI type to use

The CI types that you need to use are determined by the components of your application and by the target middleware. Deploy includes types for common application components such as files that need to be moved to target servers.

For each type, you can specify properties that represent attributes of the artifact or resource to be deployed. Examples of properties are the target location for a file or a JDBC connection URL for a datasource. If the value of a property is the same for all target environments, you can set the value in the deployment package.

If the value of a property varies across your target environments, use a placeholder for the property. Deploy automatically resolves placeholders based on the environment to which you are deploying the package.

Create a deployment package

There are multiple methods to create a deployment package:

• Using the Deploy interface
• Using a plugin for a tool such as Maven or Jenkins
• Using a command line tool such as zip

Environment-independent packages

To make the deployables in your package environment-independent:

1. Use placeholders for values that are specific to a certain environment, such as database credentials.
2. Create sets of key-value pairs called dictionaries, which contain environment-specific values and associate them with the appropriate environments.

When you import the deployment package or create it in the Deploy interface, Deploy scans the deployables for placeholders. When you execute the deployment, Deploy replaces the placeholders with the values in the dictionary.

Add placeholders to deployables

Review the components of your application for values that are environment-specific and replace them with placeholders. A placeholder is surrounded by two sets of curly brackets. For example:

jdbc.url=jdbc:oracle:thin:{{DB_USERNAME}}/{{DB_PASSWORD}}@dbhost:1521:orcl

Create a dictionary

To create a dictionary that defines environment specific values:

1. In the Deploy interface, go to the Explorer.
2. Hover over Environments, click , and select New > Dictionary. The dictionary properties appear.
3. Enter a name for the dictionary in the Name field.
4. On the Common tab, click Add new row to add entries to the dictionary.
5. Under Key, enter a placeholder that you are using in the application, without brackets (DB_USERNAME and DB_PASSWORD from the example above).
6. Under Value, enter the value that Deploy should replace the placeholder with when you deploy the application to the target environment.
7. Click Save.
8. Double-click the environment that will use the newly created dictionary. The environment properties appear.
9. On the Common tab, select the dictionary you created.
10. Click Save.

When you execute a deployment to this environment, Deploy replaces the placeholders with the values that you defined. For example:

jdbc.url=jdbc:oracle:thin:scott/tiger@dbhost:1521:orcl

Create a deployment package in the Deploy interface

When creating a deployment package in the Deploy interface, you can see the contents of a DAR file and the structure of a manifest file. For more information about creating a deployment package, see Add a package to Deploy.

Export the deployment package

1. In the Explorer, expand Applications.
2. Expand an application and select a deployment package.
3. Hover over the package, click , and select Export. The DAR file is downloaded to your computer.

To open the DAR file, change the file extension to ZIP, then open it with a file archiving program. In the package, you will see the artifacts that you uploaded when creating the package and a manifest file called deployit-manifest.xml. The manifest file contains:

• General information about the package, such as the application name and version
• References to all artifacts and resource definitions in the deployment package

For more information, see Deploy manifest format.

For Windows environments, there is a Manifest Editor that can help you create and edit deployit-manifest.xml files. For information about using this tool, see GitHub.

Create a deployment package using a Deploy plugin

Deploy includes plugins that you can use to automatically build packages as part of your delivery pipeline. Some of the plugins that are available are:

• Maven
• Jenkins
• Bamboo
• Team Foundation Server (TFS)

Create a deployment package using a command line tool

You can create DARs automatically as part of your build process without using a build tool or CI tool. A DAR is a ZIP file that contains a Deploy manifest file in the root folder. You can use a command line tool to build the DAR file. Examples of such tools are:

• zip
• Java jar utility
• Maven jar plugin
• Ant jar task

Import a deployment package

To deploy a package that you have created to a target environment, you must make the package available to the Deploy server. You can do this by publishing the package from a build tool or by manually importing the package.

The tools listed above can automatically publish deployment packages to a Deploy server. You can also publish packages through the Deploy user interface, the command line, or a Web request to the Deploy HTTP API.

Import a deployment package using the Deploy interface

You can import deployment packages from the Deploy server or from a location that is accessible via a URL, such as a CI server or an artifact repository such as Archiva, Artifactory, or Nexus. For information about importing a deployment package, see Add a package to Deploy.

Create and verify the deployment plan

Every plugin that is installed can contribute steps to the deployment plan. When Deploy creates the plan, it integrates these steps to ensure that the plugins work together correctly and the steps are in the right order.

To preview the deployment plan that Deploy will generate for your application, create a deployment plan and verify the steps.

Check the target environment

Before you can create a deployment plan, ensure the target environment for the deployment is configured. To see the environments that have been defined in Deploy, go to Explorer and expand Environments.

To verify the containers of your target environment, double-click it and review its properties. The Containers list shows the infrastructure items that are part of the environment. If your target environment is not yet defined in Deploy, you can create it by right-clicking Environments and selecting New > Environment.

If the infrastructure containers in your target environment are not available in the CI Library, you can add them by:

• Using the Deploy discovery feature. For more information, see Discover middleware.
• Manually adding the required configuration items. For more information, see Create a new CI.

Create the deployment plan

To create the deployment plan:

1. Click Start a deployment.

2. Under Applications, expand your application.

3. Select the desired version of your application and drag it to the left side of the Deployment Workspace.

4. Under Environments, select the environment where your application should be deployed and drag it to the right side of the Deployment Workspace.

5. Click to automatically map your application’s deployables to containers in the environment.

6. Double-click each mapped deployable to verify that its properties are configured as expected. You can see the placeholders that Deploy found in your deployment package and the values that it will assign to them during the deployment process.

   

7. Click Preview to Preview the deployment plan.

8. Review the steps in the Preview pane.

9. Optionally double click the step to preview the commands that Deploy will use to execute the step.

10. Click Close preview to return to the Deployment Workspace.

Deploy from the application tree node:

1. Select any application.
2. Click and select Deploy latest.
3. Select an environment where your want to deploy the application.
4. Click Continue.
5. Click Deploy to start executing the plan immediately.

Deploy from the package tree node:

1. Select any package.
2. Click and select Deploy.
3. Select an environment where your want to deploy the application.
4. Click Continue.
5. Click Deploy to start executing the plan immediately.

Troubleshoot the deployment plan

When Deploy creates the deployment plan, it analyzes and integrates the steps that each plugin contributes to the plan. If the deployment plan that Deploy generates for you does not contain the steps that are needed to deploy your application correctly, you can troubleshoot it using several different features.

Adjust the deployment plan

You can achieve the desired deployment behavior by:

• Adjusting the properties of the CI types that you are using
• Using different CI types
• Creating a new CI type

To check the types that are available and their properties, follow the instructions provided in Exploring CI types. The documentation for each plugin describes the actions that are linked to each CI type.

If you cannot find the CI type that you need for a component of your application, you can add types by creating a new plugin.

Configure an existing plugin

You can configure your plugins to change the deployment steps that it adds to the plan or to add new steps as needed.

For example, if you deploy an application to a JBoss or Tomcat server that you have configured for hot deployments, you are not required to stop the server before the application is deployed or start it afterward. In the JBoss Application Server plugin reference documentation and Tomcat plugin reference documentation, you can find the restartRequired property for jbossas.EarModule, tomcat.WarModule, and other deployable types. The default value of this property is true. To change the value:

1. Set restartRequired to false in the XL_DEPLOY_SERVER_HOME/conf/deployit-defaults.properties file.
2. Restart the Deploy server to load the new configuration setting.
3. Create a deployment that will deploy your application to the target environment. You will see that the server stop and start steps do not appear in the deployment plan that is generated.

For more detailed information about how Deploy creates deployment plans, see Understanding the packaging phase. For information about configuring the plugin you are using, refer to its manual in the Deploy documentation.

Create a new plugin

To deploy an application to middleware for which Deploy does not already offer content, you can create a plugin by defining the CI types, rules, and actions that you need for your environment. In a plugin, you can define:

• New container types, which are types of middleware that can be added to a target environment
• New artifact and resources types that you can add to deployment packages and deploy to new or existing container types
• Rules that indicate the steps that Deploy executes when you deploy the new artifact and resource types
• Control tasks that define actions you can perform on new or existing container types

You can define rules and control tasks in an XML file. Implementations of new steps use your preferred automation for your target systems. No specialized scripting language is required.