Introduction

The installation of the automation framework involves two key components, Jenkins and the CAST Batch Web Service. Jenkins will run under almost any operating system, however since CAST will only run on windows, to keep things simple, it is recommended that it be installed under windows. This is only a recommendation, if the client has a working version of Jenkins, in an environment other than Windows use it.
This section describes the installation process for all required components.

Prerequisites

Environment

  • At least one Windows 2008 or 2012
  • 4-8 GB RAM, 
  • 5-10 GB free disk space
  • CSS Database
  • Java JRE 7 or 8
  • Access to SMTP  to allow email transmission

Software

  • CAST AIP full installation - See Compatibility Test chart to see which tooling versions have been tested at Automation Tooling#FieldToolingCompatibilityTesting
    NOTE: JAF works with a CAST AIP triplet which maintains only one application.
  • CAST Batch Web Service, installed as a windows service 
  • Jenkins Continuous Integration tool, installed as a windows service 
  • CastAIPWS Jenkins Plugin
  • CastAAD Jenkins Plugin
  • PG Admin tool
  • Any SCM systems that are in use at the client site must be installed on the delivery server

Service Account
A single Service Account should be generated to run CAST, Jenkins and the CAST Batch Web Service.

  1. The account needs the ability to run services
  2. Full Access to all CAST AIP installation folders
  3. Access to the Jenkins installation folder
  4. Access to the CAST application drop site folder

 

CAST Batch Web Service

The CAST Batch Web Service (CBWS) is used to streamline the work of delivering the source code, performing analysis and generating a snapshot. The CAST Jenkins plugin directs the to the CBWS to perform these operations. The CAST Batch Web Service (CBWS) is the main component that is invoked by the Jenkins job in order to kick off a source code extraction and delivery job. Therefore, if the mode of configuration is such that the code is situated or accessible on the same machine as the analysis server, there will be only one copy of the CAST Batch Web Service required to be installed. If the code is being delivered from an external source (i.e. client location), then a copy of the CBWS will also need to be deployed on the external machine.
As shown in the diagram below, every instance of AIC Portal must correlate on a one to one basis with a copy of the CBWS on the Delivery Machine. This copy of the CBWS on the Delivery Machine must also correlate to a CBWS copy on the Analysis Machine. If the analysis is being performed on a separate server, do note that there must also be matching installation on the analysis server. In cases where the source code is being delivered by way of secure FTP transfer, the customer facing CBWS instance will now deliver the code to a DMZ folder on the CAST environment. This is usually the case with Managed Services Clients. The example below explains this more clearly.

To improve performance, one can setup multiple analysis servers with each connected via a load balancer. To allow the automation process to work each analysis server must have an identical configuration. As with the single analysis server, each subsequent server must have a web service installed for each AIC Portal being utilized.
In the event that more than one service is installed on a single server, each installation must have a unique port assigned. Complete instructions on how to install the CAST Batch Web Service are below.

CAST Batch Web Service Installation

The CAST system requires a Windows operating system to function while Jenkins can run under both Windows and Unix. In addition, to improve performance, Jenkins and CAST can be installed over multiple servers. The work of delivering the source code, performing analysis and generating a snapshot is not done by Jenkins, but by the CAST Batch Web Service (CBWS) module. The Jenkins CAST plugin sends instructions, and receives status from CBWS, which does the actual work. There needs to be one installation of the web service for each AIC portal. If the analysis is run on a separate server then there also needs to be a matching installation there.
It is recommended that multiple installations of the CBWS are installed, with one installation for each AIC Portal and one for each analysis server. In the event that more than one service is installed on a single server, each installation must have a unique port assigned.

  • Configure CBWS Installation File
    • Extract CBWS to the WebServices folder on the server e.g. folder D:\Installs\CastBatchWebServer as shown in the image below
    •  Edit InstallCastBatchWS.bat which exists in the expanded folder.  This .bat file is used to install the CBWS Windows service.

      • Update the line “SET INSTALL_FOLDER=D:\Installs\%SERVICE_NAME%” to reflect the installation folder mentioned above e.g. “SET INSTALL_FOLDER=D:\Installs\CastBatchWebServer”
      • Confirm jar version in the CLASSPATH variable mentioned on line   “SET CLASSPATH="%INSTALL_FOLDER%\dependency\*;WSBatchServer-1.5.jar”  matches the jar file version available in the expanded folder e.g. WSBatchServer-1.5.jar 
      • Save the modifications
    • Update the relevant configuration value in the CastAIPWS.properties file accordingly to the installation environment.
      NOTE:  This file uses linux style path i.e. "/"  forward slash and not the "\" backslash as used in Windows

       PropertyDescription
      castms.client=C:/Program Files/CAST/8.1/CAST-MS-cli.exePath to the CAST-MS-cli .exe
      dmt.client=C:/Program Files/CAST/8.1/DeliveryManagerTool/DeliveryManagerTool-CLI.exePath to the DeliveryManagerTool/DeliveryManagerTool-CLI.exe
      backup.client=C:/Program Files/CAST/8.1/CSSAdmin/CSSBackup.exePath to CSSBackup.exe
      restore.client=C:/Program Files/CAST/8.1/CSSAdmin/CSSRestore.exePath to CSSRestore.exe
      psql.client=C:/Program Files/CAST/CASTStorageService2/bin/psql.exePath to Potgres psql.exe
      aicPortal.deliveryFolder=C:/CASTMS/8.1/DeliveryPath to AIC Portal delivery Folder
      aicPortal.url=http://localhost/CAST-AICPURL to AIC Portal
      validation.prob.service=http://gaicvmportal:92/ValidationProbesService.asmxURL to AOP Validation Service
      qa.scans=falseFlag to enable (value set to true) / disable  (value set to falase) ProactiveQA feature
      validation.stop=falseFlag to specifiy rescan action based on validation results. Value set to "true" will stop resacan when validation check returns non-green.  Value set to "false" will permit the rescan to contine to irrespective of validation results.
      caip.version=8.3

      Value set to 8.3 : this will use the snapshot captureDate parameter to select the snapshot to be delete in JAF version 1.5 build 4 and after.

      Value set to 8.2 or no value which will default to 8.2 : will use existing snapshot delete functionality present in JAF version 1.5 build 3 and earlier.

      backup.folder=C:/CASTMS/BackupFolder location for store CSS backups used during backup/restore/optimise steps
      backup.database=postgresCSS database connection type
      backup.database.host=localhostCSS database connection host
      backup.database.port=2280CSS database connection port
      db.alter.batch=C:/CASTMS/CastBatchWSServer/dbAlter.batLocation of script used to perform database Alter during CSS optimise step
      db.delete.batch=C:/CASTMS/CastBatchWSServer/dbDelete.batLocation of script used to perform database drop cascase  during CSS optimise step
      aad.client=C:/Program Files/CAST/8.1/AAD/CLI/AadConsolidation.exePath to AADConsolidation.exe
      aad.clean=false 
      cast.database=jdbc:postgresql://localhost:2280/postgresCSS connection string
      db.user=operatorCSS operator user name
      db.password=CastAIPCSS operator password
      #parameters used for Empowerment report generatorDeprecated parameters - Do not use
      reportGenerator.client=C:/Program Files/CAST/8.1/ReportGenerator/CastReporting.Console.exeDeprecated parameters - Do not use
      reportGenerator.templates=C:/Users/CASTUS/AppData/Local/CAST/ReportGenerator/TemplatesDeprecated parameters - Do not use
      reportGenerator.outputFolder=C:/CAST/ReportsDeprecated parameters - Do not use
      empowerment.client=C:/CAST/Tools/Empowerment/Empowerment.exeDeprecated parameters - Do not use
      dmt.fail.no.changes=trueFlag to specifiy action based on the JAF's DMT Delivery Management Report shown in the jenkins console output
      dmt.change.percent=5Percentage value for change which will stop the rescan
      dmt.delivery.report.jar=C:/CASTMS/CastBatchWSServer/dependency/CASTDeliveryReporter.jarLocation for CASTDeliveryReporter.jar
      dmt.log=C:/CASTMS/8.1/CastBatchWSServer/Log/dmtIf dmt.log is set, the option -logFilePath will be added to the DMT command line
      init.batch=C:/Users/nka/SkyDrive/CAST/Projects/WSBatchServer/target/init.batIf init.batch is set, the batch file specified will be executed when the service starts
      java.path=C:/Program Files/Java/jdk1.7.0_79If java.path is set, it'll be used for JNLP calls, allowing to force the usage of a specific version of java
      webservice.port=9880Port number used by the CBWS  (Ensure firewall is open for this port number. It can be opened through Windows Control Panel, Securit, Firewall, advanced setting, inbound rules, new rule, Port <specify the desired ports>.
      smtp.server=smtp.gmail.comEmail SMPT address
      smtp.port=465Email smtp port number
      reply.address=j.godfroid@castsoftware.comEmail reply address
      smtp.login=cast.integration@gmail.comSMTP login if SMTP authentication is requires
      smtp.password=C@stInt3gr@tionSMTP password if SMTP authentication is requires
      smtp.useSSL=trueSMTP SSL flag
  • Install CBWS Windows Service
  • Open Admin command prompt  and launch the InstallCastBatchWS.bat  e.g. D:\Installs\CastBatchWSServer>InstallCastBatchWS.bat. The service will be installed and the pop up below will appear.
  • Update the the service account used to run the service as shown below.

This account should have access to the Web Services folder and CAST Management Studio (CMS). In addition it must be part of the users network group. This is easily accomplished by including the account domain name.

 

After entering the account information click on the apply button if the follow dialog does show up.

 

  • Update Java Settings

To avoid issues with java upgrades, the Java Virtual Machine should be predefined (as shown below). This way, if the user upgrades the Java version it will not affect the CBWS.  You can make this change on the "Java" tab:

    • Uncheck the "Use default" checkbox located on the upper left side of the dialog. 
    • Click on the browse button and locate and select the jvm.dll file found in the server folder of the 1.7.x folder e.g. C:\Program Files\Java\jdk1.7.xx.xx\jre\bin\server\jvm.dll
    • Click the Apply button, located on the lower right of the dialog box.
    • Initial Memory Pool = 128 MB; Maximum Memory Pool = 512 MB  (Note: The amount of memory required is dependent on the size of the application being analyzed. If, while running an analysis, the log shows that the service is out of memory, the maximum memory value should be adjusted accordingly. )
    • Change the account to the service account on Log On.
    • Ensure the service is set to start automatically.
    • Apply changes and Start the Service.





  • Restart CBWS Service

When the service is installed it is pre-configured to automatically start when the server starts.
The means that the service is already running. However in order for the above configurations changed to take effect it must be re-started. To do this go to the first tab, General, first click the stop button, then the start button.


  • Update CastGlobalSettings.ini 

The CastGlobalSettings.ini should be updated to allow the Web Service access to the CMS connection profiles independently of the user running the service.

The file is located in the CAST AIP installation folder e.g. C:\Program Files (x86)\CAST\<CAST Version>\.  

  • Before any modifications are done to the file, make sure the destination folder exists and contains the correct file structure. Using Windows Explorer create following folders:

(Replace drive letter C with whatever is the appropriate installation drive letter)

    • C:\CASTMS\GlobalSettings\
    • C:\CASTMS\GlobalSettings\AllUsers\ (to be set as a value for the variable CAST_ALL_USERS_PATH)
    • C:\CASTMS\GlobalSettings\SharedAppData\ (to be set as a value for the variable CAST_CURRENT_USER_WORK_PATH)
    • C:\CASTMS\GlobalSettings\CastTemp\ (to be set as a value for the variable CAST_CURRENT_USER_TEMP_PATH)
  • Update CastGlobalSettings.ini and modify it accordingly. 
  • Stop and restart the service.

CAST Batch Web Service Advanced Installation

When you have many CAST AIP versions hosted in the same machine, and you want to automate the rescans of all of them, you will need to have a separate CBWS instance by AIP version (you will face this case also, if you have for a single AIP version, many delivery folders). We call a CBWS instance, an installation of the webservice on a new port in the same machine. To do so:
-Copy the installation folder of an existing CBWS, and rename the folder (you can use the AIP version as suffix)
For example, if you want to add a new instance for AIP 8.2.9, starting from the installation described in §1.2.1, your copied folder will be D:\Installs\CBWS\CastBatchWebServer_833
-Rename CastBatchWSServerw.exe to CastBatchWSServer_<AIP_version>w.exe
(In our case, it will be renamed CastBatchWSServer_829w.exe

  • Edit the InstallCastBatchWS.bat file and
  • modify the variable SERVICE_NAME (with the folder name) at the first line,
  • and update the last line before the "pause" command to put the new name of the exe renamed in the previous step

  • Edit the CastAIPWS.properties file:
  • update in it all the paths related to your AIP version
  • Set a new port number not used

Now run the InstallCastBatchWS.bat, and do the same settings described in §1.2.1 starting from step 3

Jenkins Installation

Jenkins is an "extensible continuous integration server". It monitors repeated executions of jobs, such as building software projects, and can be used to build WebObjects applications and frameworks. For Step by step guidance on how to setup Jenkins, refer to the Jenkins Installation Documentation Page https://wiki.jenkins-ci.org/display/JENKINS/Installing+Jenkins+as+a+Windows+service .


The following instructions apply to the specific instance of Jenkins installation on a Windows server that hosts the CAST analysis engine and will be used to setup the CBWS described in the steps prior.

  • Create a folder called 'Jenkins' on the root drive and drop the jenkins.war file you have just downloaded at this location.
  • Open a command prompt (in admin mode) and navigate to the C:\Jenkins folder.
  • Run the war file with the following command: C:\Jenkins> java -jar Jenkins.war --httpPort=9090   (Omitting the --httpPort=9090  will default to port 8080.  Ensure the port number used does not conflict with other port numbers e.g. 8080 used with Tomcat)

  • This will run Jenkins from the command line. You will be asked to allow access through the Windows Firewall. Always 'Allow access' as shown below.

Note: The Jenkins service is being run from the command prompt for the sole purpose of installing the Windows Service for Jenkins.   

 

  • Open a browser window to test that http://localhost:9090/ points to the Jenkins service. At this point we are still running Jenkins on the command prompt (from step above).
  • From your browser, go to "Manage Jenkins" --> Install as Windows Service --> Check that the Installation Directory is at root level (eg: C:\Jenkins) before proceeding to install. If there is a D:\ on the VM/server, try installing Jenkins on the D:\. Wherever possible, change the Jenkins locations to a root level folder on a drive where you can afford allocating a large space.





  • You may be asked to download and install the .NET Framework 3.5 if you don't already have it on your system. Go ahead and install it as part of the Jenkins Service installation if prompted.
  • Press "Yes" when prompted to restart the Jenkins service once it has been installed. By default the Jenkins service will run on a default system account. It is however advisable to setup a service account to run Jenkins under.


[Important]
To change the port number ,please follow the below steps

  • Once the Jenkins is successfully started, an XML called "jenkins" is generated in its root folder ".Jenkins" .
  • Edit the  xml file "jenkins" and change  the port number to --httpPort=9090 as shown below 
  • Restart the  jenkins service

Jenkins Plugins Installation

This automation process is centered around the Jenkins system which is made up of a series of Job, with each job containing one or more tasks. Jenkins is open source and designed to work under both windows and Unix. To allow seamless integration between CAST and Jenkins a series of Plugins have been created with each performing a specific task. All the plugins are included in the CAST Batch Web Service download file.

  • CastAIPWS: This is the main plugin for the Jenkins/CAST interface. Working in conjunction with the CAST Web Service, it allows Jenkins to deliver the code, then deploy it on the CAST server and finally perform the analysis and snapshot process.
  • CastAAD: This plugin performed a refresh on the CAST Application Analytics Dashboard (AAD). It is required to allow the user to see changes made by the analysis process.

Steps to install the plugin are below  and are a one time operation per Jenkins installation. Once done correctly, further jobs (one for each application) can be easily created by cloning the existing job. 

  • In order to install a plugin, the user must have administrative right to the Jenkins system. There are two methods for installing a Jenkins plugin, automatic and manual. Currently all CAST related Plugins must be installed using the manual method.
  • Jenkins Homs Page → Manage Jenkins --> Manage Plugins --> Advanced tab → Upload Plugin Section Choose File →  Select CastAIPWS.hpi file  → Press Upload button.
  • Restart the Jenkins Service
  • Go back to the Manage Plugins page and verify the updated "CAST Jenkins Plugin" is showing.

NOTE: When installing a new version of the CBWS, it is pertinent to note that one must not directly uninstall the old plugin, otherwise all the jobs and configuration related to that job will be lost. The correct way to install the new version is to overlay the existing plugin, never uninstall it. By uninstalling it, one can inadvertently delete the configuration for the pre-configured job. Upon successful update of the existing plugin, look for the message, 'Success. Pending Restart'.

 



 

Uninstallation of a Windows Service

To uninstall this or any other windows service you can do the following:
1.Open a command prompt as an administrator
2.Run the following commands
3.If the service is running, then stop it using: SC stop <service name>
4.When the service is no longer running delete it using: SC delete <service name>


Troubleshooting 

  • Jenkins WAR file installation Issue :"Failed to delete the temporary Winstone file C:\Users\SPA\AppData\Local\Temp\winstone\jenkins.war "
    Remove the multiple entries of winstone jar files from the location keeping  only one winstone jar file .