Goals You will learn how to create and run a Neo4j graph database in a Docker container. This tutorial is designed for you to follow along and step through the process. Prerequisites This guide builds upon the basic concepts discussed… Read more →
You will learn how to create and run a Neo4j graph database in a Docker container. This tutorial is designed for you to follow along and step through the process.
This guide builds upon the basic concepts discussed in earlier guides and some knowledge of Docker. To better understand and utilize Neo4j with Docker, it helps to know the following:
You should also have downloaded Docker for your appropriate operating system and be familiar with navigating it from the command line.
There is an official Neo4j image on DockerHub we can use to give us a standard, ready-to-run package of Neo4j. From the DockerHub repo, we can run Community Edition or Enterprise Edition with a variety of versions of the database. The list from Neo4j’s options in dockerhub is shown below.
To determine which image we want, we need to piece together a few options.
neo4j tag starts each image name.
After that, the version is preceded with a colon like the
We will choose to pull the latest version of the image because we want to get all the latest features.
For community, the latest version is specified with
The Enterprise Edition has a
You need to have a valid commercial license in order to use the Enterprise Edition. Using an enterprise Docker image will require you to accept the official Enterprise license agreement.
The Neo4j Docker image includes some basic configuration defaults that should not need adjustment for most cases. However, if interested, the full list of default configurations for Neo4j in Docker can be found on the GitHub repository.
By default, the Docker image exposes three ports for remote access:
- 7474 for HTTP
- 7473 for HTTPS
- 7687 for Bolt
We will use these ports to connect to Neo4j inside the container, accessing it from Neo4j Browser, an application, or other methods.
It is also possible to create a custom Docker image with Neo4j included, but we will not cover that here.
Retrieving and running Neo4j within a Docker container is very simple using one of the provided images.
We will need to execute the basic
docker run command with the
neo4j image and specify any options or versions we want along with that.
Let us take a look at a few options available with the
docker run command.
Name your container (avoids generic id)
Specify container ports to expose
Detach container to run in background
Bind mount a volume
Set config as environment variables for Neo4j database
Output full list of docker run options
By default, Neo4j requires authentication and requires us to first login with
Let us go ahead and create our Neo4j container by running the command below. An explanation of each option is in the following paragraphs.
docker run simply creates and starts a container.
On the next line,
--name testneo4j defines the name we want to use for the container as
This avoids us having to reference the container by its generic id, making our container easier to reference and to remember.
-p option with ports 7474 and 7687 allows us to expose and listen for traffic on both the HTTP and Bolt ports.
Having the HTTP port means we can connect to our database with Neo4j Browser, and the Bolt port means efficient and type-safe communication requests between other layers and the database.
Next, we have
This detaches the container to run in the background, meaning we can access the container separately and see into all of its processes.
The next several lines start with the
These lines define volumes we want to bind in our local directory structure so we can access certain files locally.
The first one is for our
/datadirectory, which stores the authentication and roles for each database, as well as the actual data contents of each database instance (in
-voption is for the
/logsdirectory. Outputting the Neo4j logs to a place outside the container ensures we can troubleshoot any errors in Neo4j, even if the container crashes.
The third line with the
-voption binds the import directory, so we can copy CSV or other flat files into that directory for importing into Neo4j. Load scripts for importing that data can also be placed in this folder for us to execute.
-voption line sets up our plugins directory. If we want to include any custom extensions or add the Neo4j APOC or graph algorithms library, exposing this directory simplifies the process of copying the jars for Neo4j to access.
On the next line with the
--env parameter, we initiate our Neo4j instance with a username and password.
Neo4j automatically sets up basic authentication with the
neo4j username as a foundation for security.
Since it will initiate authentication and require a password change when first connecting, we can handle all of that in this parameter.
Finally, the last line of the command above references the Docker image we want to pull from DockerHub (
neo4j), as well as any specified version (in this case, just the
When we run this command, it will create and start the container.
We can see this because it generates a container id like in the image below.
Even though it creates a container id, you can reference the container using the
name we set up in the command –
Once we execute the command above, Neo4j should be running in our Docker container!
You can verify this by running
If you do not see your container in the list when you run
The above image shows the results of the
docker ps command, showing the container id, image:version, command, created duration, current status, exposed ports, and the container name.
Since the container is currently running, we can stop the container (without destroying it) using the
docker stop testneo4j command.
To start it again, we can simply execute
docker start testneo4j.
Output of both those commands is shown in the image below.
We have added
docker ps commands in between the start and stop, so we can see the status of the container before and after each command.
If we did not create the container properly, and we want to start over, we will need to destroy the container before executing the docker run again with the same container name. Running the same run command that we did above will notify us that we cannot create another container with the same name as an existing container. This is shown in the output below.
In order to avoid this, we can destroy the old container first using the
docker rm testneo4j command.
Once we run this, we can use the same docker run command from earlier to create our container again.
Once you are comfortable with creating, starting, and stopping the Docker container, you can start exploring other Neo4j functionality. Much of the other typical Neo4j processes for importing data, adding plugins, and interacting via Neo4j Browser work the same way as with any other Neo4j installation with the proper directory volumes mounted.
To run any Cypher against our database within the container, we can use either Neo4j Browser or the Cypher shell tool.
Neo4j Browser works the same as it does with any other Neo4j instance.
Simply ensure the database is running, then open a browser window and enter the url
If we want to run Cypher directly in our container, we need to first access our container.
We will need to use the command below in order to run any commands in a running container.
In this case, we are telling docker to run bash within our container, allowing us to interact with our container using Linux bash commands.
For a full list of options, check out Docker’s info on the
After the above command is run, we can now access Cypher shell by running the
cypher-shell command, which is shown below.
Notice that we also need to specify the username (
-u neo4j) and password (
-p test) in order to access the database, using the authentication values we set up when we created the container.
We can use the returning prompt to write and run various Cypher statements against our data.
The image below shows the command and prompt to access Cypher shell, as well as a query to see how many nodes are in the database (at this point, 0).
The final command exits Cypher shell using
:exit and returns to our bash prompt.
If you do need to modify any of the preset configuration values, you can do so in 3 different ways. We will review each in the next paragraphs.
1. Set environment variables
Defaults are set for pagecache and memory (512M each default). To change these, we can use the
--env parameter in our
docker run command to set different values for these.
2. Mount a /conf volume
We can mount the /conf directory to a local filesystem (like our other directories), so we can modify the
neo4j.conf configuration file.
To do this, we only need to add another
-v option to our
docker run command.
3. Build a custom image
To create a custom image, we will need to create our own Dockerfile that includes anything we want to have in our container. While we will not go into detail on this approach, there is more information in our documentation.
As we have discussed and shown above, Neo4j (by default) requires authentication and requires us to login with
neo4j/neo4j at the first connection and set a new password.
Just as we did above, we can set the password for the Docker container directly by specifying
--env NEO4J_AUTH=neo4j/<password> in your run directive.
We could also disable authentication entirely by specifying
--env NEO4J_AUTH=none instead.
Another way is to run Neo4j as a non-root user by altering the
docker run command with a different option.
Instead of the
--env, we can use the
--user option and pass in the user’s id and group for access.
We can see an example of this below, where it passes in the current user and group as the authentication.
Congratulations! You have successfully created and started a Neo4j graph database in a Docker container!
If you have any questions or need assistance using Neo4j with Docker, reach out to us on the Community Site!
To learn more about running Neo4j with Docker, check out our documentation.