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 which you can download from here
  • Alfstream version 1.7.x or above
  • This Module (Alfstream Sync)

Install all 3 amps on both sides.

Karaf Setup

Installing Karaf for Alfstream

Note

You will need to run an instance Karaf on both sides for two way sync. If you only run one instance, then the sync will only work one-way

Follow these steps for each side:

  • Make sure you have downloaded the provided alfstream sync kar file to put into the deploy directory

  • Follow the instructions for installing Karaf 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
  • Add the provided kar file to the deploy directory.

Testing and Monitoring

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

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!" }'