Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
Back to WCM Developer Documentation
This page highlights the capabilities of the WCM Deployment functionality in the 2.2 and 3.0 releases.
Deployment features prior to 2.2.
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 registry port (50500 by default) and RMI service port accessible.
The File System Receiver (FSR) allows a web project to be deployed to a remote file server, typically a web or application server.
This feature was originally added in the 2.1 release and enhanced and extended in the 2.2 and 3.0 releases.
It consists of a small server that receives updates from an alfresco repository and publishes them to a flat file system which is then typically served up by a web or application server. For performance reasons only differences between the old version and the new version are sent.
The file system receiver also supports a postCommit event which is executed after a successful deployment. Using this feature it is possible to run bespoke commands after deployment. A sample adapter is provided to run an operating system command after a successful deployment.
The destination file server receiver has to be running with its RMI registry port and service port (44100 and 44101 by default) accessible.
The code for the FSR is contained within the Deployment project within the Alfresco SVN repository.
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 below:
As can be seen in the screenshot above the only required data is the Host. All other fields can be left empty so that the defaults will then be used. The defaults 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.
During deployment each file name is compared to the Excludes pattern. If the file name matches the pattern then the file is excluded from deployment. Regular expressions can be somewhat cryptic but are powerful.
The path given to the matcher is the Store Reference for example
test20text:/www/avm_webapps/ROOT/myapp/dir1/index.htm
where 'test20text' is the WCM project name and 'myapp/dir1/index.htm' is an file in the project.
Here are some examples
.*\.jpg$|.*\.gif$
:exclude any files ending with .jpg OR .gif
[A-Za-z0-9:/_]*ROOT/myapp/dir1/*
:exclude all files within the dir1 folder of my project
When deploying to a deployment server running on a multi-NIC system it may be necessary to bind the RMI registry to a particular IP address. To do this you must add the following to the java command in deploy_start.sh/.bat<tt>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 virtualization server allows some webapps to be previewed before deployment but not all. For example, it is perfectly acceptable to author a .NET based website in Alfresco but a virtualized .NET environment is unlikely to be achieved. Furthermore, a virtualized 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 is 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.
Further information on the preview options supported by Alfresco WCM is available at WCM Preview.
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 the Deploy Website window shown below. Each configured live server will be presented with a checkbox.
Click OK to start the deployment process. The Deploy Website window will close and open the Monitor Deployment window. This window 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 as shown below. 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 window can be closed at any time during the deployment, however, the window can not be returned to (this will be rectified in a future release). To monitor progress if the Monitor Deployment window is closed, open the snapshot list in the staging area and monitor the status column, an IN PROGRESS message will be shown 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, in both cases the procedure and UI is exactly the same.
In a user sandbox open the More Actions menu and click the Deploy icon (shown in the screenshot in the previous section) and for the review sandbox click the Deploy icon in the Resources panel header.
Clicking the Deploy icon will open the Deploy Website window shown below in the 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 window will open and proceed as explained in the previous section.
If there are no unallocated test servers available the window will show the following message:
Once a test server has been allocated to, click the Deploy icon to show the Deploy Changes window, as shown in the screenshot below. This confirms which server is allocated to the sandbox before deployment.
Deploy-test-server-changes.jpg
Wherever a deployment is executed, 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.
Click the View Deployments icon to launch the Last Deployment Report window , 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, that is, 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 four 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.
Click on an attempt date to launch the Deployment Report window, where you can view the deployment reports for the selected attempt, as shown in the screenshot below.
To return quickly to the last deployment report, click the View Last Deployment Report icon that appears in the header of the expanded panel.
ASR 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, that is, Z:\ or a mount point, that is, /mnt/alfresco and then used to serve the website via Apache or the webserver of your choice.
Alternatively, to browse or virtualize 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.
FSR Runtime
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 window 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 Include In Auto Deploy option enabled.
As this all happens in the background on the server there is no Deployment Monitor window in this scenario. However, as with any manual deployment from the staging sandbox the Last Deployment Report window and the status column can be used to monitor the progress and overall result.
There are two ways to clean out old unrequired deployment reports:
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 you click OK, 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.
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'>
...
<property name='maxAge'>
<value>180</value>
</property>
...
</bean>
<bean id='avmDeploymentAttemptCleanup' class='org.alfresco.util.CronTriggerBean'>
...
<property name='cronExpression'>
<value>0 0 4 * * ?</value>
</property>
</bean>
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.
<property name='wcmwf:autoDeploy'>
<title>Auto Deploy</title>
<description>Determines whether the changes should be deployed upon submission</description>
<type>d:boolean</type>
</property>
Deploy Website Dialog
The Deploy Website window 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 window 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.
AVMDeployWebsiteAction
2.2 replaces the old AVMDeploySnapshotAction with the new AVMDeployWebsiteAction repository action.
The AVMDeployWebsiteAction 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,
getParamDisplayLabel(PARAM_WEBPROJECT)));
paramList.add(new ParameterDefinitionImpl(PARAM_SERVER, DataTypeDefinition.NODE_REF, true,
getParamDisplayLabel(PARAM_SERVER)));
paramList.add(new ParameterDefinitionImpl(PARAM_ATTEMPT, DataTypeDefinition.NODE_REF, false,
getParamDisplayLabel(PARAM_ATTEMPT)));
paramList.add(new ParameterDefinitionImpl(PARAM_CALLBACK, DataTypeDefinition.ANY, false,
getParamDisplayLabel(PARAM_CALLBACK)));
The parameters are explained below:
The default values for the remote username/password, port numbers, and so on, 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.
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 callbacks A list of callbacks.
*/
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,
List<DeploymentCallback> callbacks);
/**
* 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,
String dstTarget,
NameMatcher matcher,
boolean createDst,
boolean dontDelete,
boolean dontDo,
List<DeploymentCallback> callbacks);
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.
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);
}
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.
Monitor Dialog
When the user clicks OK in the Deploy Snapshot window, several events 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 window is opened. This window uses the same JSF component as the 'Deploy Snapshot' window, UIDeployWebsite. This time however, it is passed the list of deployment monitor ids from AVMBrowseBean and its 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 two 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 is 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] 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'] />
</deployment-progess>
There is a target-server element for each server selected by the user. The attributes are explained below:
The client side of the UIDeployWebsite component takes the response and updates each server progress area as appropriate.
Deployment Report
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.
Workflow
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:
<task-node name='submitted'>
<event type='node-enter'>
...
<action class='org.alfresco.repo.avm.wf.AVMDeployHandler'/>
</event>
...
</task-node>
...
<event type='process-end'>
...
<action class='org.alfresco.repo.avm.wf.AVMReleaseTestServerHandler'/>
...
</event>
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 window) 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.
Scripting
Being an action, AVMDeployWebsiteAction can still be called from a JavaScript, in fact it is now easier as there are a lot less mandatory parameters to satisfy. However, one of the new mandatory parameters is the deploymentattempt node used to store the deploymentreport nodes. An instance of a deploymentattempt needs to be created and populated before calling the action. Furthermore, if several servers are being deployed to as part of the same operation the same attempt instance should be passed to each action execution.
Client
The only configurable aspect of the deployment UI is the polling frequency for the Progress window. This is done via the web client configuration mechanism and as such can be overridden using the extension mechanism. The file web-client-config-wcm.xml contains the default value as shown below:
<deployment>
<progress-polling-frequency>2</progress-polling-frequency>
</deployment>
Action
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'>
...
<property name='defaultRemoteUsername'>
<value>admin</value>
</property>
<property name='defaultRemotePassword'>
<value>admin</value>
</property>
<property name='defaultAlfrescoRmiPort'>
<value>50500</value>
</property>
<property name='defaultReceiverRmiPort'>
<value>44100</value>
</property>
<property name='defaultTargetName'>
<value>default</value>
</property>
<property name='delay'>
<value>30</value>
</property>
<property name='callbacks'>
<list>
<ref bean='org.alfresco.sample.DeploymentCallback1' />
<ref bean='org.alfresco.sample.DeploymentCallback2' />
</list>
</property>
</bean>
The properties are explained as follows:
Data
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
...
...Applied patch
ID: patch.deploymentMigration
RESULT:
Deployment data has been migrated.=========================
Workflow
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:
log4j.logger.alfresco.deployment.delay=debug
To test or demonstrate the deployment capabilities, it is 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.
<math>Insert formula here</math>
Ask for and offer help to other Alfresco Content Services Users and members of the Alfresco team.
Related links:
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.