The official documentation is at: http://docs.alfresco.com
This page highlights the capabilities of the WCM Deployment functionality in the 2.2 release. For information on the deployment features prior to 2.2 click here.
The main features of the deployment are listed below, the following sections explain each one in more detail.
The Alfresco Server Receiver (ASR) 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 port (50500 by default) accessible.
The File System Receiver (FSR) allows a web project to be deployed to a remote file server, this feature was originally added in the 2.1 release.
The destination file server has to be running the FSR with its RMI port (44100 by default) accessible.
The Create and Edit Web Project wizards now have an extra step allowing multiple receivers to be configured. The single 'Deploy To' field in the previous releases has been replaced with a form for each server allowing the following information to be entered:
Each of these items is explained as follows:
As seen in the previous image, the only required data above is the 'Host', all other fields can be left empty, the defaults will then be used, these can be seen in the Configuration section below. When the details have been entered the server is added to the list of other configured servers as shown below.
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:
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
The virtualisation server allows some webapps to be previewed before deployment but not all. For example, it's perfectly acceptable to author a .NET based website in Alfresco but a 'virtualised' .NET environment is unlikely to be achieved. Furthermore, a virtualised environment hardly ever represents the eventual 'live' configuration.
For these reasons the ability to deploy to a test environment has been added in the 2.2 release. It's now possible for a developer to deploy the state of their sandbox to a test server and preview their site. Similarly, reviewers in a workflow can deploy and preview the change set they are approving (or rejecting).
Once a test server has been deployed to it is allocated to the user or workflow that performed the deploy. Once the user or workflow has finished with the test server it is 'released' and returned to the pool of test servers. This happens automatically in the case of a workflow sandbox and manually via a UI action for user sandboxes.
Deployments from the staging sandbox are deployed to live servers and behave in the same way as in previous releases, see the next section for details on performing both types of deployment.
Once the destination servers have been specified a deployment can be initiated and monitored.
Deploying to a live server
To start a deployment to a live server open the list of snapshots in the staging sandbox and click on the deploy action icon shown in the screenshot below.
This will open following the 'Deploy Website' dialog. Each configured live server will be presented with a checkbox.
Click OK to start the deployment process. The Deploy Website dialog closes 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.
Once the deployment completes, the state is updated. When a URL has been configured this will appear under the 'Deployment Successful' message to allow instant previewing of the deployed site. If an error occurs the reason for the error is shown under the 'Deployment Failed' message.
The dialog can be closed at any time during the deployment. However, you cannot return to it (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' is displayed if one or more deployment processes are executing.
Deploying to a test server
Deployments to test servers can be performed from two different places, a user sandbox and a review sandbox. However, the procedure and UI are exactly the same for both.
In a user sandbox, open the More Actions menu and click the Deploy icon and for the review sandbox, click the Deploy icon in the Resources panel header. This opens the Deploy Website dialog shown in the following screenshot. All the unallocated test servers will be displayed.
Choose a test server to use (currently only one test server can be allocated to a sandbox at a time) and click OK. This will allocate the test server to the current sandbox and deploy the contents of the sandbox. The 'Monitor Deployment' dialog will open and proceed as explained in the previous section.
If there are no unallocated test servers available the dialog will show the following message:
Once a test server has been allocated to clicking the Deploy icon will show the 'Deploy Changes' dialog as shown in the screenshot below. This simply confirms which server is allocated to the sandbox before deployment.
No matter where a deployment is executed from, the result is a set of deployment reports. These can be accessed from the 'View Deployments' icon, shown in the screenshot below. For the staging sandbox the icon appears in the top right of the panel, for the user sandbox the icon appears in the 'More Actions' menu and for review sandboxes the icon appears in the header of the Resources panel.
When the 'View Deployments' icon is clicked the 'Last Deployment Report' dialog is launched as shown in the screenshot below.
A deployment report is shown for the servers deployed to in the last deployment attempt. The screenshot above shows one successful report and one failed report. The expandable Details area either shows what happened in the deployment when it was successful or error details in the case of a failed deployment.
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.
If the 'View Deployments' icon is clicked before any deployment reports have been generated the message in the screenshot below will be shown. As reports are generated they will appear here.
For the staging sandbox only a status column displays the deployment status for the last snapshot deployed.
There are 4 possible values:
Clicking the 'View Deployment' link while the status is 'IN PROGRESS' will result in the behaviour detailed above.
A new feature in 2.2 is the 'More Deployment Reports' panel, when expanded it shows all previous deployment attempts ordered by the date of the attempt. The results can be filtered by 'Today', 'Yesterday', 'Last 7 Days', 'Last 30 Days' and 'All'. Use the 'All' filter with caution though, this could return a LOT of results and therefore take a long time to render the page.
Clicking on an attempt date will launch the 'Deployment Report' dialog to view the deployment reports for the selected attempt as shown in the screenshot below.
The last deployment report can be returned to quickly via the 'View Last Deployment Report' icon that appears in the header of the expanded panel.
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.
The result of a deployment to a file server is dependent upon the settings of the deployment receiver on the remote machine and the configuration of the selected deployment server.
By default the entire folder structure of the selected website will be transferred to the remote machine. However, using the configuration options for the server and the receiver fine grained control can be achieved of what gets deployed and where to.
As mentioned already in this page, when a deployment is performed from a user or review sandbox the selected test server gets allocated to the sandbox.
The administrator or content manager can see what test server is allocated to which sandbox by going to the edit website wizard and viewing the 'Allocated' field. Hovering over the 'Yes' label will reveal the actual store name as a tooltip.
Test servers allocated to user sandboxes can be 'released' by the owner of the sandbox, the administrator or the content manager. The 'Release Server' icon is available in the 'More Actions' menu.
Test servers allocated to review sandboxes are automatically released by the system upon completion of the workflow.
A common request is to have the staging area automatically deploy when a set of changes is approved, this is now supported in 2.2.
The submit dialog now has an 'Auto Deploy' checkbox as shown in the screenshot below.
Upon approval, if the auto deploy option is on, the workflow will perform a deployment to those live servers that have the 'Inclue In Auto Deploy' option turned on.
As this all happens in the background on the server there is no deployment monitor dialog in this scenario. However, as with any manual deployment from the staging sandbox the 'Last Deployment Report' dialog and the status column can be used to monitor the progress and overall result.
There are 2 ways to clean out old unrequired deployment reports, selectively (based on age) by a scheduled job or a total clean via the UI.
Administrators and content managers have the 'Delete All Deployment Reports' icon available to them in the 'Actions' menu for a staging sandbox. Clicking the icon will display a confirmation page, if OK is clicked ALL deployment reports for the whole web project will be deleted.
If a complete clean is too extravagant a scheduled job can be setup to clean all reports over a configurable age. The job is provided as a sample file called 'deployment-attempt-cleaner-context.xml.sample'. As with any sample extension remove the '.sample' suffix and place the file in the <tomcat>/shared/classes/alfresco/extension folder. For details on configuring the job refer to the Configuration section towards the end of this page.
The following sections provide details on the implementation of the deployment functionality.
The WCM application model has been extended in the 2.2 release to support multiple deployment servers and to store historical deployment reports.
A graphical representation of the deployment model is shown in the diagram below.
As can be seen in the diagram above the properties added to wca:webfolder in the 2.0.1 release have been deprecated as has the 'wca:deploymentreport'child association. To see the full definition of the deployment model take a look at the file named 'wcmAppModel.xml'.
The other model updated for deployment is the WCM workflow model ('wcmWorkflowModel.xml'). A new property exists to indicate whether an automatic deployment should be performed once a change set has been approved according to the rules of the workflow. The property definition is shown below.
<description>Determines whether the changes should be deployed upon submission</description>
Deploy Website Dialog
The deploy website dialog operates in several modes. It uses the UIDeployWebsite JSF component to display the list of live servers when a deploy operation is being performed in the staging sandbox, a list of test servers when deploying to a user or review sandbox for the first time and the allocated test server when changes from a user or review sandbox are being deployed.
Once the user makes and confirms their selection the dialog implementation (DeployWebsiteDialog) creates a 'deploymentattempt' node as a child of the 'webfolder' node representing the web project.
The attempt node and a callback object (DeploymentMonitor) are then passed to an asynchronously executed AVMDeployWebsiteAction instance (one for each server selected).
The DeploymentMonitor object and UIDeployWebsite component is used to display the progress of each server being deployed to.
2.2 replaces the old AVMDeploySnapshotAction with the new AVMDeployWebiteAction repository action.
The AVMDeploySnapshotAction takes two mandatory parameters and a couple of optional ones. The parameter definition is shown below:
public static final String PARAM_WEBPROJECT = 'webproject';
public static final String PARAM_SERVER = 'server';
public static final String PARAM_ATTEMPT = 'attempt';
public static final String PARAM_CALLBACK = 'callback';
paramList.add(new ParameterDefinitionImpl(PARAM_WEBPROJECT, DataTypeDefinition.NODE_REF, true,
paramList.add(new ParameterDefinitionImpl(PARAM_SERVER, DataTypeDefinition.NODE_REF, true,
paramList.add(new ParameterDefinitionImpl(PARAM_ATTEMPT, DataTypeDefinition.NODE_REF, false,
paramList.add(new ParameterDefinitionImpl(PARAM_CALLBACK, DataTypeDefinition.ANY, false,
The parameters are explained below:
The default values for the remote username/password, port numbers etc. are Spring configured, for details see the configuration section. The default values are used unless the provided 'deploymentserver' node has overridden them.
The AVMDeployWebsiteAction action marshals all the provided data into the parameters required to call the repository DeploymentService. When the deployment completes the action creates, populates and persists a 'deploymentreport' node as a child of the provided 'deploymentattempt' node.
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 callbacks A list of callbacks.
public DeploymentReport deployDifference(int version, String srcPath,
String hostName, int port,
String userName, String password,
* 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 callbacks A list of callbacks.
public DeploymentReport deployDifferenceFS(int version, String srcPath,
String hostName, int port,
String userName, String password,
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. This takes the form of a regular expression.
The 'callbacks' parameter allows a list of DeploymentCallback implementations to listen to the deployment. All events that occur during the deployment process, including errors, are sent to the callback objects.
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.
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);
Six types of event can be received as shown by the following enum definition:
public static enum Type implements Serializable
COPIED, // Copied a source node that did not exist on the destination.
UPDATED, // Overwrote the destination.
DELETED, // Deleted the destination node.
START, // A Deployment has begun.
END, // A Deployment has ended.
FAILED // A Deployment failed.
Each event also provides the source path, destination path and an optional message. The message is currently only used by the FAILED event so send the error message that caused the failure.
In releases prior to 2.2 only one DeploymentCallback object could be passed to the DeploymentService and this was hard-coded to be the DeploymentMonitor object used by the UI. A list of callback objects can now be passed all of which will get called back appropriately. To see how to pass custom callback implementations to the DeploymentService see the configuration section.
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):
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:
<target-server id='xxx' name='host[:port] or display name' server='NodeRef of server node'
attempt='NodeRef of attempt node' finished='true|false'
[successful='true|false'] [url='server url'] [reason='error message'] />
There is a 'target-server' element for each server selected by the user. The attrbiutes are explained below:
The client side of the UIDeployWebsite component takes the response and updates each server progress area as appropriate.
Once a deployment operations completes, whether successful or not, the AVMDeployWebsiteAction implementation creates a 'deploymentreport' object as a child association of the 'deploymentattempt' node passed to the action as a parameter.
The 'deploymentreport' node holds a copy of all the relevant data from the 'deploymentserver' node passed to the action. Doing this keeps the report completely separate from the server configuration meaning the server configuration can be changed in isolation and the deployment audit trail remains intact.
To support the auto deployment at the end of a submission workflow a new handler has been added to the 'node-enter' event
on the 'submitted' task and to support the release of any allocated test server a new handler has been added to the 'process-end' event. This is shown in the snippet from submit_processdefinition.xml below:
AVMDeployHandler is called once the change set has been approved. If the 'autoDeploy' process instance variable is set to true (the user selected the checkbox in the submit dialog) the handler creates a 'deploymentattempt' node and then an instance of AVMDeployWebsiteAction for each live server configured to be included in any automatic deployments.
It determines the list of servers by querying for 'live' servers from the web project with their 'deployonapproval' property set to 'true'.
The only configurable aspect of the deployment UI is the polling frequency for the progress dialog, this is done via the web client configuration mechanism and as such can be overridden using the extension mechanism. web-client-config-wcm.xml contains the default value as shown below:
Default values for calling the DeploymentService are configured in Spring meaning they can be overridden using the standard repository configuration mechanism or via an AMP.
<bean id='avm-deploy-website' class='org.alfresco.repo.avm.actions.AVMDeployWebsiteAction' parent='action-executer'>
<ref bean='org.alfresco.sample.DeploymentCallback1' />
<ref bean='org.alfresco.sample.DeploymentCallback2' />
The properties are explained below:
Attempt Cleaner Job
A sample scheduled job is provided that when enabled will purge any old 'deploymentattempt' nodes. By default the job will purge any nodes older than 180 days at 4am every morning as shown below.
<bean id='avmDeploymentAttemptCleaner' class='org.alfresco.repo.avm.AVMDeploymentAttemptCleaner'>
<bean id='avmDeploymentAttemptCleanup' class='org.alfresco.util.CronTriggerBean'>
<value>0 0 4 * * ?</value>
For more information on scheduled jobs and in particular how to use cron expressions see the Scheduled_Actions page.
As the model has changed from 2.1 to 2.2 a patch has been implemented to migrate the deployment data from previous releases to the structure required for the 2.2 model.
The patch creates a new 'deploymentserver' for each entry in the old 'deployto' field. The old 'selecteddeployto' and 'selecteddeployversion' fields (if set) are migrated to a new 'deploymentattempt' node and any 'deploymentreport' nodes moved as a child of the new 'deploymentattempt' node.
The patch will output messages similar to the following:
.. INFO [PatchExecuter] Applying patch 'patch.deploymentMigration' (patch.deploymentMigration.description).
.. INFO [..DeploymentMigrationPatch] Migrating deployment data for web project: File Server Deployment
.. INFO [..DeploymentMigrationPatch] Server '\\localhost' from web project 'File Server Deployment' has been migrated
.. INFO [..DeploymentMigrationPatch] Deployment report for '__localhost deployment report.txt' from web project
'File Server Deployment' has been migrated
Deployment data has been migrated.
The submit_processdefinition.xml file was changed to support automatic deployment, a patch has also been implemented to ensure the new definition gets deployed.
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:
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 'Host' field of an ASR and leaving the 'Port' field empty 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.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.
Ask for and offer help to other Alfresco Content Services Users and members of the Alfresco team.