Installation options

There are several options for installing the Sync Service:

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,, 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-3.4.x.amp
  • licenses directory containing the 3rd-party licenses
  • service-sync directory with:
    • service-sync-3.4.x.jar Sync Service JAR
    • config.yml property file
    • syncservice start/stop script
    • sync.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.

  1. Download from the Alfresco Support Portal.

  2. Extract the 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
  3. Stop the Alfresco repository.

  4. Use the Module Management Tool (MMT) to install the alfresco-device-sync-repo-3.4.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-3.4.x.amp, use the following command:

     java -jar <alfrescoInstallLocation>\bin\alfresco-mmt.jar install <installLocation>\amps-repository\alfresco-device-sync-repo-3.4.x.amp <installLocation>\tomcat\webapps\alfresco.war
  5. Add the following properties to the file:



    • 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.
    • specifies the location of ActiveMQ.
  6. Configure the Sync Service properties in the <installLocation>/service-sync/config.yml file.

    See Configure Sync Service.

    For example, edit the following properties:

    • repo:

        hostname: localhost

      where repo.hostname is the IP address of the repository host.

    • messaging:

            host: localhost

      where is the IP address of the ActiveMQ host.

    • sql:

            url: jdbc:postgresql:alfresco

      where sql.db.url is the URL of the Postgres database.

  7. Start and configure PostgreSQL.

    For more information, see Configuring PostgreSQL database for Desktop Sync.

  8. 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.

  9. Start the repository.

    Note: Wait for the repository to fully start before proceeding to the next step.

  10. Start the Sync Service.

    For Linux:

    cd <installLocation>/service-sync
    java -Xmx2G -classpath <classpath to database.jar file>:service-sync-3.4.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<username>sync/tmp -classpath <classpath to database.jar file>;service-sync-3.4.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.

  11. Access Alfresco Share by browsing to:

  12. 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 the logging properties in the config.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

  1. In the applicationConnector section of the config.yml file, comment out or remove the lines from type: https to validateCerts: false.

         type: default
             - type: http
               port: 9090
             # type: https
             # keyStorePath: ./sync.jks
             # keyStorePassword: N9SnIgrcAx7zWr
             # keyStoreType: JCEKS
             # validateCerts: false
  2. For the dsync.service.uris property, replace https with http in the 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.

These instructions apply to both Alfresco Content Services and Alfresco One.

  1. Stop the Alfresco server.

  2. 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-3.4.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.

  3. 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.

  4. Review the autoStart properties in your 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 to false:

  5. 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
  6. 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).

  7. 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
  8. Using the ActiveMQ Console, remove the ActiveMQ topic and queues matching the following names:

     Queue Consumer.*

Edit this page

Suggest an edit on GitHub
This website uses cookies in order to offer you the most relevant information. Please accept cookies for optimal performance. This documentation is subject to the Alfresco documentation terms.