Exploring the Hello World Project

A more detailed look at SCRIPT_DEMO_40

Project Orchestration (task list)

The Orchestration tab contains details of the environment neutral task steps that will be run on each environment configured for this project. An environment is a logical configuration on a server node.

  • Firstly, navigate to Resources-> Projects and edit the project (pencil icon on the tool menu for the SCRIPT_DEMO_40 project line item). 
  • Navigate to the  Orchestration  tab and view the tasklist on the left hand side . We start with the InitialisationTask . This is common to all task lists. 
  • Click on the  + New button in the top right hand corner of the Orchestration Task List panel. This will give a list of all tasks that can be selected and the tasks you see will come from all of the plugins you have installed. As you install more plugins, more tasks related to that plugin will appear in this list.
  • The  InitialisationTask is a mandatory task used to define the starting paramteters for the rest of the task list. Click on it to see the Task Details in the panel on the right hand side. 
  • To see a description of the task and a list of all task parameters for the InitialisationTask, click on the ? button in the top right hand corner of the panel.
  • Let's look at each task parameter in turn.

    • cleanOnFail  is set to true. Determines if temporary files used in the deployment are cleaned up on failure. Set this to false if you need to further degug a failed job.
    • useAntCompression   is false. Determines if ANT based compression should be used. If false, standard Java utilites are used.
    • sourceVariables   is set to true. This tells RapidDeploy to expand, at runtime, any variables in the form ${VAR} to the value of the corresponding environment variable set for the scope of this deployment (for example in the .bash_profile file of the user running this deployment) on the target host. These variables could be in any environment configuration files.
    • checkTmpSize . Check there is enough space in the temporary storage on this server to expand the deployment package. The checkTmpSizeMultiplier is used to determine the amount of space you need relative to the size of the deployment package, so a factor of 2 would mean there must be 200Mb free for a 100Mb deployment package.s.
  • The final (mandatory) task is the FinalisationTask . This task is used to clean up after all the other tasks have been run.
    • retainExpandedArchive . This task tells RapidDeploy to retain the expanded archive file after the job has completed. Normally it is deleted. You might want to do this to further examine the archive files, including search/replaces etc, after the deployment has completed successfully. Use the cleanOnFail  parameter on the InitialisationTask  to perform the same job in a failure scenario.
  • Now let's take a look at the EchoTask(s). These are simply echoing text to the log file. In this case they serve to demonstrate RapidDeploy built in variables and environment variable expansion.
    • EchoTask-Show-Inbuilt-Variable-Expansion - Echoes the inbuilt variables . A list of built in variables can be found here.
    • EchoTask-Show-Server-environment-Variable-Expansion - Echoes Environment variables set on the server. In this case we are using the data dictionary parameter @@HOME@@, which is referenced in the data dictionary for each target environment as @@HOME@@=${HOME}
    • Shows setting environment variables from source: ${HOME} @@HOME@@
  • ScriptRunnerTask . This task runs a script on the target environment. The script will take command line arguments and echo them, along with environment variables set, to the log file.
    • failOnError  is set to true. All tasks can set this parameter, which determines if the failure of this task fails the entire job, or carries on to the next task in the list.
    • scriptToRunPath is set to /tmp/helloWorld.@@SCRIPT_EXT@@. In this case the extension of the script is set to a data dictionary value, so that it can be different in each different paltform (Windows: bat, Linux: sh).
    • scriptArgs . This parameter sets the command line arguments to pass to the script. Again we could put absolute values here, but in this instance we put a data dictionary value @@SCRIPT_ARGS@@, as this will map to different arguments in each of the four targets.
    • Entries . Under entries we see three environment variables set. These will be set in the shell running the script. The script will echo them out to STDOUT. Note they are set to data dictionary values so that they will be different for each target.
  • Project scoped dictionary items are set on the   Data Dictionary  tab. If you set any new Data Dictionary values in your orchestration, use the Discover button to find those variables and set them at project scope. All Data Dictionary values have a project scope, although the value may be blank. When we look at project targets we will see other scopes.

Project Targets

Now we've defined the tasks to run in each invocation of this job, let's take a look at where the job can be run. In this case we've defined four targets. Two on windows and two on linux. To keep this project quite abstract, the targets defined are shapes. We have two shapes defined, circle and square.

  • Firstly, navigate to Resources-> Projects and edit the project (pencil icon on the tool menu for the SCRIPT_DEMO_40 project line item). 
  • Navigate to the  Targets tab and view the list of environments.
  • Click on the Edit button next to the square application. Choose the windows or linux flavour depending on where your RapidDeploy is installed.  Note that the environment is on localhost in either case.
  • Select Dictionary  ->    Data Dictionary . You can see a number of Data Dictionary parameters set. Note all data dictionary parameters are enclosed in "@@". Now, this data dictionary list defines all the possible differences between environments. Whereever the data dictionary is found, at runtime it will be replaced with the environment specific value. This could be in other configuration files, inside ear or war files, scripts, or the orchestration itself. In short, anywhere in the deployment package.
  • Note the values for @@MV_COLOUR@@@@MV_SIDES@@ and @@MV_SHAPE@@ for the square environment.
  • Note also that data dictionary items may themselves include other data dictionary items. The @@SCRIPT_ARGS@@  parameter is the one we set in the ScriptRunnerTask scriptArgs parameter to pass the command line arguments to the script. It is set to     @@MV_SHAPE@@  @@MV_COLOUR@@   @@MV_SIDES@@.  
  • Now look at the scope column.
    • If the entry reads PROJECT scope, then the value is derived from the project scope value (it has not been set at the target level. 
    • If the entry reads OVERRIDDEN then the project scoped value is overridden by the target scope. 
    • If the entry reads ENVIRONMENT then the value is set from the target only and has a blank setting at project scope.  
    • If the entry reads EMPTY then the data dictionary is not set at either PROJECT or TARGET scope. In this case you will be asked to enter a value (or confirm it is to be left blank) during the deployment job request.
  • Note also that the data dictionary item can be set to an external (server level) environment variable by use of ${VAR}. Here we set the @@HOME@@ to ${HOME} as used in the orchestration above.
  • Now go back the the target list using the  Back    button and select the circle application. Note the differences in the settings for @@MV_COLOUR@@      @@MV_SIDES@@    and    @@MV_SHAPE@@

Project Files

Now we've defined the tasks to run in each invocation of this job and the environment specific values for each environment, let's look at the simple and environment neutral script we'll run on each invocation of the job

  • Firstly, navigate to Resources-> Projects and edit the project (pencil icon on the tool menu for the SCRIPT_DEMO_40 project line item). 
  • Navigate to the  Files tab and view the list of files.
  • Navigate to  Scripts ->  Bin   directory and click on helloWorld.sh. The script is below. Note the command line arguments and environment variables that are echoed.  We are setting both the command line arguments and environment variables in each of our environments.

# helloWorld.sh Script
# Copyright (c) 2011, MidVision Limited. All rights reserved.
# http://www.midvision.co.uk

if [[ $# -ne 3 ]]; then
    echo Please supply at least two parameters to this script.
    exit 1

echo Hello from the Server. 
echo Shape passed: $1
echo Colour passed: $2
echo Sides passed: $3

echo Environment Variables set:

echo Script Complete.

exit 0

Project Packages

Now we can package up all of the internal (and external - more about this later) resources in our project into a deployment package. This is a zip/jar/tar archive containing all the project components at a point in time, versioned with a version number. You can retain this package and deploy it to any target environment at any time. This gives the ability to roll forward and back through changes whenever y

  • Firstly, navigate to Resources-> Projects and edit the project (pencil icon on the tool menu for the SCRIPT_DEMO_40 project line item). 
  • Navigate to the  Packages tab and view the list of previous packages.
  • Click  Create Package  to create a new deployment package.

Run a Deployment job

Now we can deploy the created package to the square environment.

  • Navigate to Jobs-> New Job
  • Select the SCRIPT_DEMO_40 project. You will see a tree view of server/environment and application. 
  • Select the one you want to deploy (the square application for the windows or linux localhost server and dev environment) and follow the wizard. 
  • On the  Version  panel you select the version (package version) you want to deploy. 
  • Since there is only one package, it is preselected. The latest package will always be preselected by default. 
  • Click on the  Skip to Finish  checkbox and click  Next 
  • On the final tab click the  Start Job  button. The deployment is started and you see the tasks executed and job log in real time.
  • Once the deployment completes, check the log file for the following output:

Dictionary values are set:

2015-09-17 17:48:58,475 [RemoteInvocationHandler_29] DEBUG com.midvision.rapiddeploy.domain.deploy.pojo.EnvironmentPropertyFileServices - Key: @@COLOUR@@ Value green
2015-09-17 17:48:58,475 [RemoteInvocationHandler_29] DEBUG com.midvision.rapiddeploy.domain.deploy.pojo.EnvironmentPropertyFileServices - Key: @@SIDES@@ Value 4
2015-09-17 17:48:58,475 [RemoteInvocationHandler_29] DEBUG com.midvision.rapiddeploy.domain.deploy.pojo.EnvironmentPropertyFileServices - Key: @@SHAPE@@ Value square

Echo built-in variables in the echo task:

2015-09-17 17:49:01,605 [RemoteInvocationHandler_29] ERROR org.apache.tools.ant.taskdefs.Echo - ARCHIVE_ROOT_VAL is  /tmp/8b92b290-d092-47bf-9eab-342351ffa790_SCRIPT_DEMO-0.0.5.jar, MV_UUID is d5b8c205-0522-4635-8389-d44b135420f7, MV_DATE_MILLIS is 2015091717490157

Command line arguments passed to the script:

2015-09-17 18:00:29,855 [RemoteInvocationHandler_37] INFO  com.midvision.rapiddeploy.orchestration.tasks.LocalScriptRunnerTask - Running Local Script: scripts/bin/helloWorld.sh Args: square green 4

Script runner output from the HellowWorld.sh script:

2015-09-17 17:49:01,626 [RemoteInvocationHandler_29] INFO  com.midvision.rapiddeploy.utilities.exec.LocalScriptRunner - Hello from the Server.
Shape passed: square
Colour passed: green
Sides passed: 4

Environment Variables set:
MV_COLOUR = green
MV_SHAPE = square

Script Complete.