There are several options for installing the Sync Service:
- Install manually using a distribution ZIP
- Install using Helm charts or Docker Compose (i.e. containerized deployment)
Note: It is recommended that you familiarize yourself with the concepts of containerized deployment before working with Docker, Kubernetes, and Helm.
Install with zip
Use these instructions to install the Sync Service repository modules and services on Alfresco Content Services.
The Sync Service distribution zip file, AlfrescoSyncServer-5.0.x.zip
, includes all the files required to provide the Sync Service. This file contains the following artifacts:
amps-repository
directory containing the Sync Service repository AMP:alfresco-device-sync-repo-5.0.x.amp
licenses
directory containing the 3rd-party licensesservice-sync
directory with:service-sync-5.0.x.jar
Sync Service JARconfig.yml
property filesyncservice
start/stop scriptsync.jks
SSL keys
Note: The keystore
sync.jks
contains a self-signed certificate that should be used for testing purposes only. You’ll need to provide your own SSL keys for a production environment.
Note: Make sure you’re running the correct versions of operating system and software before you install the AMP file. See Prerequisites for more information.
-
Download
AlfrescoSyncServer-5.0.x.zip
from Hyland Community. -
Extract the
AlfrescoSyncServer-5.0.x.zip
file into a system directory; for example,<installLocation>/
.We’ll refer to this new directory (
<installLocation>/sync
), as the Alfresco Sync Service installation directory. In this directory you’ll see these folders:amps-repository
licenses
service-sync
-
Stop the Alfresco repository.
-
Use the Module Management Tool (MMT) to install the
alfresco-device-sync-repo-5.0.x.amp
AMP into the repository WAR.For more information, see instructions in Install the AMP file.
For example, to apply the
alfresco-device-sync-repo-5.0.x.amp
, use the following command:java -jar <alfrescoInstallLocation>\bin\alfresco-mmt.jar install <installLocation>\amps-repository\alfresco-device-sync-repo-5.0.x.amp <installLocation>\tomcat\webapps\alfresco.war
-
Add the following properties to the
alfresco-global.properties
file:dsync.service.uris=https://<hostname>:9090/alfresco messaging.broker.url=failover:(tcp://localhost:61616)?timeout=3000
where:
dsync.service.uris
specifies the hostname of the Sync Service (or the load balancer hiding the Sync Service cluster) that Desktop Sync clients can see. For example,https://<hostname>:9090/alfresco
.- The
dsync.service.uris
value needs to be set to an IP address or hostname of the Sync Service machine that can be accessed by the Desktop Sync clients outside the firewall. In addition, the port 9090 needs to be opened up in the firewall so that clients can access the Sync Service. messaging.broker.url
specifies the location of ActiveMQ.
-
Configure the Sync Service properties in the
<installLocation>/service-sync/config.yml
file.For example, edit the following properties:
-
repo:
hostname: localhost
where
repo.hostname
is the IP address of the repository host. -
messaging:
broker: host: localhost
where
messaging.broker.host
is the IP address of the ActiveMQ host. -
sql:
db: url: jdbc:postgresql:alfresco
where
sql.db.url
is the URL of the Postgres database.
-
-
Start and configure PostgreSQL.
For more information, see Configuring PostgreSQL database for Desktop Sync.
-
Start ActiveMQ.
If ActiveMQ is down, the repository transactions will fail and rollback. In production environments, it’s advisable that you run an ActiveMQ cluster in failover mode to avoid this situation. See ActiveMQ master/slave configurations.
For more information, see Setting up ActiveMQ.
-
Start the repository.
Note: Wait for the repository to fully start before proceeding to the next step.
-
Start the Sync Service.
For Linux:
cd <installLocation>/service-sync java -Xmx2G -Djava.io.tmpdir=/var/tmp/dsync -classpath <classpath to database.jar file>:service-sync-5.0.x.jar org.alfresco.service.sync.dropwizard.SyncService server config.yml
See Running Sync Service via a script.
For Windows:
cd <installLocation>/service-sync java -Xmx2G -Djava.io.tmpdir=/users/<username>sync/tmp -classpath <classpath to database.jar file>;service-sync-5.0.x.jar org.alfresco.service.sync.dropwizard.SyncService server config.yml
Note: For production systems, you need to configure JMX authentication as password authentication over the Secure Sockets Layer (SSL) is enabled by default. However, in a test environment, you can disable all security, namely both password authentication and SSL, when you start the Java VM. See Connect to Sync Service through JMX for configuration options. For more information, see the JRE documentation.
Note: The PostgreSQL JDBC driver must be provided and included in the startup command line as shown above.
For more information, see Install and configure PostgreSQL database.
-
Access Alfresco Share by browsing to:
http://<hostname>:8080/share
-
Check the repository and Sync Service log file (
<installLocation>/service-sync/logs/sync-service.log
by default) to see if the Sync Service started properly. The location of the log file can be configured using thelogging
properties in theconfig.yml
file.To validate that the Sync Service is configured correctly, see Sync Service health check.
SSL certificate for the synchronization server
Alfresco supplies a self-signed certificate with the Sync Service. This certificate is for testing purposes only, and it’s not recommended for use in a production system.
How to disable SSL for the synchronization server
-
In the
applicationConnector
section of theconfig.yml
file, comment out or remove the lines fromtype: https
tovalidateCerts: false
.server: type: default applicationConnectors: - type: http port: 9090 # type: https # keyStorePath: ./sync.jks # keyStorePassword: N9SnIgrcAx7zWr # keyStoreType: JCEKS # validateCerts: false
-
For the
dsync.service.uris
property, replacehttps
withhttp
in the alfresco-global.properties file.For example,
dsync.service.uris=http://localhost:9090/alfresco
.
Install and configure databases
The Sync Service is not packaged with a database driver, so it will need to be downloaded separately and cited in the start-up.
See instructions to install and configure databases.
Containerized deployment
Sync Service can optionally be deployed as part of Alfresco Content Services using Helm charts or a Docker Compose file.
It is recommended that these deployment references are used as an accelerator by customers who have prior production experience with containerized deployment technologies like Docker, Kubernetes and Helm.
Follow these links to find out how to deploy Alfresco Content Services including the Sync Service using Helm charts or Docker Compose:
Due to the limited capabilities of Docker Compose, this deployment method is recommended for development and test environments only.
Uninstalling Sync Service
To remove the Sync Service, uninstall the Sync Service AMP file, remove the Sync Service installation, and then remove the ActiveMQ topic.
-
Stop the Alfresco server.
-
Uninstall the Sync Service, AMP file in the repository, for example using the Module Management Tool (MMT):
java -jar bin/alfresco-mmt.jar uninstall alfresco-device-sync-repo-5.0.x.amp tomcat/webapps/alfresco.war
Uninstall an AMP file provides information on how to uninstall the AMP file, and remove the AMP content from the WAR files.
-
Delete the Tomcat webapp directory.
For example, delete
tomcat/webapps/alfresco
.Deleting these directories forces Tomcat to read the edited WAR files when Alfresco is restarted.
-
Review the
autoStart
properties in youralfresco-global.properties
file to ensure that the events and messaging subsystems aren’t set to start automatically.Uninstalling the AMP file removes any settings applied by the Sync Service repository module, however you should review custom
autoStart
properties to check that they’re set tofalse
:events.subsystem.autoStart=false messaging.subsystem.autoStart=false
-
Ensure that all system services relating to the Sync Service are stopped, disabled or removed. Disable all cron jobs, and ensure there are no active Analytics processes on your server.
There are four system services to stop:
- ActiveMQ
- Event broker
- Messaging broker
- Sync Service
-
Ensure that Alfresco Content Services isn’t physically connected to the Sync Service installation and that all related functions are disabled.
You’ll physically remove all parts of the Sync Service installation, so you must make sure this doesn’t affect the Alfresco Content Services installation. Most Sync Service files are installed in
<installLocation>
, which you chose during installation (for example,<installLocation>/sync
). -
Remove the Sync Service installation and database.
Navigate to the Sync Service installation directory. Remove all Sync Service files by running the
rm -rf
command, or run this command from another directory:rm -rf /<installLocation>/sync
-
Using the ActiveMQ Console, remove the ActiveMQ topic and queues matching the following names:
Queue Consumer.*.alfresco.repo.event2 Topic alfresco.repo.event2