Set up a local Causal Cluster

Introduction

In this tutorial, you will learn how to deploy a Causal Cluster locally on a single machine.

Keep in mind that a cluster on a single machine has no fault tolerance and is therefore not suitable for production use.

A typical Causal Cluster consists of three Core instances and three Read Replicas. The Core instances are responsible for keeping the data safe, and the Read Replicas are responsible for scaling the capacity of the cluster. For details on the number of servers required for a Causal Cluster, see Core Servers.

The Core of the Causal Cluster is intended to remain stable over time. The roles within the Core may change as needed, but the Core itself is long-lived and stable.
Read Replicas live at the edge of the cluster and can be brought up and taken down without affecting the Core. They can be added as needed to increase the operational capacity of the cluster as a whole.

For more information about Causal Clustering architecture, configuration, and operation, see Clustering.

Download Neo4j

You download Neo4j and prepare your local environment.

  1. Create a local working directory.

  2. Download a copy of the Neo4j Enterprise Edition from the Neo4j download site.

  3. Unpack Neo4j in the working directory.

Set up the Core servers

You create and configure three Core instances.

Configure and start the first Core instance

You create and configure the first Core instance.

  1. Make a copy of the neo4j-enterprise-4.1.12 directory and name it core-01.
    You have to keep the original directory for setting up the other Core instances and Read Replicas. The core-01 directory will contain the first Core instance.

  2. Open the Neo4j configuration file, conf/neo4j.conf, and configure the following settings:

    If you cannot find the configuration file, see File locations.

    1. Locate and uncomment the setting dbms.mode=CORE.

    2. Locate and uncomment the setting causal_clustering.minimum_core_cluster_size_at_formation=3.

    3. Locate and uncomment the setting causal_clustering.minimum_core_cluster_size_at_runtime=3.

    4. Locate and uncomment the setting causal_clustering.initial_discovery_members=localhost:5000,localhost:5001,localhost:5002.

    5. Locate and uncomment the setting causal_clustering.discovery_listen_address=:5000.

    6. Locate and uncomment the setting causal_clustering.transaction_listen_address=:6000.

    7. Locate and uncomment the setting causal_clustering.raft_listen_address=:7000.

    8. Locate and uncomment the setting dbms.connector.bolt.listen_address=:7687.

    9. Locate and uncomment the setting dbms.connector.http.listen_address=:7474.

    10. Locate and uncomment the setting dbms.connector.https.listen_address, and change the value to :6474.

    11. Locate and uncomment the setting dbms.backup.listen_address=0.0.0.0:6362.

  3. Save the file.

  4. Open a command-line tool and navigate to core-01 directory.

  5. Run the following command to start core-01:

    core-01$ ./bin/neo4j start

Create and configure the second Core instance

You create and configure the second Core instance.

  1. Make a new copy of the neo4j-enterprise-4.1.12 directory and name it core-02.

  2. Overwrite core-02/conf/neo4j.conf with the just modified core-01/conf/neo4j.conf. Then in the new core-02 directory, open the conf/neo4j.conf file and configure the following settings:

    1. Locate the setting causal_clustering.discovery_listen_address and change the value to :5001.

    2. Locate the setting causal_clustering.transaction_listen_address and change the value to :6001.

    3. Locate the setting causal_clustering.raft_listen_address and change the value to :7001.

    4. Locate the setting dbms.connector.bolt.listen_address and change the value to :7688.

    5. Locate the setting dbms.connector.http.listen_address and change the value to :7475.

    6. Locate the setting dbms.connector.https.listen_address and change the value to :6475.

    7. Locate the setting dbms.backup.listen_address and change the value to 0.0.0.0:6363.

  3. Save the file.

  4. Open a command-line tool and navigate to core-02 directory.

  5. Run the following command to start core-02:

    core-02$ ./bin/neo4j start

Create and configure the third Core instance

You create and configure the third Core instance.

  1. Make a new copy of the neo4j-enterprise-4.1.12 directory and name it core-03.

  2. Overwrite core-03/conf/neo4j.conf with the just modified core-02/conf/neo4j.conf. Then in the new core-03 directory, open the conf/neo4j.conf file and configure the following settings:

    1. Locate the setting causal_clustering.discovery_listen_address and change the value to :5002.

    2. Locate the setting causal_clustering.transaction_listen_address and change the value to :6002.

    3. Locate the setting causal_clustering.raft_listen_address and change the value to :7002.

    4. Locate the setting dbms.connector.bolt.listen_address and change the value to :7689.

    5. Locate the setting dbms.connector.http.listen_address and change the value to :7476.

    6. Locate the setting dbms.connector.https.listen_address and change the value to :6476.

    7. Locate the setting dbms.backup.listen_address and change the value to 0.0.0.0:6364.

  3. Save the file.

  4. Open a command-line tool and navigate to core-03 directory.

  5. Run the following command to start core-03:

    core-03$ ./bin/neo4j start
Startup Time

To follow along with the startup of a server, check the messages in <instance-home>/logs/neo4j.log:

  • On a Unix system, run the command tail -n100 logs/neo4j.log.

  • On Windows Server, run Get-Content .\logs\neo4j.log -Tail 10 -Wait.

While an instance is joining the cluster, the server may appear unavailable. In the case where an instance is joining a cluster with lots of data, it may take a number of minutes for the new instance to download the data from the cluster and become available.

Check the status of the cluster

The minimal cluster of three Core servers is operational and is ready to serve requests.

Connect to any of the three Core instances to check the cluster status.

  1. Open core-01 at http://localhost:7474.

  2. Authenticate with the default neo4j/neo4j credentials, and set a new password when prompted.

  3. Check the status of the cluster by running the following in Neo4j Browser:

    :sysinfo
    Example 1. A cluster of three Core instances.
    Name Address Role Status Default Error

    neo4j

    localhost:7689

    follower

    online

    true

    -

    neo4j

    localhost:7688

    follower

    online

    true

    -

    neo4j

    localhost:7687

    leader

    online

    true

    -

    system

    localhost:7689

    follower

    online

    -

    -

    system

    localhost:7688

    follower

    online

    -

    -

    system

    localhost:7687

    leader`

    online

    -

    -

  4. Run the following query to create nodes and relationships.

    UNWIND range(0, 100) AS value
MERGE (person1:Person {id: value})
MERGE (person2:Person {id: toInteger(100.0 * rand())})
MERGE (person1)-[:FRIENDS]->(person2)

  5. Open a new tab and point your web browser to a follower, for example, core-02 at http://localhost:7475.

  6. Authenticate with the credentials you have set up for core-01.

  7. Run the following query to verify that the data has been replicated:

    MATCH path = (person:Person)-[:FRIENDS]-(friend)
RETURN path
LIMIT 10

Set up the Read Replicas

Because the Read Replicas do not participate in quorum decisions, their configuration is simpler than the configuration of the Core servers.

You configure a Read Replica by setting the address of a Core instance that it can bind to in order to discover the cluster. For details, see Discovery protocol.
After the initial discovery, the Read Replicas can choose a Core instance from which to catch up. For details, see Catchup protocol.

Configure and start the first Read Replica

You create and configure the first Read Replica.

  1. Make a copy of the neo4j-enterprise-4.1.12 directory and name it replica-01.

  2. In the new replica-01 directory, open the conf/neo4j.conf file and configure the following settings:

    1. Locate and uncomment the setting dbms.mode, and change the value to READ_REPLICA.

    2. Locate and uncomment the setting causal_clustering.initial_discovery_members=localhost:5000,localhost:5001,localhost:5002.

    3. Locate and uncomment the setting causal_clustering.discovery_listen_address, and change the value to :5003.

    4. Locate and uncomment the setting causal_clustering.transaction_listen_address, and change the value to :6003.

    5. Locate and uncomment the setting dbms.connector.bolt.listen_address, and change the value to :7690.

    6. Locate and uncomment the setting dbms.connector.http.listen_address, and change the value to :7477.

    7. Locate and uncomment the setting dbms.connector.https.listen_address, and change the value to :6477.

    8. Locate and uncomment the setting dbms.backup.listen_address, and change the values to 0.0.0.0:6365.

  3. Save the file.

  4. Open a command-line tool and navigate to replica-01 directory.

  5. Run the following command to start replica-01:

    replica-01$ ./bin/neo4j start

Configure and start the second Read Replica

You create and configure the second Read Replica.

  1. Make a new copy of the neo4j-enterprise-4.1.12 directory and name it replica-02.

  2. Overwrite replica-02/conf/neo4j.conf with the just modified replica-01/conf/neo4j.conf. Then in the new replica-02 directory, open the conf/neo4j.conf file and configure the following settings:

    1. Locate the setting causal_clustering.discovery_listen_address and change the value to :5004.

    2. Locate the setting causal_clustering.transaction_listen_address and change the value to :6004.

    3. Locate the setting dbms.connector.bolt.listen_address and change the value to :7691.

    4. Locate the setting dbms.connector.http.listen_address and change the value to :7478.

    5. Locate the setting dbms.connector.https.listen_address and change the value to :6478.

    6. Locate the setting dbms.backup.listen_address and change the value to 0.0.0.0:6366.

  3. Save the file.

  4. Open a command-line tool and navigate to replica-02 directory.

  5. Run the following command to start replica-02:

    replica-02$ ./bin/neo4j start

Configure and start the third Read Replica

You create and configure the third Read Replica.

  1. Make a new copy of the neo4j-enterprise-4.1.12 directory and name it replica-03.

  2. Overwrite replica-03/conf/neo4j.conf with the just modified replica-02/conf/neo4j.conf. Then in the new replica-03 directory, open the conf/neo4j.conf file and configure the following settings:

    1. Locate the setting causal_clustering.discovery_listen_address and change the value to :5005.

    2. Locate the setting causal_clustering.transaction_listen_address and change the value to :6005.

    3. Locate the setting dbms.connector.bolt.listen_address and change the value to :7692.

    4. Locate the setting dbms.connector.http.listen_address and change the value to :7479.

    5. Locate the setting dbms.connector.https.listen_address and change the value to :6479.

    6. Locate the setting dbms.backup.listen_address and change the value to 0.0.0.0:6367.

  3. Save the file.

  4. Open a command-line tool and navigate to replica-03 directory.

  5. Run the following command to start replica-03:

    replica-03$ ./bin/neo4j start

Check the status of the cluster

Your cluster of three Core servers and three Read Replicas is operational and is ready to serve requests.

In your core-01 browser, check the cluster status by running the following in Neo4j Browser:

:sysinfo
Example 2. A cluster of three Core instances and three Read Replicas.
Name Address Role Status Default Error

neo4j

localhost:7689

follower

online

true

-

neo4j

localhost:7688

follower

online

true

-

neo4j

localhost:7687

leader

online

true

-

neo4j

localhost:7692

read_replica

online

true

-

neo4j

localhost:7691

read_replica

online

true

-

neo4j

localhost:76890

read_replica

online

true

-

system

localhost:7689

follower

online

-

-

system

localhost:7688

follower

online

-

-

system

localhost:7687

leader

online

-

-

system

localhost:7692

read_replica

online

-

-

system

localhost:7691

read_replica

online

-

-

system

localhost:7690

read_replica

online

-

-

  1. Open a new tab and point your web browser to a Read Replica, for example, replica-01 at http://localhost:7477.

  2. Login with neo4j and the previously set password and use the bolt:// schema.

  3. Run the following query to verify that the data has been replicated:

    MATCH path = (person:Person)-[:FRIENDS]-(friend)
RETURN path
LIMIT 10