Parashift Alfstream Sync Module

The Alfstream Sync module is an extension to Alfstream that allows site-to-site synchronisation of Alfresco between two instances (or more).

Alfstream Sync is targeted for users of Alfresco Share and Share's Collaboration sites.

Features

The following features are added based on the existing alfstream module:

  • Two actions are added, which are Begin Syncing and Stop from Syncing.
  • Only Users within the ALFSTREAM_SYNC group are allowed to run these actions
  • Synchronise site specific data such as: Dashboards, Wikis & Discussions
  • Synchronise site folders and files
  • Synchronise 'My files'
  • Synchronise user Groups
  • If there is a failure to synchronise between instances due to environmental reasons, site managers are notified via email. Users can retry syncing by:
    • Setting up automatic retries, as per below
    • Manually selecting Retry Syncing from Share

Changelog

The change log for Alfstream Sync can be found here

Usage

While the behaviours are managed by aspects, there are two actions available depending on the current state of the node to make it easy for users to select which nodes to bring under sync

Setup

You will need a user to be part of the ALFSTREAM_SYNC group:

  • Create the ALFSTREAM_SYNC group if it doesn't exist
  • Add a user into that group

Bringing a Node Under Sync

  • Navigate to The Document Library to a folder you want synced.
  • Select the Begin Syncing action
  • This will add the alfs:sync aspect to the folder and all children

begin_syncing.png

Removing a Node from Sync

  • Navigate to a folder that has the alfs:sync Aspect applied
  • Select the Stop from Syncing action
  • This will change the alfs:syncState property to Inactive

stop_from_syncing.png

Retry Sync on a Node

Manually Retry Sync on a Node

  • Navigate to a folder that has the sync error message banner displayed
  • Select the Retry Syncing action
  • This will clear the error status and trigger a resync

Scheduled Auto Retry Sync on All Eligible Nodes

If you want to automatically retry sync in case of a failure, then you can enable the following options

  • Add alfstream.sync.autoretry.enabled=true in alfresco-global.properties to enable scheduler
  • Add alfstream.sync.autoretry.cronExpression in alfresco-global.properties to change the default retry period (every 15 mins), this property won't work if scheduler is disabled

Installation and Setup

Please follow the below steps to install the amps and setup the environment

Alfresco Setup

You will need to install the following modules:

  • Alfresco Dynamic Extensions 1.4.2 +
  • Alfstream version 1.7.x or above
  • This Module (Alfstream Sync)

Install all 3 amps on both sides.

Alfresco Full Site Sync Configuration

If you need to synchronise entire sites, we need to let Share know to update its cache whenever there has been a change to the site configuration (dashboards, themes, etc..)

Repo Configuration

The site synchronisation is controlled by the following properties:

alfstream.sync.shareurl=http://localhost:8080/share
alfstream.sync.sharetoken=ParashiftRocks!

These properties are set as a default and ordinarily do not need to be changed.

  • alfstream.sync.shareurl: This is the Share URL which will receive cache updates from Alfresco. defaults to http://localhost:8080/share
  • alfstream.sync.sharetoken: This is the Token that allows Alfresco to talk to Share securely, and is checked by Share when a request to invalidate the cache is made. defaults to ParashiftRocks!
Share Configuration

If you want to change the token for whatever reason, this needs to match in Alfresco Share.

You can adjust the token by adding the following snippet to share-config-custom.xml:

<config evaluator="string-compare" condition="ClearCache">
    <token>ParashiftRocks!</token>
</config>
Testing Configuration

You can test that Share is ready to accept cache update requests by submitting a JSON POST to the page/caches/clearcachepath url:

curl --request POST \
  --url http://localhost:8080/share/page/caches/clearcachepath \
  --header 'content-type: application/json' \
  --data '{ "path": "alfresco/site-data/pages/site/test-sync-full-site/dashboard.xml", "token": "ParashiftRocks!" }'

Karaf Setup

Installing Karaf for Alfstream

With the node aspects in Alfresco, we construct a two-way camel route which will:

  • Listen for changes to any nodes with the alfs:sync aspect
  • Filter out any nodes with the sync state of Not Synced
  • Change the alfs_syncState from Inactive to Not Synced
  • Capture any exception thrown during the node sync process and update the node with error message

You will need to follow this step on both sides:

  • Follow the instructions for installing Karaf/Alfstream from here: alfstream

  • Create a or update the config file at /opt/apache-karaf-{version}/etc/com.parashift.cfg with the following properties:

  • alfstream.local.url: the Local alfresco instance (normally localhost, but could be a different server)

  • alfstream.local.username: the Local alfresco admin username
  • alfstream.local.password: the Local alfresco admin password
  • alfstream.remote.url: the Remote alfresco instance
  • alfstream.remote.username: the Remote alfresco admin username
  • alfstream.remote.password: the Remote alfresco admin password
  • alfstream.sync.persist.file: the file used to store the last sync status

As an example:

alfstream.remote.url=http://sidea.dev.parashift.local:8080/alfresco
alfstream.remote.username=admin
alfstream.remote.password=admin
alfstream.local.url=http://localhost:8080/alfresco
alfstream.local.username=admin
alfstream.local.password=admin
alfstream.sync.persist.file=persist/alfstream-sync

Since 1.2.2, we provide default values in alfstream-sync-blueprint.xml for local alfstream configurations and persist file as shown below:

alfstream.local.url=http://localhost:8080/alfresco alfstream.local.username=admin alfstream.local.password=admin alfstream.sync.persist.file=persist/alfstream-sync You only need to provide remote related alfstream configurations if the default values work for you.

  • Since 1.2.2 you can create a KAR Bundle:
  • Download or navigate to where you have stored the alfstream module
  • Run gradle publishToMavenLocal to publish the artifact
  • In the camel directory of alfstream-sync, run gradle generateKar

  • Copy the generated KAR archive to the deploy directory of karaf, the example path like /opt/apache-karaf-{version}/deploy.

Testing and Monitoring

Follow the steps here to enable debug logging for com.parashift: alfstream