Exploring the Hello World Project

A more detailed look at SCRIPT_DEMO

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 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.
    • projectDictionaryFile . This file is a project level dictionary file. Any data dictionary items present in this file will be overridden in any environment specific dictionary files.
  • 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.
    • ARCHIVE_ROOT_VAL is  ${ARCHIVE_ROOT}, MV_UUID is ${MV_UUID}, MV_DATE_MILLIS is ${MV_DATE_MILLIS}
    • 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.
    •  scriptRelativeToArchiveRoot is set to true. If this is set to true, the path to the script is relative to the top level of the expanded deployment archive. You can also set this to false and use an absolute path, or use the built-in variable ${ARCHIVE_ROOT}
    • scriptToRunPath is set to @@relativePathToScript_1@@. In this case the path to the script is set to a data dictionary value, so that it can be different in each different environment.
    • envPropertyFileSuffix . This is the suffix of a property file for the environment, containing environment variables to set for the environment in which this script is run. In the case of this project their are four environments, each with different values for the environment variables.
    • 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 @@scriptArguments_1@@, as this will map to different arguments in each of the four target environments.

Project Environments

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 environments. Two on windows and two on linux. To keep this project quite abstract, the environments 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 project line item). 
  • Navigate to the  Environments 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 @@COLOUR@@, @@SIDES@@ and @@SHAPE@@ for the square environment.
  • Note also that data dictionary items may themselves include other data dictionary items. The scriptArguments_1  parameter is the one we set in the ScriptRunnerTask scriptArgs parameter to pass the command line arguments to the script. It is set to     @@COLOUR@@ @@SIDES@@  and  @@SHAPE@@  
  • Note also that the date 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 click on  Properties ->  Environment Variables . You can see a number of environment variables being set to data dictionary values. These could equally be set to absolute values or external environment variables from the server. The script we will run will echo out these environment variables.
  • Now go back the the environment list using the Back   button and select the circle application. Note the differences in the settings for  @@COLOUR@@     @@SIDES@@    and    @@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 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.
#!/bin/sh

# 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.
    echo
    exit 1
fi 

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

echo 
echo 
echo Environment Variables set:
    

echo MV_COLOUR = $MV_COLOUR
echo MV_SHAPE = $MV_SHAPE
echo MV_SIDES = $MV_SIDES
echo 
echo Script Complete.
echo
echo 

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 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 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
MV_SIDES = 4

Script Complete.