Best practices for customizing Deploy

When customizing Deploy, it is recommended that you start by extending configuration item (CI) types and writing rules.

If you cannot achieve the desired behavior through rules, you can build custom server plugpoints or plugins using Java. When building a plugin in Java, create a build project that includes the XL_DEPLOY_SERVER_HOME/lib directory on its classpath.

For examples of CI type modifications (synthetic.xml) and rules (xl-rules.xml), review the open source plugins in the Deploy/Replace community plugins repository.

Configuration item type modifications

When modifying CIs or scripts, you should ensure that you can roll back changes to these items’ original state by doing the following:

  • When extending a CI type, copy the existing CI type to a custom namespace for your organization, and then make the desired changes.
  • When modifying a script that is used in a plugin, copy it to a different classpath namespace, then make the desired changes.

Managing synthetic.xml customizations

Deploy will load all synthetic.xml files that it finds on the classpath. This means that you can store synthetic.xml files, associated scripts, and other resources in:

  • The XL_DEPLOY_SERVER_HOME/ext directory. This is recommended for small, local customizations.
  • A JAR file in the XL_DEPLOY_SERVER_HOME/plugins directory. This is recommended for larger customizations. It also makes it easier to version-control customizations by storing them in a source control management system (such as Git or SVN) from which you build JAR files.
  • A subdirectory of the XL_DEPLOY_SERVER_HOME/plugins directory. This is similar to storing customizations in the ext directory or in an exploded JAR file. Using this method, you can also easily version-control your customizations.

Referring from a deployed to another CI

While you can refer from one CI to another, it is recommended that you avoid referring from one deployed to another deployed or to a container.

Plugin idempotency

It is recommended that you try to make plugins idempotent to make the plugin more robust in the case of rollbacks.

Using operations in rules

A rule’s operation property identifies the operations it is restricted to: CREATE, MODIFY, DESTROY, or NOOP.

Generally, a plugin that uses rules should contain one or more rules with the CREATE operation, to ensure that the plugin can deploy artifacts and resources. The plugin should also contain DESTROY rules so that it can update and undeploy deployed applications.

You may also want to include MODIFY rules that will update deployed applications in a more intelligent way. Alternatively, you can choose to use a simple DESTROY operation followed by a CREATE operation.

Handling passwords in plugins

If you develop a custom plugin in Java, ensure that you do not log passwords in plain text while the plugin is executing. You should replace passwords with a string such as ******.

Also, ensure that you do not include passwords in the command line when executing an external tool, because this will cause them to appear in the output of the ps command.