Moving to Confluence Data Center

 

Below is the process for migrating from Confluence Server to Confluence Data Center, which is a clustered solution.

There's also a note on moving the other way, from Confluence Data Center to Server.

Your Confluence license will determine the type of Confluence you have: Server or Data Center. Confluence will auto-detect the license type when you enter your license key on the 'License Details' page in Confluence administration. If you've entered a different type of license, it'll automatically prompt you to begin the migration (from Confluence Server to Data Center, for example)

 

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

Moving from Server to Data Center

Clustering requirements and terminology

To run Confluence in a cluster, you must:

On this page:

  • Have a clustered license
  • Use an external database
  • Use a load balancer with session affinity in front of the cluster
  • Have a shared directory that's accessible by the same path to all cluster nodes (this will be your shared home directory)
  • Use OAuth authentication if you have application links to other Atlassian products (like JIRA applications). 

If you need a Confluence Data Center evaluation license, get in touch with us.  

In this guide we'll use the following terminology:
  • 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 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.6, 5.7 or 5.8 the process for upgrading is a little different.  Refer to our earlier documentation for more information. 

2. Apply your Data Center license 

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

  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.  

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

6. Test cluster connectivity

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


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

  1. Create a new document on node 1
  2. Ensure the new document is visible by accessing it directly on node 2
  3. Search for the new document on node 1, and ensure it appears
  4. Search for the new document on node 2, 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.

7. Configure load balancer

Install and configure your load balancer. You can use the load balancer of your choice, but it needs to support ‘cookie-based session affinity’.

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.

Security

Ensure that only permitted cluster nodes are allowed to connect to a Confluence Data Center instance's Hazelcast port, which by default is port 5801, 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.

Before you complete this process

As a precaution, we recommend shutting down all nodes except one, and running Confluence on a single node.

 

1. Enter your Confluence server license

Your home directory (configured in confluence\WEB-INF\classes\confluence-init.properties) should point to your local home directory.

  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.

To confirm you're now running the non-clustered edition, go to  > General Configuration. The 'Cluster Configuration' page should not appear. Instead you'll see information about Confluence Data Center.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport