Commit 59ffa024 authored by peter's avatar peter

Include alfstream sync

parent ea562beb
# 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
* 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](../changelogs/alfstream-sync.md)
## 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](../images/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](../images/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`:
```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](alfstream.md)
* 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
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
```
* Add the camel route blueprint to the `deploy` directory: [alfstream-sync-blueprint.xml](../examples/alfstream-sync-blueprint.xml)
#### Testing and Monitoring
Follow the steps here to enable debug logging for `com.parashift`: [alfstream](alfstream.md#monitoring-karaf)
# AlfStream Module
This module provides an Apache Camel component and an Alfresco Repository component
This module provides an Apache Camel component and an Alfresco Repository component.
## Changelog
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment