WCM Deployment Features 21

Document created by resplin Employee on Jun 6, 2015Last modified by resplin Employee on Sep 8, 2016
Version 9Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com



{{AVMWarning}}
AVM


Introduction


This page highlights the capabilities of the WCM Deployment functionality added in the 2.0.1 release.


Features


The main features of the deployment are listed below, the following sections explain each one in more detail.


  • Deploys authoring environment to an Alfresco instance on a remote machine
  • Multi-server deploy (transactional at the server level)
  • Real-time monitoring of deployment progress
  • Deployment reports

Alfresco To Alfresco Deployment (ASR)


Deployment in the 2.0.1 release and later allows a web project being authored in one Alfresco server instance to be deployed to another separate instance of Alfresco.

The destination Alfresco server may be located on the same machine or on a remote server, the process is identical in either case. For debugging purposes deploying to the same instance is also possible, see the Debugging section for details.

The destination server must have a full Alfresco 2.0 or later installation present and the RMI registry port (50500 by default) accessible.


Alfresco To File Server Deployment (FSR)


The ability to deploy to a remote file server has been added in the 2.1 release.

The destination file server has to be running the Deployment Receiver with it's RMI registry port (44100 by default) accessible.


Multi-server Deployment


The Create and Edit Web Project wizards now have an extra field on step 1, the 'Deploy To' field as shown in the screenshot below.

Deploy-settings.gif

This field allows a comma separated list of destination servers (Alfresco or File Server) to deploy to to be entered, the entries can either be the host name or the IP address of the server. File server destinations are denoted with a prefix of \\.

If a port number is not entered for an Alfresco server the default RMI registry port as configured in the web-client-config-wcm.xml file will be used. Out of the box this is set to 50500. Similarly, if a port number is not entered for a file server the default RMI registry port from the same config file will be used. Out of the box this is set to 44100.

The example in the screenshot above shows that port 50500 will be used for 'liverserver1', port 50900 will be used for 'liveserver2' and port 44100 will be used for 'liveserver3'.

Further servers can be added at any time so if another server is brought online simply add another entry, save the web project settings and deploy to it.


Multi NIC Receivers


When deploying to a receiver agent running on a multi-NIC system it may be necessary to bind the reciever agent (RMI registry) to a particular ip address. To do this you must add the following to the java command in deploy_start.sh/.bat:
-Djava.rmi.server.hostname=x.x.x.x

Where x.x.x.x is the IP address assigned to the NIC you want to bind to.

Look here for more information.

Thanks to Rakesh Kalra at Care.com


Real Time Monitoring


Once the destination servers have been specified a deployment can be initiated. To start a deployment open the list of snapshots in the staging sandbox and click on the deploy action icon shown in the screenshot below.

Deploy-action.gif

This will open the 'Deploy Snapshot' dialog shown below. Each server present in the 'Deploy To' field will be presented with a checkbox.

If the selected snapshot is being deployed for the first time all the servers will be pre-selected. Once a deployment has been completed successfully for a snapshot entering the dialog subsequently will deselect the servers previously deployed successfully. These servers can obviously be re-deployed by re-selecting the checkbox, this may be useful if the deployed site has been compromised and needs to be reset.

Deploy-snapshot.gif

Click OK to start the deployment process. The 'Deploy Snapshot' dialog will close and open the 'Monitor Deployment' dialog. This dialog shows the progress of each deployment currently executing in the server. An AJAX callback is used  to poll the server for progress. The frequency of this polling request can be set in the web-client-config-wcm.xml configuration file. A deployment in progress is shown in the screenshot below.

Deploy-status1.gif

Once the deployment completes the state is updated as shown below. The dialog can be closed at any time during the deployment, however, the dialog can not be returned to (this will be rectified in a future release). To monitor progress if the 'Monitor Deployment' dialog is closed open the snapshot list in the staging area and monitor the status column, 'IN PROGRESS' will be shown if one or more deployment processes are executing.

Deploy-status2.gif


Deployment Reports


When a deployment has completed the status of that deployment is shown in the status column of the snapshot list in the staging sandbox and a 'View Deployment' link will be present as shown in the screenshot below.

Deploy-live.gif

There are 4 possible values for the status column:


  • IN PROGRESS: Deployment is occurring on one or more servers
  • LIVE: All servers were deployed to successfully
  • PARTIAL FAILURE: Deployment failed on one or more servers
  • FAILED: Deployment failed on all servers

Clicking the 'View Deployment' link while the status is 'IN PROGRESS' will show the reports for the servers that have completed, obviously once the status changes to one of the above clicking the 'View Deployment' link will show the reports for all servers deployed to. The example report below shows a successful and failed report.

Deploy-report.gif

There may be times when the expandable Details area does not appear on successful reports. This occurs when a deployment takes place and does not make any changes i.e. the destination server was up to date.


Deployed Runtime


The result of a deployment is a runtime version of the web site. This consists of a single AVM store matching the name of the web project's 'AVM Store Root/DNS name' property. Using the first screenshot in this page as an example the store will be called 'alfresco'.

CIFS can be used to browse the contents of the destination server, again using the example from the screenshot, navigating to \\liveserver_A\AVM\alfresco\HEAD\DATA\www\avm_webapps\ROOT would show you the contents at the root of the web project. The CIFS path can be assigned a drive mapping i.e. Z:\ or a mount point i.e. /mnt/alfresco and then used to serve the website via Apache or the webserver of your choice.

Alternatively, to browse or virtualise the deployed website on the destination server the web client can be used to create a web project before a deployment is attempted. The only requirement is that the DNS name used during the creation of the web project is the same as the web project on the source (authoring) server. The deployment will then use the store created by the web project and thus allow all the familiar web client actions.


Deployed File Server Deployment


The result of a deployment to a file server is dependent upon the settings of the deployment receiver on the remote machine.

By default the entire folder structure of the selected snapshot will be transferred to the remote machine. However, it is possible to deploy a subtree of the selected snapshot via the deployment receiver's configuration file.


Implementation


The following sections provide details on the implementation of the deployment functionality.


Model


The WCM application model has been enhanced to support deployment, namely new properties and an association on the existing wca:webfolder type and the definition of a new wca:deploymentreport type.

The deploymentreport type holds the details of a deployment i.e. the target server, the snapshot version that was deployed, the start and end times, a flag to indicate the outcome and a reason for the failure if the deployment was unsuccessful. The type extends cm:content, thus the content of the type is used to hold the details of the deployment i.e. all the events that occurred if the deployment was successful or the stack trace if the deployment failed.

The type definition for the deploymentreport type is shown below.



<type name='wca:deploymentreport'>
   <title>Website Deployment Report</title>
   <parent>cm:content</parent>
   <properties>
      <property name='wca:deployserver'>
         <title>Server Deployed To</title>
         <type>d:text</type>
         <mandatory>true</mandatory>
      </property>
      <property name='wca:deployversion'>
         <title>Snapshot Version Deployed</title>
         <type>d:int</type>
         <mandatory>true</mandatory>
      </property>
      <property name='wca:deploystarttime'>
         <title>Time Deploy Started</title>
         <type>d:datetime</type>
         <mandatory>true</mandatory>
      </property>
      <property name='wca:deployendtime'>
         <title>Time Deploy Finished</title>
         <type>d:datetime</type>
         <mandatory>true</mandatory>
      </property>
      <property name='wca:deploysuccessful'>
         <title>Deployment Successful</title>
         <type>d:boolean</type>
         <default>false</default>
      </property>
      <property name='wca:deployfailedreason'>
         <title>Failure Reason</title>
         <type>d:text</type>
      </property>
   </properties>
</type>

As mentioned above the existing webfolder type has been modified, 3 properties have been added, one to hold the list of servers to deploy to, one to hold the list of servers selected in the last deployment attempt and one to hold the snapshot version used in the last deployment attempt. A zero to many child association has also been added to the webfolder type, the target being the deploymentreport type introduced above.



<property name='wca:deployto'>
   <title>Deploy To</title>
   <type>d:text</type>
   <multiple>true</multiple>
</property>
<property name='wca:selecteddeployto'>
   <title>Servers Selected For Deployment</title>
   <type>d:text</type>
   <multiple>true</multiple>
</property>
<property name='wca:selecteddeployversion'>
   <title>Snapshot Version Selected For Deployment</title>
   <type>d:int</type>
</property>

<child-association name='wca:deploymentreport'>
   <source>
      <mandatory>false</mandatory>
      <many>false</many>
   </source>
   <target>
      <class>wca:deploymentreport</class>
      <mandatory>false</mandatory>
      <many>true</many>
   </target>
</child-association>

Code


Deploy Snapshot Dialog

The deploy snapshot dialog uses the UIDeployWebsite JSF component to display the list of servers present in the wca:deployto property. It also detects whether any of the configured servers have already had the current snapshot successfully deployed, if they have the server is not pre-selected.

Once the user makes and confirms their selection any deployment reports for the servers selected are removed, the wca:selecteddeployto and wca:selecteddeployversion properties get set and an AVMDeploySnapshotAction instance is created, populated (see next section for details) and executed for each server. Each action is executed asynchronously and passed a  callback object (DeploymentMonitor) to help monitor the deployment progress.

AVMDeploySnapshotAction

The actual deployment is handled by the AVMDeploySnapshotAction repository action, which in turn calls the repository's DeploymentService.

The AVMDeploySnapshotAction takes several mandatory parameters and a couple of optional ones. The parameter definition is shown below:



public static final String PARAM_WEBSITE = 'website';
public static final String PARAM_TARGET_SERVER = 'target-server';
public static final String PARAM_DEFAULT_RMI_PORT = 'default-rmi-port';
public static final String PARAM_DEFAULT_RECEIVER_RMI_PORT = 'default-receiver-rmi-port';
public static final String PARAM_REMOTE_USERNAME = 'remote-username';
public static final String PARAM_REMOTE_PASSWORD = 'remote-password';
public static final String PARAM_CALLBACK = 'deploy-callback';
public static final String PARAM_DELAY = 'delay';

paramList.add(new ParameterDefinitionImpl(PARAM_WEBSITE, DataTypeDefinition.NODE_REF, true,
      getParamDisplayLabel(PARAM_WEBSITE)));
paramList.add(new ParameterDefinitionImpl(PARAM_TARGET_SERVER, DataTypeDefinition.TEXT, true,
      getParamDisplayLabel(PARAM_TARGET_SERVER)));
paramList.add(new ParameterDefinitionImpl(PARAM_DEFAULT_RMI_PORT, DataTypeDefinition.INT, true,
      getParamDisplayLabel(PARAM_DEFAULT_RMI_PORT)));
paramList.add(new ParameterDefinitionImpl(PARAM_DEFAULT_RECEIVER_RMI_PORT, DataTypeDefinition.INT, true,
      getParamDisplayLabel(PARAM_DEFAULT_RECEIVER_RMI_PORT)));
paramList.add(new ParameterDefinitionImpl(PARAM_REMOTE_USERNAME, DataTypeDefinition.TEXT, true,
      getParamDisplayLabel(PARAM_REMOTE_USERNAME)));
paramList.add(new ParameterDefinitionImpl(PARAM_REMOTE_PASSWORD, DataTypeDefinition.TEXT, true,
      getParamDisplayLabel(PARAM_REMOTE_PASSWORD)));
paramList.add(new ParameterDefinitionImpl(PARAM_CALLBACK, DataTypeDefinition.ANY, false,
      getParamDisplayLabel(PARAM_CALLBACK)));
paramList.add(new ParameterDefinitionImpl(PARAM_DELAY, DataTypeDefinition.INT, false,
      getParamDisplayLabel(PARAM_DELAY)));

  • The 'website' parameter is the NodeRef representation of the AVM path of the website to deploy.
  • The 'target-server' parameter is the host name or IP address of the target server (this may also include a port number which overrides the 'default-rmi-port' parameter.
  • The 'default-rmi-port' parameter is the default RMI port to connect to on the remote machine if a port is not passed as part of the server reference in 'target-server'.
  • The 'default-receiver-rmi-port' parameter is the default RMI port to connect to on the remote deployment receiver if a port is not passed as part of the server reference in 'target-server'.
  • The 'remote-username' parameter is the user account to use on the destination server.
  • The 'remote-password' parameter is the the password for the 'remote-username' account.
  • The 'deploy-callback' parameter is an instance of an object implementing the DeploymentCallback interface, if present all deployment events are sent to this listener object.
  • The 'delay' parameter is for testing and debugging purposes, it adds a delay of the specified number of seconds to the start of the deployment.

The AVMDeploySnapshotAction action simply marshals these parameters and calls the repository DeploymentService.

Deployment Service

The DeploymentService is the key part of the deployment process. The JavaDoc for the service is shown below.



/**
  * Deploys the differences between what is is the local source path
  * and a destination machine's path.
  *
  * @param version The local version.
  * @param srcPath The local path.
  * @param hostName The remote hostname.
  * @param port The remote rmi registry port.
  * @param userName The username for authentication.
  * @param password The password for authentication.
  * @param dstPath The destination path corresponding to source path.
  * @param createDst Flag for whether a missing destination should be created.
  * @param dontDelete Don't delete assets at the destination.
  * @param dontDo If this is set then this is a dry run.
  * @param callback A possibly null callback.
  */
public DeploymentReport deployDifference(int version, String srcPath,
                                          String hostName, int port,
                                          String userName, String password,
                                          String dstPath,
                                          NameMatcher matcher,
                                          boolean createDst,
                                          boolean dontDelete,
                                          boolean dontDo,
                                          DeploymentCallback callback);

/**
  * Deploy to a filesystem on another machine.
  *
  * @param version The version to deploy from.
  * @param srcPath The path to deploy from.
  * @param hostName The hostname of the filesystem receiver.
  * @param port The port to connect to.
  * @param userName The username for authentication
  * @param password The password for authentication
  * @param dstTarget The target on the deployment receiver.
  * @param createDst Flag for whether a missing destination should be created.
  * @param dontDelete Don't delete deleted nodes from destination.
  * @param dontDo If this is set, this is a dry run.
  * @param callback A possibly null callback.
  */
public DeploymentReport deployDifferenceFS(int version, String srcPath,
                                            String hostName, int port,
                                            String userName, String password,
                                            String dstTarget,
                                            NameMatcher matcher,
                                            boolean createDst,
                                            boolean dontDelete,
                                            boolean dontDo,
                                            DeploymentCallback callback);



The DeploymentService uses the 'userName' and 'password' to connect to the RMI registry on the Alfresco server or deployment receiver represented by 'hostName' and 'port'. The connection is currently made using RMI, HTTPS connections have been tested but will not be supported until a later release.

Once connected the DeploymentService determines what differences there are between the 'srcPath' and the 'dstTarget' and applies those changes. Although the DeploymentService can leave deleted assets and perform a dry run these features are not currently exercised by the web client.

The 'matcher' parameter, if supplied, allows a subset of 'srcPath' to be omitted from the deployment.

If the optional 'callback' object is present (an implementation of the DeploymentCallback interface) all events that occur during the deployment process are sent to the callback object.

If the deployment is successful a DeploymentReport is returned which contains a list of all the events that occurred as part of the deployment. A failure to deploy is currently indicated by an AlfrescoRuntimeException.

Deployment Callback

As mentioned above a callback object can be used to track progress of a deployment operation. The interface definition for  DeploymentCallback is shown below.



public interface DeploymentCallback
{
    /**
     * Called each time something happens during deployment.
     * This is called synchronously by the deployer and should
     * therefore be handled rapidly, if possible.
     * @param event The event that occurred.
     */
    public void eventOccurred(DeploymentEvent event);
}

Monitor Dialog

When the user clicks OK in the Deploy Snapshot dialog a couple of things occur to allow monitoring of the deployments. A DeploymentMonitor object gets instantiated and passed as the DeploymentCallback object to AVMDeploySnapshotAction. The DeploymentMonitor object itself creates a unique identifier and gets stored using that key in the HTTP session. This identifier is referred to hereinwith as a 'deployment monitor id'. A list of deployment monitor ids is also constructed and stored in the 'AVMBrowseBean' JSF managed bean.

When a deployment operation starts the Monitor Deployment Dialog is opened. This dialog uses the same JSF component as the Deploy Snapshot dialog, UIDeployWebsite. This time however, it is passed the list of deployment monitor ids from AVMBrowseBean and it's 'monitor' attribute is set to true. This shows the same list of selected servers but displays an animated icon instead of a checkbox to provide user feedback on the deployment progress.

Every 2 seconds (this is configurable though) an AJAX call is made back to the server requesting the status of the executing deployments. This is done using the following request (where xxxx, yyyy and zzzz are deployment monitor ids):

/ajax/invoke/DeploymentProgressBean.getStatus?ids=xxxx,yyyy,zzzz

As the URL suggests this calls a JSF managed bean called 'DeploymentProgressBean'. It's responsible for locating the DeploymentMonitor object associated with each supplied deployment monitor id and producing the XML to represent the state of the deployment.

The response is an XML file with the following format:



<deployment-progess>
   <target-server id='xxx' name='host[:port]' finished='true|false' [successful='true|false'] />
</deployment-progess>

There is a 'target-server' element for each server selected by the user. The 'id' attribute contains the deployment monitor id, the 'name' attribute is the host name/IP address and optional port the deployment is going to, the 'finished' attribute indicates whether the deployment has finished and the 'successful' attribute indicates whether the deployment was a success or not. The 'successful attribute is only present once 'finished' is true.

The client side of the UIDeployWebsite component takes the response and updates each server progress area as appropriate.

Deployment Report

As hinted at in the Deploy Snapshot Dialog section above deployment reports are currently only held for the last deployment attempt on the snapshot being deployed. Once another snapshot is deployed all previous deployment reports are removed. In a future release deployment reports will be held against each snapshots enabling historical deployment reports to be maintained.

Once a deployment operations completes, whether successful or not, the AVMDeploySnapshotAction implementation creates a wca:deploymentreport object as a child association on the node representing the web project. The deployment reports are then used to determine the status for the snapshot being deployed i.e. LIVE, PARTIAL FAILURE or FAILED.


Configuration


Several deployment parameters are configurable via the web client configuration mechanism and as such can be overridden using the extension mechanism. web-client-config-wcm.xml contains the default values as shown below:



<deployment>
   <remote-username>admin</remote-username>
   <remote-password>admin</remote-password>
   <remote-rmi-port>50500</remote-rmi-port>
   <receiver-rmi-port>44100</receiver-rmi-port>
   <progress-polling-frequency>2</progress-polling-frequency>
   <delay>30</delay>
</deployment>



'remote-username' and 'remote-password' are ultimately passed to the DeploymentService as the credentials to use on the remote server. The same username and password is therefore used for all destination servers, the ability to provide a username and password for individual servers will be implemented in a future release.

'remote-rmi-port' is the default RMI port to connect to on the destination server. This is only used if a destination Alfresco server is specified in the 'Deploy To' field without a port number.

'receiver-rmi-port' is the default RMI port to connect to on the deployment receiver on the destination server. This is only used if a destination file server is specified in the 'Deploy To' field without a port number.

The 'progress-polling-frequency' value specifies, in seconds, the duration between calls back to the server to check on progress.

Finally, the 'delay' value specifies, in seconds, how much delay to add to the beginning of a deployment. This is only used if the alfresco.deployment.delay debug flag is set, see the Debugging section for details.


Debugging & Testing


A deployment, especially small ones, can happen very rapidly, if for some reason the deployment time needs to be extended or  the deployment monitoring needs to be demonstrated a configurable delay can be introduced. The delay can be activated by adding the following to your log4j.properties file:

log4j.logger.alfresco.deployment.delay=debug

To test or demonstrate the deployment capabilities it's a lot easier to use the same instance of Alfresco rather than setting up another instance on the same machine and having to change port numbers or to have multiple machines especially for demos off site. To cater for this the entries localhost and 127.0.0.1 literally mean the same Alfresco instance.

Entering either of these in the 'Deploy To' field will cause the deployment to be directed into an AVM store with a name of the authoring web project's AVM Store Root/DNS name postfixed with 'live'. For example, say this is a web project with an AVM Store Root/DNS name of 'alfrescosite', the deployed site would end up in an AVM store called 'alfrescositelive'.

This store can then be browsed via CIFS or the same trick mentioned in the Deployed Runtime section can be used where a web project is created before the deployment is attempted. Using the example in the previous paragraph you would specify the web project's DNS name as 'alfrescositelive' in step 1 of the Create Web Project Wizard.

Outcomes