Installing Confluence Data Center
In this guide we'll run you through installing Confluence Data Center, which is a clustered solution, in a Windows or Linux Environment.
This guide covers installing for the first time, with no existing data. If you already have a Confluence Server instance, see Moving to Confluence Data Center.
Other ways to install Confluence Data Center:
- AWS Quick Start - hassle free deployment in AWS
- Move to Data Center - for existing Confluence Server sites
On this page:
Clustering requirements and terminology
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)
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.
1. Install Confluence on the first node
- Install Confluence on node 1
See Installing Confluence on Windows from Zip File or Installing Confluence on Linux from Archive File for more information. - Start Confluence on Node 1
- Complete the setup wizard by entering:
- Your cluster license
- 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
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.
- Stop Confluence on Node 1
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.
- Create a Synchrony directory on your first node and copy
synchrony-standalone.jar
from your Confluence<home-directory
> to this directory. - Copy your database driver from your Confluence
<install-directory>/confluence/web-inf/lib
to an appropriate location on your Synchrony node. 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.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.
- To check that Synchrony is accessible, you can go to:
http:
//<SERVER_IP>:<SYNCHRONY_PORT>
/synchrony/heartbeat
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 }
- 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
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://<LOAD_BALANCER_URL>:<PORT>/synchrony/v1
For example
http://yoursite.com:8091/synchrony/v1
. You must include/v1
on the end of the URL.
You may want to add this system property to your<install-directory>/bin/setenv.sh
orsetenv.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.- 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:
- Shut down Confluence on node 1
- Shut down your application server on node 2, or stop it automatically loading web applications
- Copy the installation directory from node 1 to node 2
- 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.
- Start Confluence on node 1
- Wait for Confluence to become available on node 1
- Start Confluence on node 2
- 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:
- Access a node via your load balancer, and create a new document on this node
- Ensure the new document is visible by accessing it directly on a different node
- Search for the new document on the original node, and ensure it appears
- 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.
Upgrading a cluster
It's important that upgrades follow the procedure for Upgrading Confluence Data Center.