Structuring a Deployment Package, part 1: Understanding the complexity

25 Mar, 2010
Xebia Background Header Wave

A deployment package arguably is never just a single file to be dropped somewhere and you are done. No! Choosing and bundling your artifacts for deployment is none less complex than figuring out an efficient deployment strategy itself. The Java EE specification suggests EARs as the standard packaging and distribution mechanism but we all know that this is not enough. In reality the ‘deployment package’ comprises a whole list of artifacts and more:

  • EARs
  • WARs
  • database scripts
  • static content like images files and icons
  • scripts to create queues, topics and data sources

In short, an EAR and a lot around it! But wait, there is still more, what about the plethora of environment specific configurations that also go along?

This leads to a few questions and the reason for this blog.

What goes into a deployment package and what not? Is there any standard way of deciding the grouping? What are the factors that influence the bundling and how can the environment specific properties be managed?
There is no simple answer but let’s start by categorizing the components that can be a part of the deployment package. Broadly there are four categories of components.


  1. application artifacts: EAR, WAR, static content etc.
  2. middleware resource configurations: scripts to create queues, topics, data sources etc.
  3. environment specific configurations: connection properties for databases, servers and other middleware, LDAP configurations, security credentials etc.
  4. process scripts: deployment automation scripts

Keeping this in mind, the following patterns (in order of maturity) can be observed across the IT landscape:

Simply ad hoc:


There is no standard followed as such. An application build with the artifacts is released to the deployers. The deployers carry out the required setup and deploy the app by referring to a deployment document which may or may not be a part of the release. This document could just be an email describing the required steps to be carried out or a first cut release document. This document also holds the environment specific configurations and settings. It may sound too rudimentary but it is a common practice even in large organizations.

  • It is obvious that this is inherently a time consuming and painstaking process.
  • It assumes that the deployment process or the deployment package contents will not change over time, which is wrong.
  • Deployment Knowledge (environment specific configs, middleware configs and process scripts) is scattered and out of sync.

Moving to standardization:


Each release is accompanied by a deployment release note where you can find all environment specific steps and configuration for development, test and production. The initial release may be a detailed “How to deploy” booklet followed by later delta releases. These delta documents just have instructions for how to tweak or steps and configuration for the changes. A general deployment document will have details like which database scripts to be executed, which queues to be created on which server, configurations to connect to LDAP etc. And also the configuration properties required for each environment. This is definitely better than the previous scenario but still can give you nightmares.

  • It is still a manual process with a lot depending upon how well the deployer follows the instructions and hence prone to error.
  • There is no way to compare two releases.
  • Takes longer and difficult for a new deployer to deploy. He may shuffle through some year old documents which might not be relevant any more. A lot of ‘how to’, ‘what to’ and ‘where’ is still in the heads of the deployment team. So just releasing deltas is not helpful or efficient.
  • Deployment Knowledge is organized but with limitations.

The Standardized approach:

Hand drawing empty diagram

A release structure is decided and followed with a definite format to arrange the artifacts.

There may be a release document but the focus is more on moving the Deployment Knowledge from the documents and making them available for automation. So it is moving from manual deployments to automated deployments.

A typical automation ready deployment package would consist of neatly arranged artifacts, accompanied by environment specific configurations and likely the deployment scripts as well. So is it good? To a point, yes. It makes your deployments reliable and faster. But as you can see there is high coupling of the environment specific configurations with your deployment artifacts both being a part of the deployment package. This leads to some new issues that need to be addressed:

  • The developers are responsible for the release and they package the environment specific configurations, provided to them by deployment team. This is prone to error.
  • Also some of the configurations(eg. production environment configurations) may not be exposed to the developers. So these might be left empty and will still require manual steps.
  • Rollbacks to any particular version is still a headache. No device to directly compare the changes and steps therefore to move to a previous version.
  • No way to automatically get rid of the redundant infrastructure or configuration not used any more.
  • Customizing your deployment package for a new environment is again a manual and time consuming process.
  • The release structure could become a complex tree of folders and sub folders with applicable scripts and configurations that go along.

So there are certain visible drawbacks and limitations of bundling the environment configurations into the deployment package itself. Is there a way out?


Getting it Right:


From our experience we have learnt that an ideal unit of deployment should have the following characteristics:

  • A unit of deployment should be simple and focus on the artifacts (and middleware configurations) only. The developers should not worry about the environment specific configuration while releasing a build.It seems like back to sqaure one when we suggest a simple deployment package with artifacts and middleware configurations, but the idea is to delegate environment specific configs to be managed by deployment automation tools.
  • The environment configuration should be seen as an aspect applied to a deployment package to make it work for a specific environment. It is understandable that it is the ‘bridge’ between your deployment package and the environment where it is deployed. So it should be dealt separately.
  • The unit of deployment and the artifacts within should be versionable.
  • It should be easy to switch between versions with little or no effort.
  • The Deployment Knowledge should be automated.

Is it possible to keep the deployment package simple and yet reap the benefits of deployment automation? With Deployit that is exactly what we want to achieve.
In the next blog we followup with Deployit’s approach and proposals to ‘get it right’.


Get in touch with us to learn more about the subject and related solutions

Explore related posts