Project overview
The project is at the heart of the RapidDeploy application. Typically it will have a project root directory, below which artifacts and configuration are stored. A project may be directly related to a specific development project, such as a small web application project, or may be the basis for just one deployable component of a much larger software development effort. Typically a project will be the basis of one or more version locked deployable components, for example one or more script, ear, war or jar files, that form a Unit of Deployment.
A large development project with many independent components, such as web applications, web servers, scripts and database objects, may have many RapidDeploy projects (Units of Deployment), which may be run independently or as part of a Job Plan.
Each project has exactly one orchestration task flow, which determines the task steps to run for each job this project runs. This task flow is largely target independent. The task flow is edited through the UI and stored in the project as an xml file.
Each task in the task flow allows the setting of multiple data dictionary parameters (keys), in place of setting literal values. The data dictionary keys you define are automatically discovered whenever you save the project. You can set/edit the values for these keys on the orchestration data dictionary panel. This panel defines the 'Project Scoped' data dictionary values which will be used if the corresponding key value is not set at the target scope.
The Project scoped data dictionary parameters may be overridden at the target scope, to allow target differences such as database passwords to be set for each target this project deploys to.
The storage location of configuration files, whether in the fileystem or in an SCM repository, is determined from the project root directory (or working copy directory).
You can point multiple projects to the same root directory, but supply different orchestration file names, so that each project can perform different actions on the same set of configurations and deployable artifacts.
Project Description
Project Orchestration
The orchestration file is located in the project root directory and by default is called midvision-deploy-orchestration.xml. It may be edited through the RapidDeploy GUI on the project Orchestration tab. The orchestration defines the task steps to run on the target servers. You can select tasks from a palette of base tasks and additional plugin-dependent tasks. Each task will normally define all of the configuration required to perform the task, in the form of fields known as task parameters. Most tasks also support one or more outputParameter fields. These typically contain the outputs from the task or true/false results.
outputParameters may be used as inputs in any fields of any subsequent tasks in the task flow.
The task steps are usually, but not always, target neutral. Configuration differences between targets are specified using Data Dictionary values.
As well as the standard tasks, there are some special tasks listed below:
- Select 'Conditionals and Loops' to add basic programming constructs into your orchestration such as 'If', 'While' and 'ForEach' statements.
- Select 'Add Target Specific' to add tasks that run only on the specified target(s), for example to check a change management tool in a production target only.
- Select 'Add RD Job Task' to add a 'Linked Deployment' which enables the current task flow to callback into RapidDeploy to invoke another job on this or a different target, either as a synchronous (wait) or asynchronous (parallel) call. For example, in between application stop/start on the current target, call out synchronously to a Database deploy project to make changes to a database.
Project Data Dictionary
The dictionary file is located in the project root directory and is called 'data-dictionary.xml'. It may be edited through the RapidDeploy GUI on the project 'Orchestration' -> 'Data Dictionary' tab.
Data dictionary parameters are key/value pairs of the following form:
@@DATA_DICTIONARY_KEY@@ Data-Dictionary-Value
The Data Dictionary defines the differences between one target and another target. The (target specific) dictionary values are injected into the deployment orchestration at deployment time.
Project, Target and Job scopes are supported.
- Project Scope - Any Data Dictionary values set at project scope are used by all targets, unless overridden by the target scope.
- Target Scope - Overrides Data Dictionary values at the project scope for a particular target.
- Job Scope - Overrides Data Dictionary values at the project and target scopes. Can be set when a job is called via the web services interface. User is prompted to enter Job Scoped Data Dictionary values in the UI if the value is empty at the Project and Target scope. This is called 'Late Property Injection'.
Project Deployable Resources
The projects deployable resources can be stored locally under the project root directory, or pulled in at package time from an external resource location. They tend to be target neutral resources such as scripts, Ear files, Jar files etc. Typically they represent the 'payload' of the job and are often the output of a continuous integration or build process.
Local resources
The projects deployable resources can be stored locally under the project root directory under the 'resources' folder. You can add resources by uploading them through the RapidDeploy GUI on the Projects Files tab or via the command line in the filesystem.
External resources
Created packages can contain one or more external resources that are added to the package during the package creation. These resources are selected on the project main 'General' tab by selecting from the list of available resources.
The selected resources are stored in a 'resources.xml' file in the project root directory.
New resources can be defined on the resources panel, by defining a resource based on one of the external resource types (Maven, SCP, FileSystem, HTTP (wget) etc). All defined resources can be consumed by any project.
Targets
A 'Target' is defined as an 'Installation' on a 'Server', together with any target specific 'Configuration'. A project can define many deployment targets. For example a project might define several development, test, UAT and production targets, each of which can be deployed to independently or as part of a release 'Pipeline'. Each deployment target can override the Data Dictionary values discovered and set at Project scope.
You can click on the 'Server' and 'Installation' links on the 'Targets' list panel to go to the Server or Installation definition respectively. You can click on the 'Edit' button in the 'Actions' panel next to the chosen 'Target' on the list panel to go to the target specific configuration ('Data Dictionary' panel).
Deployment Package
The deployment package is a point in time, zipped copy of the project root directory that is stored outside SCM, normally on the filesystem or in an artifact repository such as Maven. It will also contain any external resources as required by the project (see above). The package will be named according to the label in the Scm repository. This package contains all of the configuration and artifacts to completely build (from scratch) and/or update ALL of the targets that this package relates to.
This package can be created the RapidDeploy application itself using the Projects Package Wizard or through a Job Plan by selecting 'NEW VERSION' on the version selector. In the latter case, a new package is created in the project as the first step each time the pipeline is invoked, and used for all subsequent targets in the pipeline for this project.
Project location
Using the HELLO_WORLD demo project as an example. If we set the Project root directory (using the FileSystem plugin) to:
c:/temp/projects/HELLO_WORLD
Location of Project Deployable Artifacts
The storage location of deployable artifacts is determined from the project root directory 'resource.xml' file. What you need to specify will be determined by the resources used. The resources to be included are selected on the Project General panel from the 'Available Project Scoped Resources' pick-list. To add new resources, go to 'Resources'. See Resources for further details. The deployable artifacts can be sourced from many locations using different resource plugin types, e.g. Maven, Filesystem, SCP, HTTP etc. The resources are added to the deployable package at package creation time.
By default the resources will be placed into a 'resources' sub-folder off the main project folder at package creation time.
Location of the Orchestration File
The orchestration file is located in the project root directory. It may be edited directly or through the MidVision GUI application on the project panels. This file defines the task steps to run on the target servers. By default this file is called 'midvision-deploy-orchestration.xml'
Location of the Dictionary File
The dictionary file is located in the project root directory. It may be edited directly or through the MidVision GUI application on the project panels. This file defines the target differences injected into the deployment orchestration at deployment time. By default this file is called 'data-dictionary.xml'.
Location of the log settings File
Each project can set the log levels for executing jobs. This is set in the 'log4j.properties' file located in the project root directory.
Export / Import
The project can be exported as a single package to be imported in the future via a wizard page. If the user is grated he is able to download the project as a single zip file in the project details page on edit mode. This single project zip file can be uploaded from project list page if the user is allowed to this operation. Once the file is uploaded the user is redirected to import project wizard page. The project import operation includes project settings, resources and target files. If any resource does not already exist, they will be restored at the same point when they were exported.