7.2. Deploy a cluster

This section describes how to deploy a new Neo4j Causal Cluster.

This section includes:

7.2.1. Introduction

In this section we describe how to set up a new Causal Cluster consisting of three Core instances. We then proceed to show how more Core Servers as well as Read Replicas can be added to a running cluster.

Three Cores is the minimum number of servers needed in order to form a fault-tolerant Causal Cluster. See Section, “Core Servers” for a discussion on the number of servers required in various scenarios.

Refer to Section B.1, “Set up a local Causal Cluster” for a tutorial on how to set up a Causal Cluster on a local machine.

7.2.2. Configure a Core-only cluster

The following configuration settings are important to consider when deploying a new Causal Cluster. See also Section 7.7, “Settings reference” for more detailed descriptions and examples.

Table 7.1. Important settings for a new Causal Cluster
Option name Description


The address or network interface this machine uses to listen for incoming messages. Setting this value to makes Neo4j bind to all available network interfaces.


The address that other machines are told to connect to. In the typical case, this should be set to the fully qualified domain name or the IP address of this server.


The operating mode of a single server instance. For Causal Clustering, there are two possible modes: CORE or READ_REPLICA.


The minimum number of Core machines in the cluster at formation. A cluster will not form without the number of Cores defined by this setting, and this should in general be configured to the full and fixed amount.


The minimum number of Core instances which will exist in the consensus group.


The network addresses of an initial set of Core cluster members that are available to bootstrap this Core or Read Replica instance. In the default case, the initial discovery members are given as a comma-separated list of address/port pairs, and the default port for the discovery service is :5000. It is good practice to set this parameter to the same value on all Core Servers.

The behavior of this setting can be modified by configuring the setting causal_clustering.discovery_type. This is described in detail in Section 7.4, “Discovery”.

Listen configuration

Listening on makes the ports publicly available. Make sure you understand the security implications and strongly consider setting up encryption.

The following example shows how to set up a simple cluster with three Core servers:

Example 7.1. Configure a Core-only cluster

In this example, we will configure three Core Servers named core01.example.com, core02.example.com and core03.example.com. We have already installed Neo4j Enterprise Edition on all three servers. We configure them by preparing neo4j.conf on each server. Note that they are all identical, except for the configuration of dbms.default_advertised_address:

neo4j.conf on core01.example.com: 


neo4j.conf on core02.example.com: 


neo4j.conf on core03.example.com: 


Now we are ready to start the Neo4j servers. The startup order does not matter.

After the cluster has started, we can connect to any of the instances and run CALL dbms.cluster.overview() to check the status of the cluster. This will show information about each member of the cluster.

We now have a Neo4j Causal Cluster of three instances running.

Startup time

The instance may appear unavailable while it is joining the cluster. If you want to follow along with the startup, you can follow the messages in neo4j.log.

7.2.3. Add a Core Server to an existing cluster

Core Servers are added to an existing cluster by starting a new Neo4j instance with the appropriate configuration. The new server will join the existing cluster and become available once it has copied the data from its peers. It may take some time for the new instance to perform the copy if the existing cluster contains large amounts of data.

The setting causal_clustering.initial_discovery_members shall be updated on all the servers in the cluster to include the new server.

Example 7.2. Add a Core Server to an existing cluster

In this example, we will add a Core Server, core04.example.com, to the cluster that we created in Example 7.1, “Configure a Core-only cluster”.

We configure the following entries in neo4j.conf:

neo4j.conf on core04.example.com: 


Note that the configuration is very similar to that of the previous servers. In this example, the new server is not intended to be a permanent member of the cluster, thus it is not included in causal_clustering.discovery_members.

Now we can start the new Core Server and let it add itself to the existing cluster.

7.2.4. Add a Read Replica to an existing cluster

Initial Read Replica configuration is provided similarly to Core Servers via neo4j.conf. Since Read Replicas do not participate in cluster quorum decisions, their configuration is shorter; they only need to know the addresses of some of the Core Servers which they can bind to in order to discover the cluster. They can then choose an appropriate Core Server from which to copy data.

Example 7.3. Add a Read Replica to an existing cluster

In this example, we will add a Read Replica, replica01.example.com, to the cluster that we created in Example 7.1, “Configure a Core-only cluster”.

We configure the following entries in neo4j.conf:

neo4j.conf on replica01.example.com: 


Now we can start the new Read Replica and let it add itself to the existing cluster.