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 →

neo4j docker image now in beta 235x300

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 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.

Beginner


Neo4j Docker Image

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.

neo4j dockerhub versions

To determine which image we want, we need to piece together a few options. First, the neo4j tag starts each image name. After that, the version is preceded with a colon like the neo4j:3.5.0 image. 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 neo4j:latest.

The Enterprise Edition has a -enterprise ending to the name after the version. The latest version of enterprise is tagged with neo4j:enterprise.

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.

Neo4j Configuration

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.

Run Docker with Neo4j

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.

Option

Description

Example

--name

Name your container (avoids generic id)

docker run --name myneo4j neo4j

-p

Specify container ports to expose

docker run -p7687:7687 neo4j

-d

Detach container to run in background

docker run -d neo4j

-v

Bind mount a volume

docker run -v $HOME/neo4j/data:/data neo4j

--env

Set config as environment variables for Neo4j database

docker run --env NEO4J_AUTH=neo4j/test

--help

Output full list of docker run options

docker run --help

By default, Neo4j requires authentication and requires us to first login with neo4j/neo4j and set a new password. We will skip this password reset by initializing the password when we create the Docker container using the --env NEO4J_AUTH=neo4j/<password> option.

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 \
    --name testneo4j \
    -p7474:7474 -p7687:7687 \
    -d \
    -v $HOME/neo4j/data:/data \
    -v $HOME/neo4j/logs:/logs \
    -v $HOME/neo4j/import:/var/lib/neo4j/import \
    -v $HOME/neo4j/plugins:/plugins \
    --env NEO4J_AUTH=neo4j/test \
    neo4j:latest

The 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 testneo4j. This avoids us having to reference the container by its generic id, making our container easier to reference and to remember.

Using the -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 -d. 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 -v option. 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 /data directory, which stores the authentication and roles for each database, as well as the actual data contents of each database instance (in graph.db folder).
  • The second -v option is for the /logs directory. 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 -v option 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.
  • The next -v option 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 latest edition).

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 – testneo4j.

Click to zoom

docker run neo4j

Verifying Execution and Stopping the Container

Once we execute the command above, Neo4j should be running in our Docker container! You can verify this by running docker ps.

If you do not see your container in the list when you run docker ps, you can run docker ps -a instead to see if the container crashed and any associated exit codes.

Click to zoom

neo4j docker ps

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.

Click to zoom

docker startstop neo4j

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.

Click to zoom

docker run duplicate

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.

Click to zoom

docker rm neo4j

Executing Other Functionality in Neo4j Containers

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.

Cypher and Cypher Shell

To run any Cypher against our database within the container, we can use either Neo4j Browser or the Cypher shell tool.

Neo4j Browser

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 localhost:7474.

Cypher Shell

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 exec command.

docker exec -it testneo4j bash

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.

cypher-shell -u neo4j -p test

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.

Click to zoom

docker cypher shell

Overriding Default Config

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.

docker run \
    ... \
    --env NEO4J_dbms_memory_pagecache_size=1G \
    neo4j:latest

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.

docker run \
    ... \
    -v $HOME/neo4j/conf:/conf \
    neo4j:latest

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.

Authentication

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.

docker run \
    ... \
    --user="$(id -u):$(id -g)" \
    neo4j:latest

Wrapping Up

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.