• installation directory – The directory where Confluence is installed.
• local home directory – The home or data directory on each node (in non-clustered Confluence this is simply known as the home directory).
• shared home directory – The directory you created that is accessible to all nodes in the cluster via the same path.

At the end of the installation process you'll have an installation directory and local home directory on each node, and a single shared home directory (for example, in a two node cluster you'd have a total of 5 directories). 

1. Upgrade Confluence Server 

If you're switching to Confluence Data Center 5.9 or later follow the normal procedure for backing up and upgrading Confluence first. See upgrading Confluence for information on upgrading and choosing the best upgrade path.

If you're switching to Confluence Data Center 5.8 the process for upgrading is a little different.  Refer to our earlier documentation for more information. 

2. Apply your Data Center license 

1. Go to  > General administration.
2. Choose License Details from the sidebar under the Administration heading.
3. Enter your Confluence Data Center license key.
4. Shut down Confluence.

3. Create a shared home directory 

1. Create a directory that's accessible to all cluster nodes via the same path. This will be your shared home directory. 
2. In your existing Confluence home directory, move the contents of <confluence home>/shared-home to the new shared home directory you just created.
   To prevent confusion, we recommend deleting the empty <confluence home>/shared-home directory once you've moved its contents.
3. Move your attachments directory to the new shared home directory (skip this step if you currently store attachments in the database). 

4. Start Confluence

The setup wizard will prompt you to complete the migration, by entering:

• A name for your cluster
• The path to the shared home directory you created earlier
• A multicast address (automatically generated or enter your own) or the IP addresses of each cluster node
• The network interface Confluence will use to communicate between nodes

Your first node is now up and running.  

2. Set up Synchrony

Collaborative editing requires Synchrony, which runs as a separate process. You can deploy Synchrony on the same nodes as Confluence, or in its own cluster with as many nodes as you need.  You'll need to complete step one (including entering your Data Center license) before you start this step.

In this example, we assume you'll run Synchrony in its own cluster. When configuring your cluster nodes you can either supply the IP address of each Synchrony cluster node, or a multicast address.

1. Create a Synchrony directory on your first node and copy synchrony-standalone.jar from your Confluence <home-directory> to this directory. 
2. Copy your database driver from your Confluence <install-directory>/confluence/web-inf/lib to an appropriate location on your Synchrony node.

3. Change to your Synchrony directory and start Synchrony using the following command.
   You need to pass all of the system properties listed, replacing the values where indicated.
   
   

   Start Synchrony command...

   In a terminal / command prompt, execute the following command, replacing <values> with appropriate values for your environment. Scroll down for more information on each of the values you will need to replace.
    

   java 
   -Xss2048k 
   -Xmx2g 
    
   # To set the classpath in Linux based operating systems
   -classpath <PATH_TO_SYNCHRONY_STANDALONE_JAR>:<JDBC_DRIVER_PATH> 
    
   # To set the classpath in Windows operating systems
   -classpath <PATH_TO_SYNCHRONY_STANDALONE_JAR>;<JDBC_DRIVER_PATH> 
    
   -Dsynchrony.cluster.impl=hazelcast-btf 
   -Dsynchrony.port=<SYNCHRONY_PORT> 
   -Dcluster.listen.port=<CLUSTER_LISTEN_PORT>
   -Dsynchrony.cluster.base.port=<CLUSTER_BASE_PORT>
    
   # Remove this section if you don't want to discover nodes using TCP/IP
   -Dcluster.join.type=tcpip 
   -Dcluster.join.tcpip.members=<TCPIP_MEMBERS> 
    
   # Remove this section if you don't want to discover nodes using multicast
   -Dcluster.join.type=multicast
   -Dcluster.join.multicast.group=<MULTICAST_GROUP> 
   -Dcluster.join.multicast.port=54327 
   -Dcluster.join.multicast.ttl=32 
    
   -Dsynchrony.context.path=/synchrony 
   -Dsynchrony.cluster.bind=<SERVER_IP> 
   -Dsynchrony.bind=<SERVER_IP> 
   -Dcluster.interfaces=<SERVER_IP>
   -Dsynchrony.service.url=<SYNCHRONY_URL> 
   -Djwt.private.key=<JWT_PRIVATE_KEY> 
   -Djwt.public.key=<JWT_PUBLIC_KEY>
   -Dsynchrony.database.url=<YOUR_DATABASE_URL> 
   -Dsynchrony.database.username=<DB_USERNAME> 
   -Dsynchrony.database.password=<DB_PASSWORD>  
   
   # The following properties must be passed, but their values do not matter
   -Dip.whitelist=127.0.0.1,localhost
   -Dauth.tokens=dummy 
   -Dopenid.return.uri=http://example.com 
   -Ddynamo.events.table.name=5 
   -Ddynamo.snapshots.table.name=5
   -Ddynamo.secrets.table.name=5 
   -Ddynamo.limits.table.name=5 
   -Ddynamo.events.app.read.provisioned.default=5 
   -Ddynamo.events.app.write.provisioned.default=5 
   -Ddynamo.snapshots.app.read.provisioned.default=5 
   -Ddynamo.snapshots.app.write.provisioned.default=5 
   -Ddynamo.max.item.size=5 
   -Ds3.synchrony.bucket.name=5 
   -Ds3.synchrony.bucket.path=5 
   -Ds3.synchrony.eviction.bucket.name=5 
   -Ds3.synchrony.eviction.bucket.path=5 
   -Ds3.app.write.provisioned.default=100
   -Ds3.app.read.provisioned.default=100
   -Dstatsd.host=localhost 
   -Dstatsd.port=8125 
   synchrony.core 
   sql

   Remember to remove all commented lines completley before you execute this command, and replace all new lines with white space. You may also need to change the name of the synchrony-standalone.jar if the file you copied is different to our example.

   Here's more information about each of the values you'll need to supply in the command above.

   Value	Description
   <SYNCHRONY_PORT>	This is the HTTP port that Synchrony runs on. We suggest port 8091, if available.
   <CLUSTER_LISTEN_PORT>	This is Synchrony's Hazelcast port. We suggest port 5701, if available. As with Confluence's Hazelcast port (5801) you should ensure that only permitted cluster nodes are allowed to connect to this port, through the use of a firewall and or network segregation.
   <CLUSTER_BASE_PORT>	This is the Aleph binding port. Synchrony uses Aleph  to communicate between nodes. We suggest port 25500, if available.
   <TCPIP_ MEMBERS>	If you choose to discover nodes using TCP/IP, provide a comma separated list of IP addresses for each cluster node.
   <MULTICAST_GROUP>	If you chose to discover nodes using multicast, specify an IP address for the multicast group.
   <SERVER_IP>	This is the public IP address or hostname of this Synchrony node. It could also be a private IP address - it should be configured to the address where Synchrony is reachable by the other nodes.
   <SYNCHRONY_URL>	This is the URL that the browser uses to contact Synchrony. Generally this will be the URL for your load balancer plus the Synchrony context path, for example http://yoursite.com/synchrony
   <JWT_PRIVATE_KEY> <JWT_PUBLIC_KEY>	These keys are generated by Confluence. Copy each key from the <local-home>/confluence.cfg.xml file on your first Confluence node. The keys must be the same on all Confluence and Synchrony nodes.
   <YOUR_DATABASE_URL>	This is the URL for your Confluence database. For example jdbc:postgresql://localhost:5432/confluence. You can find this URL in <local-home>/confluence.cfg.xml.
   <DB_USERNAME> <DB_PASSWORD>	The username and password for your Confluence database user.
   <PATH_TO_SYNCHRONY_STANDALONE_JAR>	This is the path to the synchrony_standalone.jar that you copied in step 1. For example <synchrony-directory>/synchrony_standalone.jar
   <JDBC_DRIVER_PATH>	This is the path to your database driver. For example <synchrony-directory>/postgresql-9.2-1002.jdbc.jar.
   <YOUR_LOAD_BALANCER>	This is the full URL of the load balancer Synchrony will run behind, for example, http://<lb_host>:<lb_port><lb_context_path>. For example, if your loadbalancer path is synchrony, then it will be http://hostname:80/synchrony. Notice that it does not end with /v1, unlike the synchrony.service.url system property passed to Confluence. If this URL doesn't match the URL coming from a users' browser, Synchrony will fail.

   Sensitive information (like database credentials) may be provided using environmental variables, rather than via the command line. Any dots (".") in variable names (identifiers) will need to be replaced with underscores ("_"). 

   A few other properties can be modified to suit your environment. See Configuring Synchrony for Data Center for more information.

4. To check that Synchrony is accessible, go to:
   http://<SERVER_IP>:<SYNCHRONY_PORT>/synchrony/heartbeat

5. Repeat this process to start Synchrony on each node of your Synchrony cluster.
   As each node joins you'll see something like this in your console.

   Members [2] {
   	Member [172.22.52.12]:5701
   	Member [172.22.49.34]:5701 
   }
   

6. Configure your load balancer for Synchrony.
   Your load balancer must support WebSockets (for example NGINX 1.3 or later, Apache httpd 2.4, IIS 8.0 or later) and session affinity. SSL connections must be terminated at your load balancer so that Synchrony can accept XHR requests from the web browser. 

3. Start Confluence on Node 1

1. Start Confluence on node 1 and pass the following system property to tell Confluence where to find your Synchrony cluster.

   -Dsynchrony.service.url=http://<YOUR_LOAD_BALANCER>:<LOAD_BALANCER_PORT>/synchrony/v1

   You may want to add this system property to your <install-directory>/bin/setenv.bin or setenv.bat so it is automatically passed every time you start Confluence. See Configuring System Properties for more information on how to do this in your environment.

2. Head to  > General Configuration > Collaborative editing to check that this Confluence node can connect to Synchrony. 
   
   Note: to test creating content you'll need to access Confluence via your load balancer.  You can't create or edit pages when accessing a node directly.

4. Copy Confluence to second node

To copy Confluence to the second node:

1. Shut down Confluence on node 1
2. Shut down your application server on node 2, or stop it automatically loading web applications
3. Copy the installation directory from node 1 to node 2
4. Copy the local home directory from node 1 to node 2
   If the file path of the local home directory is not the same on nodes 1 and 2 you'll need to update the <installation directory>/confluence/WEB-INF/classes/confluence-init.properties file on node 2 to point to the correct location.

Copying the local home directory ensures the Confluence search index, the database and cluster configuration, and any other settings are copied to node 2.

5. Configure load balancer

Configure your load balancer for Confluence. You can use the load balancer of your choice, but it needs to support session affinity and WebSockets.

SSL connections must be terminated at your load balancer so that Synchrony can accept XHR requests from the web browser.

You can verify that your load balancer is sending requests correctly to your existing Confluence server by accessing Confluence through the load balancer and creating a page, then checking that this page can be viewed/edited by another machine through the load balancer.

6. Start Confluence on the first node, wait, then start Confluence on second node

You must only start Confluence one server at a time.

1. Start Confluence on node 1
2. Wait for Confluence to become available on node 1
3. Start Confluence on node 2
4. Wait for Confluence to become available on node 2.

The Cluster monitoring console ( > General Configuration > Clustering) includes information about the active cluster.

When the cluster is running properly, this page displays the details of each node, including system usage and uptime. Use the menu to see more information about each node in the cluster.

Screenshot: Cluster monitoring console

7. Test your Confluence cluster

Remember, to test creating content you'll need to access Confluence via your load balancer.  You can't create or edit pages when accessing a node directly.

A simple process to ensure your cluster is working correctly is:

1. Access a node via your load balancer, and create a new document on this node
2. Ensure the new document is visible by accessing it directly on a different node
3. Search for the new document on the original node, and ensure it appears
4. Search for the new document on another node, and ensure it appears

Security

Ensure that only permitted cluster nodes are allowed to connect to a Confluence Data Center instance's Hazelcast port (which defaults to 5801) or Synchrony's Hazelcast port (which defaults to 5701) through the use of a firewall and or network segregation.

Troubleshooting

If you have problems with the above procedure, please see our Cluster Troubleshooting guide.

If you're testing Confluence Data Center by running the cluster on a single machine, please refer to our developer instructions on Starting a Confluence cluster on a single machine.

Moving from Data Center to Server

If you need to move from Data Center (clustered) to Server (non-clustered), read on. In these instructions we'll assume that you'll use one of your existing cluster nodes as your new, non-clustered installation. 

You'll need a Confluence Server license to switch back to Server.

1. Enter your Confluence server license

1. Go to  > General administration
2. Choose License Details from the sidebar under the Administration heading
3. Enter your Confluence Server license key

2. Shut down Confluence

Stop any cluster nodes that are still running before proceeding. We also recommend configuring your load balancer to redirect traffic away from Confluence.

3. Move items in the cluster shared home back to local home

1. Create a directory called /shared-home in the <local home> directory on one node (if you removed this directory when installing Data Center)
2. Move the entire config directory from your <shared home> directory to the <local home>/shared-home directory
3. Move the remaining contents of your <shared home> directory to the root of your <local home> directory

Your cluster's shared home directory should now be empty. 

4. Start Confluence

The setup wizard will guide you through the migration process.