Deployit Reference Manual

Preface

This manual contains general background information for users of Deployit.

Deployment Overview

Deployit is the first out-of-the-box deployment automation solution that allows non-experts to perform application deployments. A deployment consists of all the actions needed to install, configure and start an application on a target environment. Deployments are defined by:

• A Package or what is to be deployed.
• A Environment or where the package is to be deployed.
• A Deployment or customizations to the package to be deployed.

Once the what and the where are known, h Deployit (and it's runbooks) takes care of the how by putting together a list of steps (such as copying files, starting / stopping application servers) that perform the actual deployment.

Deployments can be categorized into two major categories:

• Initial deployments
• Upgrade deployments

A deployment is an initial deployment when the package is deployed to the environment for the first time. This type of deployment typically requires some effort to get right because all deployed items must be specified and configured. A user familiar with the middleware setup and with experience in this area is normally involved in this activity.

Once the initial deployment has been configured, all subsequent deployments of the package to the environment are upgrade deployments. These deployments reuse the deployed items from the initial deployment and can typically be performed without any further configuration. Consequently, users without any knowledge of the middleware setup can perform these deployments.

Deployit Concepts

These are the main concepts in Deployit, in alphabetical order.

Archetypes

An archetype is a die for creating many similar Configuration Items (CIs) and are a way to reduce duplication of data. An archetype contains default values for properties that are the same for all of the CIs that are created based on the archetype. CIs created from an archetype have the option of overriding the values from the archetype. A CI created from an archetype keeps the link to the archetype so that updates to the archetype's properties are immediately made for all of the related CIs. Archetypes can also be nested.

For example, if we define an archetype UnixHost that has the property OS Family set to the value UNIX. If we create host CIs web1 and web2 based on the UnixHost archetype, both host CIs inherit the OS Family property from the archetype. If we change the OS Family property to WINDOWS on the archetype, the value will automatically change for both host CIs. If we change the OS Family property to WINDOWS on web1, this overrides the value on the UnixHost archetype. Any changes to OS Family on the archetype now only affect the web2 CI.

Artifacts

Artifacts are files containing application resources such as code or images. The following are examples of artifacts:

• a WAR file.
• an EAR file.
• a file containing static content such as HTML or images.
• a folder containing SQL upgrade files.

In the Unified Deployment Model, a complete application (consisting of both artifacts and middleware resources) is contained in a single deployment package.

Command Line Interface (CLI)

The Deployit CLI provides a way to programmatically interact with Deployit. The CLI can be programmed using the Python programming language. For more detailed information, see the Deployit Command Line Manual.

Configuration Items (CIs)

A configuration item (CI) is a fundamental structural unit in a configuration management system. In Deployit, a CI is a container for properties and relations to other CIs. A CI holds information about a part of the infrastructure, application or deployment. A CI has a certain type that determines what information it contains and what it can be used for.

The following are some examples of CIs:

• web1.acme.com. This is a CI of type Host.
• Oracle 11g on db1.acme.com. This is a CI of type Database. Note that this CI links to a Host CI indicating where the database is running.
• Tomcat 7.0 on web1.acme.com. This is a CI of type TomcatServer. Note that this CI links to a Host CI indicating where the server is running.
• PetClinic. This is a CI of type Application.
• PetClinic/1.0. This is a CI of type DeploymentPackage. Note that this CI links to an Application CI indicating which application the package contains.
• Test. This is a CI of type Environment. It contains CIs to which applications can be deployed.
• PetClinic/1.0 on Test. This is a CI of type Deployment. Note that this CI links to an Application CI indicating the application that is deployed, and an Environment CI indicating where the application is deployed.

Deployit CIs all share certain properties:

• id. This is the id of the CI, a unique identifier for this CI that can be used to reference it. The id determines the place of the CI in the Repository.
• archetypeId. This specifies which archetype (if any) the CI has. See section Archetypes for more information.

Some properties of a CI are mandatory (must be given a value before the CI can be used), others are optional. To determine which properties are available and which are mandatory or optional for a CI, see the CI Reference or use the help facility in the Deployit CLI.

Deployed Items

Deployed items are members of a deployment package that have been deployed on some target middleware. The deployed item can be configured for the specific target it is mapped to during the deployment. When configuring a deployed item it is possible to override any CI properties that the CI has in the generic package. This allows a single package to be used in different environments.

Deploying an Application

This process installs a particular application (represented by a deployment package) on an environment. Deployit copies all necessary files and makes all configuration changes to the target middleware that are necessary for the application to run. If there is already a version of the application running on the environment, the deployment is an upgrade rather than an initial deployment (see Upgrading an Application). Before performing an initial deployment, all deployed items must be configured correctly for the deployment to work.

Deployment ARchive (DAR) Format

The DAR format is the native format Deployit supports for deployment packages. A DAR file is basically a Java jar archive containing a specially formatted manifest. The archive contains the package's artifacts while the middleware resources are described in the archive's manifest file. Deployit processes the manifest file to know which CIs are stored in the archive.

For a comprehensive description of the manifest format, see the Deployit Packaging Manual.

Deployment Package

A deployment package is an archive containing a particular version of an application, containing all artifacts and middleware resources that the application needs. It is independent of the environment it is deployed in (see Unified Deployment Model).

Deployit accepts packages in the Deployment ARchive (DAR) format.

Environment

An Environment is a grouping of infrastructure items, such as hosts, servers, clusters, etc. Environments can contain any combination of infrastructure items that are used in your situation. An environment is used as the target of a deployment, allowing members of the deployment package to be mapped to members of the environment.

Middleware Resources

Middleware resources are pieces of middleware configuration that an application is dependent on. The following are examples of middleware resources:

• a queue.
• a topic.
• a datasource.
• a classpath entry.

In the Unified Deployment Model, a complete application (consisting of both middleware resources and artifacts) is contained in a single deployment package.

Plug-in

A plug-in is a self-contained piece of functionality that adds capabilities to the Deployit system. Plugins contain Runbooks, Steps and Configuration Item types.

Repository

The repository is a storage space for all things Deployit knows about. This includes configuration items (CIs), binary files (such as deployment packages) and Deployit's security configuration (user accounts and rights). The repository can be stored on disk (default) or in a database (see Configuring Database Storage).

In Deployit, the repository conforms to the Java Content Repository (JCR) standard. Deployit's repository has a hierarchical layout and a version history. The repository stores all CIs of all types. The top-level folders indicate the type of CI stored below it. Depending on the type of CI, the repository stores it under a particular folder:

• Application CIs are stored under the /Applications folder.
• Environment CIs are stored under the /Environments folder.
• Middleware CIs (Host, Server, etc.) are stored under the /Infrastructure folder.
• Archetypes are stored under the /Archetypes folder.

Containment and References

Deployit's repository contains CIs that are containers for other CIs. There are two ways in which CIs can refer to each other:

• Containment. In this case, one CI contains another CI. If the parent CI is removed, so is the child CI. An example of this type of reference is an Environment CI and it's deployed applications.
• Reference. In this case, one CI refers to another CI. If the referring CI is removed, the referred CI is unchanged. Removing a CI when it is still being referred to is not allowed. An example of this type of reference is an Environment CI and it's middleware. The middleware exists in the /Infrastructure folder independently of the environments the middleware is in.

Deployed Applications

Deployed applications have a special structure in the repository. A deployed application is the result of deploying a package to an environment. While performing the deployment, package members are installed as deployed items on individual environment members. In the repository, the deployed application CI is stored under the Environment node. Each of the deployed items are stored under the infrastructure members in the Infrastructure node.

So, deployed applications exist in both the /Environment as well as /Infrastructure folder. This has some consequences for the security setup. See the Deployit System Administration Manual for details.

Runbook

A runbook is a component that generates a steplist when presented with a task. A runbook can produce steps for any task or only for particular tasks. A runbook is integrated into Deployit by means of a plug-in.

Deployit ships with the following runbooks:

• Tomcat runbook. This runbook makes it possible to deploy to the Tomcat application server.
• JBoss runbook. This runbook makes it possible to deploy to the JBossAS application server.

XebiaLabs also provides the following optional runbooks:

• WAS runbook. This runbook makes it possible to deploy to the WebSphere Application Server (WAS).
• WLS runbook. This runbook makes it possible to deploy to the WebLogic application server.
• IBM MQ runbook. This runbook makes it possible to deploy to the IBM MQ Series platform.
• IBM Portal runbook. This runbook makes it possible to deploy to the IBM WebSphere Portal application server.

It is also possible to customize Deployit by building your own runbook from scratch or by changing an existing runbook. Please see the Deployit Programmers Manual for more information.

Step

A step is one concrete action to be performed to accomplish a task. A step is created by a runbook and contained in a steplist. Deployit ships with a number of standard infrastructure steps. Other middleware-specific steps are contributed by the plugins.

The following are examples of steps:

• copy file /foo/bar to host1, directory /bar/baz.
• restart the Apache HTTP server on web1.
• create a virtual host in the WAS server on was1.
• run the SQL installation files on b1.

Steplist

A steplist is a sequential list of steps that is generated by one or more runbooks when a task is executed. The steplist contains all steps that Deployit will execute to perform the task.

Task

A task is an activity in Deployit. When starting a deployment, Deployit will create and start a task. The task contains a list of steps that must be executed to successfully complete the task. To execute the task, Deployit will execute each of the steps in turn. When all of the steps are successfully executed, the task itself is successfully executed. If one of the steps fails, the task itself is marked stopped.

Deployit supports the following tasks:

• deploy application. This task deploys a package onto an environment.
• upgrade application. This task upgrades an existing deployment of an application.
• undeploy application. This task undeploys a package from an environment.
• discovery. This task discovers middleware on a host.

Task Recovery

Deployit periodically stores a snapshot of the tasks in the system to be able to recover tasks if the server crashes. If this happens, Deployit reloads the tasks from the recovery file when it restarts. The tasks, deployed item configuration and generated steps will all be recovered. Tasks that were running in Deployit when the server crashed will be put in STOPPED state so the user can decide whether to rerun it or cancel it. Tasks that were not yet started (for instance, a deployment for which only mappings have been configured, but no steplist was generated) will not be recovered.

Task Reloading

When a user logs in, the Deployit GUI loads any tasks that are pending for this user from the repository and displays them in tabs. This includes tasks that were stopped or executing when the user closed his browser,

Task State

Deployit allows a user to interact with the task. In addition to starting a task, a user can:

• stop the task. Deployit will wait for the currently executing step to finish and will then cleanly stop the task. Note that, due to the nature of some steps, this is not always possible. For example, a step that calls an external script may hang indefinitely.
• abort the task. Deployit will attempt to kill the currently executing step. If successful, the aborted step and task are marked failed.
• cancel the task. Deployit will remove the task from the system. If the task was executing before, the task will be archived since it may have made changes to the middleware. If the task was pending and never started, it will be removed.

Undeploying an Application

This process removes an application from an environment. Deployit stops the application and removes the package from the target middleware.

Unified Deployment Model (UDM)

The UDM is XebiaLabs' model for describing deployments and is used in Deployit. The UDM consists of the following components:

• Deployment Package. This is an environment-independent package containing a complete application. The application contains both artifacts as well as associated middleware resources.
• Environment. This is an environment containing deployment targets, i.e. resources that applications can be deployed on. An example is a test environment containing a cluster of WebSphere servers.
• Deployment. This is the process of installing and configuring a deployment package onto a specific environment.

Upgrading an Application

This process replaces an application deployed to an environment with another version of the same application. If the application is not running on the environment, the deployment is an initial deployment (see Deploying an Application). When performing an upgrade, most deployed items can be inherited from the initial deployment. Deployit recognizes which artifacts in the deployment package have changed and deploys only those artifacts.

Configuration Item Reference

Deployit ships with a number of configuration items that you can use to define your middleware configuration and deploy applications. This section contains an overview of these CIs, their purpose and the properties they support. This section of the manual was generated from the Deployit CLI interface.

Application

An application. Each version of the application is a separate package.

Type: com.xebialabs.deployit.ci.Application

ConfigurationFiles

Folder in the Application Package containing configuration files. Might contain sub folders

Type: com.xebialabs.deployit.ci.artifact.ConfigurationFiles

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.
• placeholders(Set): Placeholders found after scanning the artifact

ConfigurationFilesMapping

A mapping of a ConfigurationFiles CI to a Host

Type: com.xebialabs.deployit.ci.artifact.mapping.ConfigurationFilesMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• targetDirectory(STRING): The directory on the target host to which the configuration is to be copied. Example: /data/petclinic/1.0/conf. It can be overidden by using Key TARGET_DIRECTORY
• createIfNotExist(BOOLEAN): create the target directory and sub directory if they are not exist
• keyValuePairs(List<com.xebialabs.deployit.ci.mapping.KeyValuePair>): Key Value Pairs
• placeholderFormat(ENUM): Placeholder Format
  • Values: [SPRING, WINDOWS_SHELL, STARS, NONE]
• shared(BOOLEAN): The target directory is shared when another resources using it as well, default true.

Database

SQL database instance

Type: com.xebialabs.deployit.ci.Database

Properties:

• host(com.xebialabs.deployit.ci.Host): The host on which the SQL client is running
• password(STRING): value of the password option provided to the client command, replaces "${password}" in options
• user(STRING): value of the user option provided to the client command, replaces "${user}" in options
• command(STRING): The plain command to the SQL client, such as "/home/centos/oracle/product/10.2.0/db_5/bin/sqlplus" for Oracle or "/usr/local/mysql/bin/mysql" for MySql
• database(STRING): value of the database option provided to the client command, replaces "${database}" in options
• options(STRING): All options for the command, such as "user / {password}@${database}" for Oracle or "-u user - p{password} ${database}" for MySql

DeployableArtifact

Deployable artifact.

Type: com.xebialabs.deployit.ci.artifact.DeployableArtifact

Properties:

• location(STRING): Location of the artifact.

Deployment

A deployment of an application package or a deployable artifact to a middleware CI or an environment.

Type: com.xebialabs.deployit.ci.Deployment

Properties:

• source(com.xebialabs.deployit.ci.DeploymentPackage): Source
• target(com.xebialabs.deployit.ci.Environment): Target
• mappings(Set<com.xebialabs.deployit.ci.mapping.Mapping>): Mappings
• vhostDefinition(STRING): The virtual host : as used by the HTTP and application server. Valid examples; www.xebialabs.com:80

DeploymentPackage

A package of a certion version of an application, i.e. a grouping of a number of deployable artifact CI's. Contains as its members all the application components that make it up. Is contained by the Application CI of which it supplies a version.

Type: com.xebialabs.deployit.ci.DeploymentPackage

Properties:

• application(com.xebialabs.deployit.ci.Application): The application the package is a part of.
• deployableArtifacts(Set<com.xebialabs.deployit.ci.artifact.DeployableArtifact>): The set of deployable artifacts that are part of this package
• middlewareResources(Set<com.xebialabs.deployit.ci.MiddlewareResource>): The set of middleware resources that are part of this package
• version(STRING): The version of the application package. Examples; 1.0, 1.2.3, 1.0-SNAPSHOT, 3.4-MILESTONE-RC-3

Ear

Deployable EAR artifact.

Type: com.xebialabs.deployit.ci.artifact.Ear

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

EjbJar

Deployable EJB JAR artifact.

Type: com.xebialabs.deployit.ci.artifact.EjbJar

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

EjbJarMapping

A mapping of an EjbJar to any kind of middleware

Type: com.xebialabs.deployit.ci.artifact.mapping.EjbJarMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• keyValuePairs(List<com.xebialabs.deployit.ci.mapping.KeyValuePair>): Key Value Pairs
• mdbListenerPortJndiNameBindings(List<com.xebialabs.deployit.ci.mapping.MdbListenerPortBinding>): Bindings of message driven beans JNDI names to the corresponding listener ports present on the target middleware
• placeholderFormat(ENUM): Placeholder Format
  • Values: [SPRING, WINDOWS_SHELL, STARS, NONE]

Environment

A group where middleware CI's can be added, can serve as a target for a deployment.

Type: com.xebialabs.deployit.ci.Environment

Properties:

• members(Set<java.io.Serializable>): Members

Folder

Description unavailable

Type: com.xebialabs.deployit.ci.artifact.Folder

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

GenericFolder

Folder in the Application Package containing non typed files. Might contain sub folders

Type: com.xebialabs.deployit.ci.artifact.GenericFolder

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

GenericFolderMapping

A mapping of a GenericFolder CI to a Host

Type: com.xebialabs.deployit.ci.artifact.mapping.GenericFolderMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• targetDirectory(STRING): The directory on the target host to which the configuration is to be copied. Example: /data/petclinic/1.0/conf. It can be overidden by using Key TARGET_DIRECTORY
• createIfNotExist(BOOLEAN): create the target directory and sub directory if they are not exist
• keyValuePairs(List<com.xebialabs.deployit.ci.mapping.KeyValuePair>): Key Value Pairs
• placeholderFormat(ENUM): Placeholder Format
  • Values: [SPRING, WINDOWS_SHELL, STARS, NONE]
• shared(BOOLEAN): The target directory is shared when another resources using it as well, default true.

Host

A machine that runs middleware. Used to find out how to connect to the machine to run configuration and installation commands. Contains as its members the middleware CI's running on it (ApacheHttpd, WebSphereCell, etc.).

Type: com.xebialabs.deployit.ci.Host

Properties:

• accessMethod(ENUM): How deployit will access this host. For local use use local, for remote access use the rest of the options.
  • Values: [NONE, LOCAL, SSH_SFTP, SSH_SCP, SSH_SUDO, SSH_INTERACTIVE_SUDO, CIFS_TELNET]
• address(STRING): Where to access this host. Valid examples; www.xebialabs.com, localhost, 127.0.0.1, 172.16.1.3
• operatingSystemFamily(ENUM): The type of operating system this host is running, Valid examples; Windows, Unix
  • Values: [WINDOWS, UNIX]
• password(STRING): The password used to authenticate the username with.
• sudoUsername(STRING): When using the SSH_SUDO access method, deployit will use the sudo username to execute command on this host.
• temporaryDirectoryLocation(STRING): Overrides the location (on windows , on unix /tmp) where deployit will store temporary files.
• username(STRING): The username needed to connect to this host.

HttpdServer

A generic web server.

Type: com.xebialabs.deployit.ci.HttpdServer

Properties:

• host(com.xebialabs.deployit.ci.Host): Host on which the web server runs

Libraries

Folder in the Application Package containing library files. Might contain sub folders

Type: com.xebialabs.deployit.ci.artifact.Libraries

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

LibrariesMapping

Description unavailable

Type: com.xebialabs.deployit.ci.artifact.mapping.LibrariesMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• targetDirectory(STRING): The directory on the target host to which the configuration is to be copied. Example: /data/petclinic/1.0/conf. It can be overidden by using Key TARGET_DIRECTORY
• createIfNotExist(BOOLEAN): create the target directory and sub directory if they are not exist
• keyValuePairs(List<com.xebialabs.deployit.ci.mapping.KeyValuePair>): Key Value Pairs
• placeholderFormat(ENUM): Placeholder Format
  • Values: [SPRING, WINDOWS_SHELL, STARS, NONE]
• shared(BOOLEAN): The target directory is shared when another resources using it as well, default true.

ListenServer

Description unavailable

Type: com.xebialabs.deployit.ci.ListenServer

Properties:

• host(com.xebialabs.deployit.ci.Host): Host
• listenPort(INTEGER): Listen Port

NamedDeployableArtifact

Description unavailable

Type: com.xebialabs.deployit.ci.artifact.NamedDeployableArtifact

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

PermissionScheme

A permission scheme to apply to a configuration item.

Type: com.xebialabs.deployit.ci.security.PermissionScheme

Properties:

• accessControlEntries(List<com.xebialabs.deployit.ci.security.AccessControlEntry>): Access control entries.
• allowedCiTypes(Set): Allowed CI types.

Root

A root in the JCR tree

Type: com.xebialabs.deployit.ci.Root

SqlFolder

Folder in the Application Package containing sql files. Might contain sub folders

Type: com.xebialabs.deployit.ci.artifact.SqlFolder

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.
• filter(STRING): Default is .sql

SqlFolderMapping

Description unavailable

Type: com.xebialabs.deployit.ci.artifact.mapping.SqlFolderMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• keyValuePairs(List<com.xebialabs.deployit.ci.mapping.KeyValuePair>): Key Value Pairs
• placeholderFormat(ENUM): Placeholder Format
  • Values: [SPRING, WINDOWS_SHELL, STARS, NONE]

SqlMapping

Description unavailable

Type: com.xebialabs.deployit.ci.artifact.mapping.SqlMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• keyValuePairs(List<com.xebialabs.deployit.ci.mapping.KeyValuePair>): Key Value Pairs
• placeholderFormat(ENUM): Placeholder Format
  • Values: [SPRING, WINDOWS_SHELL, STARS, NONE]

SqlScript

SQL script instance

Type: com.xebialabs.deployit.ci.artifact.SqlScript

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

StaticContent

Deployable static content artifact.

Type: com.xebialabs.deployit.ci.artifact.StaticContent

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.

StaticContentMapping

A mapping of a StaticContent to any kind of middleware

Type: com.xebialabs.deployit.ci.artifact.mapping.StaticContentMapping

Properties:

• source(java.io.Serializable): Source
• target(java.io.Serializable): Target
• virtualHost(STRING): The virtual host : as used by the HTTP and application server. Example: www.xebialabs.com:80

UnreachableHost

A machine that runs middleware but cannot be directly accessed from the Deployit server. Used to find out how to connect to the machine to run configuration and installation commands. Contains as its members the middleware CI's running on it (ApacheHttpd, WebSphereCell, etc.).

Type: com.xebialabs.deployit.ci.UnreachableHost

Properties:

• accessMethod(ENUM): How deployit will access this host. For local use use local, for remote access use the rest of the options.
  • Values: [NONE, LOCAL, SSH_SFTP, SSH_SCP, SSH_SUDO, SSH_INTERACTIVE_SUDO, CIFS_TELNET]
• address(STRING): Where to access this host. Valid examples; www.xebialabs.com, localhost, 127.0.0.1, 172.16.1.3
• jumpingStation(com.xebialabs.deployit.ci.Host): The host where the ssh tunnel will be started
• operatingSystemFamily(ENUM): The type of operating system this host is running, Valid examples; Windows, Unix
  • Values: [WINDOWS, UNIX]
• password(STRING): The password used to authenticate the username with.
• sudoUsername(STRING): When using the SSH_SUDO access method, deployit will use the sudo username to execute command on this host.
• temporaryDirectoryLocation(STRING): Overrides the location (on windows , on unix /tmp) where deployit will store temporary files.
• username(STRING): The username needed to connect to this host.

War

Deployable WAR artifact.

Type: com.xebialabs.deployit.ci.artifact.War

Properties:

• location(STRING): Location of the artifact.
• name(STRING): The technical name of the artifact as it will be used within application servers.