Purpose

Enabling Collaborative Editing is a high-impact change and it can cause issues if not planned correctly. 

Solution

In this guide, we will cover a few preparation steps that can help in the process and avoid some common problems. Please make sure to test this first on a staging instance before attempting it in production.

Cleanup

As a first step, you need to check if Collaborative Editing was enabled and used in the past. If you are not sure, run the following query:

select * from content 
where contenttype = 'PAGE' 
and content_status = 'draft';

If any result is returned, it means CE was indeed enabled in the past. That query finds Shared Drafts on the database, so it confirms the feature was used. In that scenario, its preferable to clean up that old content and start fresh as follows:

• How to remove all shared drafts and start with a clean state using Collaborative Editing

 It's also important to check the lastmoddate column for those entries before deleting them to confirm they are indeed old contents that should be removed. Generally speaking, this step is only needed if Collaborative Editing was used before version 7.5. After that version, shared drafts remain accessible even if CE is disabled, it just removes the ability to edit them as covered here.

Selecting a deployment option (Data Center only)

Since Confluence 6.12, Synchrony can be deployed in two modes on Data Center:

• Self-managed - Recommended
• Standalone

Although the Standalone mode offers more flexibility in terms of node count and location, it requires much more administrative effort. That is why we recommend using Standalone mode, more details here:

• Possible configurations for Confluence Data Center

Ports review

Since Synchrony is a separate JVM, it uses a few other ports, especially in Data Center. Before moving forward, ensure the following ports are open in the internal network:

• Confluence Server and Data Center ports

Reverse proxy or Load Balancer setup

If using Self-managed mode in DC or running Confluence Server, there is an entity called synchrony-proxy used to forward requests to Synchrony. In order to reduce latency and improve the editor performance, we recommend setting up a direct connection to Synchrony, bypassing this internal proxy, and ensuring WebSockets are allowed.

Another advantage of this setup is to isolate both processes. That is because the synchrony-proxy threads run on the same JVM as Confluence, meaning it can interfere with the main process. More details here:

• Direct to Synchrony with a reverse proxy or load balancer

Although it only mentions the server deployment, the same can be achieved in Data Center self-managed mode by configuring up the Load Balancer to communicate directly to Synchrony. Here you can find a list of documents about this setup:

Final checks

To avoid a few common issues, check the following items before moving forward:

Cluster interface

If running Data Center in clustered mode, make sure the following property is present in <Confluence-home>/confluence.cfg.xml and set to the correct network interface. You can double-check with the ifconfig command:

 <property name="confluence.cluster.interface">eth0</property>

Java and JNA temporary directory

To avoid the problem covered in this KB, edit the file <confluence-local-home>/synchrony-args.properties and set the java.io.tmpdir property to use the temp folder from the installation directory, as follows:

java.io.tmpdir=<CONFLUENCE-INSTALL>/temp

A similar problem can happen for the JNA library files as covered here. To avoid it, also set the jna.tmpdir to the same location, but this time on the Confluence system properties (setenv file):

CATALINA_OPTS="-Djna.tmpdir=<CONFLUENCE-INSTALL>/temp ${CATALINA_OPTS}"

Memory allocation

Lastly, for production, we recommend setting the following property on <Confluence-Install>/bin/setenv.sh:

CATALINA_OPTS="-Dsynchrony.memory.max=4g ${CATALINA_OPTS}"

The default memory allocation for Synchrony is 2g, which might not be enough. For large-scale instances, we recommend setting the Synchrony heap between 4 to 8g. Make sure there is enough physical memory available on the server. We don't recommend allocating more than 50% of the total memory in heap space (Confluence and Synchrony combined).

With all those steps completed and tested in staging, enabling Collaborative Editing in production should be a smooth operation. We still recommend scheduling a maintenance window since it triggers several background tasks to complete it. Reach out to Atlassian Support if you need any clarification on those recommendations.