Moving to Confluence Data Center

This page outlines the process for migrating an existing Confluence Server (non-clustered) site to Confluence Data Center (clustered).

If you're installing Confluence for the first time (you don't have any existing Confluence data to migrate), see Installing Confluence Data Center

If you're wanting to switch back to a non-clustered solution, see Moving from Data Center to Server.

Your Confluence license determines the type of Confluence you have: Server or Data Center. Confluence will auto-detect the license type when you enter your license key, and automatically prompt you to begin the migration.

Not sure if you should upgrade from Confluence Server to Data Center? Learn more about the benefits of Confluence Data Center.

On this page:

Before you begin

Clustering requirements

To run Confluence in a cluster you must:

  • Have a Data Center license (you can purchase a Data Center license or create an evaluation license at my.atlassian.com)
  • Use a supported external database, operating system and Java version
  • Use a load balancer with session affinity and WebSockets support in front of the cluster
  • Have a shared directory accessible to all cluster nodes in the same path (this will be your shared home directory)
  • Use OAuth authentication if you have application links to other Atlassian products (such as JIRA)

Supported platforms

See our Supported Platforms page for information on the database, Java, and operating systems you'll be able to use. These requirements are the same for Server and Data Center deployments. See Confluence Data Center Technical Overview for important hardware and infrastructure considerations.

We also have specific guides and deployment templates to help you running Confluence Data Center in AWS or Azure. Check them out to find out what's required.

Terminology

In this guide we'll use the following terminology:

  • Installation directory – The directory where you installed Confluence on a node.
  • 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. 
  • Synchrony directory - The directory where you downloaded Synchrony (this can be on a confluence node, or on its own node)

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

Set up Data Center

1. Upgrade Confluence Server 

If you plan to upgrade Confluence as part of your migration to Data Center, you should upgrade your existing Confluence Server site as the first step.  

2. Apply Data Center license 

  1. Go to  > General Configuration > License Details
  2. Enter your new Confluence Data Center license key.
  3. You'll be prompted to stop Confluence to begin the migration.

 

At this stage your home directory (configured in confluence\WEB-INF\classes\confluence-init.properties) should still be pointing to your existing (local) home directory.

3. Create a shared home directory 

  1. Create a directory that's accessible to all cluster nodes via the same path. The directory should be empty. 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
  • The network interface Confluence will use to communicate between nodes
  • A multicast address (automatically generated or enter your own) or the IP addresses of each cluster node
  • How you want Confluence to discover cluster nodes:

    • Multicast - enter your own multicast address or automatically generate one.
    • TCP/IP - enter the IP address of each cluster node
    • AWS - enter your IAM Role or secret key, and region.
       

      AWS node discovery...

      We recommend using our Quick Start or Cloud Formation Template to deploy Confluence Data Center in AWS, as it will automatically provision, configure and connect everything you need.

      If you do decide to do your own custom deployment, you can provide the following information to allow Confluence to auto-discover cluster nodes:

      Field Description
      IAM Role or
      Secret Key
      This is your authentication method. You can choose to authenticate by IAM Role or Secret Key.
      Region This is the region your cluster nodes (EC2 instances) will be running in.
      Host header Optional. This is the AWS endpoint for Confluence to use (the address where the EC2 API can be found, for example 'ec2.amazonaws.com'). Leave blank to use the default endpoint.
      Security group name Optional. Use to narrow the members of your cluster to only resources in a particular security group (specified in the EC2 console).
      Tag key and Tag value

      Optional. Use to narrow the members of your cluster to only resources with particular tags (specified in the EC2 console).

Once you've confirmed that Confluence is running, stop Confluence so you can set up Synchrony (required if you want to continue to use collaborative editing).  

Set up Synchrony

5. Set up a Synchrony cluster

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. 

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  
    -classpath <PATH_TO_SYNCHRONY_STANDALONE_JAR>:<JDBC_DRIVER_PATH> 
     
    # To set the classpath in Windows 
    -classpath <PATH_TO_SYNCHRONY_STANDALONE_JAR>;<JDBC_DRIVER_PATH> 
     
    # 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
     
    # Remove this section if you don't need to discover nodes in AWS
    -Dsynchrony.cluster.impl=hazelcast-micros
    -Dcluster.join.type=aws
     
    -Dsynchrony.bind=<SERVER_IP> 
    -Dsynchrony.service.url=<SYNCHRONY_URL> 
    -Dsynchrony.database.url=<YOUR_DATABASE_URL> 
    -Dsynchrony.database.username=<DB_USERNAME> 
    -Dsynchrony.database.password=<DB_PASSWORD>  
     
    synchrony.core 
    sql

    (warning) 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.

    Values Required? Description
    <PATH_TO_SYNCHRONY_STANDALONE_JAR>
    Yes 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>
    Yes This is the path to your database driver. For example <synchrony-directory>/postgresql-9.2-1002.jdbc.jar.
    <TCPIP_ MEMBERS> Yes, if TCP/IP If you choose to discover nodes using TCP/IP, provide a comma separated list of IP addresses for each cluster node.
    <SERVER_IP>
    Yes 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> Yes This is the URL that the browser uses to contact Synchrony. Generally this will be the full URL of the load balancer Synchrony will run behind plus the Synchrony context path, for example http://yoursite.com:8091/synchrony. Note 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.
    <YOUR_DATABASE_URL>
    Yes 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>
    Yes The username and password for your Confluence database user. Sensitive information (like these 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 ("_"). 

    When you start Synchrony we also pass default values for a number of additional properties. You can choose to override these values by specifying these optional properties when you start Synchrony. See Configuring Synchrony for Data Center for more information.

    (warning) You can use this info to create your own script to run Synchrony, or follow the steps in this guided example to create a service script - Run Synchrony-standalone as a service on Linux.

     

  4. To check that Synchrony is accessible, you can 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. 

6. Start Confluence on Node 1

In this example, we assume you use the same load balancer for Synchrony and Confluence, as shown in Configuring Synchrony for Data Center.

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

    -Dsynchrony.service.url=http://<synchrony load balancer url>/synchrony/v1

    For example http://yoursite.example.com/synchrony/v1. You must include /v1 on the end of the URL.

    If Synchrony is set up as one node without a load balancer, use the following instead:

    -Dsynchrony.service.url=http://<synchrony ip or hostname>:<synchrony port>/synchrony/v1

    For example http://42.42.42.42:8091/synchrony/v1 or http://synchrony.example.com:8091/synchrony/v1

    You may want to add this system property to your <install-directory>/bin/setenv.sh 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.

Add more Confluence nodes

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

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

9. Start Confluence one node at a time

You must only start Confluence one node at a time. The first node must be up and available before starting the next one.

  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) shows 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.

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

If Confluence detects more than one instance accessing the database, but not in a working cluster, it will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity of the cluster.


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.

Last modified on Aug 15, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.