GraphAcademy
Course

Running Neo4j in Docker

Deploy Neo4j in Docker from the command line, then scale your deployment into a fault-tolerant cluster with three primaries and two secondaries.

55 minutes7 lessons across 1 module
Database AdministratorsIntermediate
About this lab

In this 55-minute lab, you will learn

Running Neo4j in Docker is a hands-on lab that takes you from a single Neo4j container to a fault-tolerant cluster in around 55 minutes. You will work entirely from the command line, starting one instance with Docker Compose, then growing your deployment into a five-member cluster of three primaries and two secondaries and operating it through the failure of a primary.

Running Neo4j on your own infrastructure starts with the same building blocks at every scale: an image, a set of ports, and a handful of configuration settings. A cluster adds the discovery, cluster, and Raft ports that let members find each other and reach agreement. This lab teaches both, and because clustering is where deployments most often go wrong, it makes you diagnose and fix a misconfigured cluster rather than only watching a healthy one.

  • Running Neo4j in Docker

    Start a container with the right image, ports, authentication, volumes, and the NEO4J_ environment-variable naming convention.

  • How a cluster forms

    Understand primaries, secondaries, Raft consensus, and the discovery, cluster, and Raft ports that let members find each other.

  • Allocating secondaries

    Diagnose secondaries that stay Free, bring them into service with ENABLE SERVER and ALTER DATABASE, and configure the secondaries count so they are allocated from the start.

  • Routing and fault tolerance

    See how reads and writes route across the cluster and watch it survive the loss of a primary.

Course content

1 module, 55 minutes.

  1. 7 lessons
    1. Running Neo4j in a Single Container7 min
    2. Start a Single Instance6 min
    3. How Clustering Works8 min
    4. Form a Cluster7 min
    5. Allocate the Secondaries8 min
    6. Routing, Roles, and Fault Tolerance6 min
    7. Inspect Topology and Survive a Failure6 min

  • Who this course is for

    This lab is for anyone who runs, or is about to run, Neo4j on self-managed infrastructure: administrators and DevOps engineers who want a practical introduction to the Neo4j Docker image and to how a cluster forms, routes queries, and survives failure; developers who want to understand what is happening underneath a production deployment; and architects who want to see fault tolerance demonstrated on a real cluster. You should be comfortable with Docker basics - containers, images, port mapping, volumes, and Docker Compose - and able to read and run the simple Full definition for Cypher (opens in a new tab)Neo4j's implementation of GQL, the ISO standard query language for graph databases. It is declarative: you describe the pattern to find, and the database decides how to find it. statements covered in Neo4j Fundamentals and Cypher Fundamentals. You do not need any prior experience with clustering; the lab introduces primaries, secondaries, and Raft consensus from first principles.

  • What you'll do

    You spend your time at a terminal, not reading theory. All of the work happens in a GitHub Codespace with Docker already available, so there is nothing to install locally; the lab repository provides the Docker Compose files. You will start a single Neo4j container from a Compose file, understand the image, the 7474 and 7687 port mappings, the NEO4J_AUTH setting, and the data volume, then connect with cypher-shell and prove the instance works.

    Then you will scale up. You will bring up a five-member cluster and inspect its topology with SHOW SERVERS and dbms.cluster.overview(). When the two secondaries stay in the Free state instead of hosting the database, you will diagnose why, enable them with ENABLE SERVER, and allocate them with ALTER DATABASE. Finally, you will watch how reads and writes route across the cluster, stop the leader, and confirm that the remaining primaries elect a new leader and keep accepting writes.

  • Where to go next

    If you connect applications to the deployment you now know how to run, the driver courses show you how, using cluster-aware neo4j:// connection URIs: Using Neo4j with Python, Java, Go, .NET, or TypeScript. If you would rather have Neo4j manage the cluster for you, Aura In Production covers running Neo4j Go to glossary for Aura (opens in a new tab)Neo4j's fully managed cloud service. in production. The lab also pairs well with the path toward the Neo4j Certified Professional certification.