Docker-specific operations

You can use the Neo4j tools when running Neo4j in a Docker container.

Use Neo4j Admin

The Neo4j Admin tool can be run locally within a container using the following command:

docker exec --interactive --tty <containerID/name> neo4j-admin <category> <command>

To determine the container ID or name, run docker ps to list the currently running Docker containers.

For more information about the neo4j-admin commands, see Neo4j Admin and Neo4j CLI.

Use Neo4j Import

The Neo4j Import tool can be run locally within a container using the following commands:

docker exec --interactive --tty <containerID/name> neo4j-admin database import full <options>

and

docker exec --interactive --tty <containerID/name> neo4j-admin database import incremental <options>

For more information about the commands' syntax and options, see Full import and Incremental import.

Prerequisites

  • Verify that you have created the folders that you want to mount as volumes to the Neo4j docker container.

  • Verify that the CSV files that you want to load into Neo4j are formatted as per CSV header format.

  • Verify that you have added the CSV files to the folder that will be mounted to /import in your container.

Import CSV files into the Neo4j Docker container using the Neo4j import tool

This is an example of how to start a container with mounted volumes /data and /import, to ensure the persistence of the data in them, and load the CSV files using the neo4j-admin database import full command. You can add the flag --rm to automatically remove the container’s file system when the container exits.

docker run --interactive --tty --rm \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \
    --volume=$HOME/neo4j/import:/import \
    neo4j:5.8.0 \
neo4j-admin database import full --nodes=Movies=/import/movies_header.csv,/import/movies.csv \
--nodes=Actors=/import/actors_header.csv,/import/actors.csv \
--relationships=ACTED_IN=/import/roles_header.csv,/import/roles.csv

Use Neo4j Admin for memory recommendations

The neo4j-admin server memory-recommendation command with the argument --docker outputs environmental variables that can be passed to a Neo4j docker container. The following example shows how neo4j-admin server memory-recommendation --docker provides a memory recommendation in a docker-friendly format.

Example 1. Invoke neo4j-admin server memory-recommendation --docker
$neo4j-home> bin/neo4j-admin server memory-recommendation --memory=16g --docker

...
...
...
# Based on the above, the following memory settings are recommended:
NEO4J_server_memory_heap_initial__size='5g'
NEO4J_server_memory_heap_max__size='5g'
NEO4J_server_memory_pagecache_size='7g'
#
# It is also recommended turning out-of-memory errors into full crashes,
# instead of allowing a partially crashed database to continue running:
NEO4J_server_jvm_additional='-XX:+ExitOnOutOfMemoryError'
#
...
...

Use Cypher Shell

The Neo4j Cypher Shell tool can be run locally within a container using the following command:

docker exec --interactive --tty <containerID/name> cypher-shell <options>

For more information about the cypher-shell syntax and options, see Syntax.

Retrieve data from a database in a Neo4j Docker container

The following is an example of how to use the cypher-shell command to retrieve data from the neo4j database.

  1. Run a new container, mounting the same volume /data as in the import example.

    docker run --interactive --tty --name <containerID/name> \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \
    neo4j:5.8.0

  2. Use the container ID or name to get into the container, and then, run the cypher-shell command and authenticate.

    docker exec --interactive --tty <containerID/name> cypher-shell -u neo4j -p <password>

  3. Retrieve some data.

    neo4j@neo4j> match (n:Actors)-[r]->(m:Movies) return n.name AS Actors, m.title AS Movies, m.year AS MovieYear;
+-------------------------------------------------------------+
| Actors               | Movies                   | MovieYear |
+-------------------------------------------------------------+
| "Keanu Reeves"       | "The Matrix Revolutions" | 2003      |
| "Keanu Reeves"       | "The Matrix Reloaded"    | 2003      |
| "Keanu Reeves"       | "The Matrix"             | 1999      |
| "Laurence Fishburne" | "The Matrix Revolutions" | 2003      |
| "Laurence Fishburne" | "The Matrix Reloaded"    | 2003      |
| "Laurence Fishburne" | "The Matrix"             | 1999      |
| "Carrie-Anne Moss"   | "The Matrix Revolutions" | 2003      |
| "Carrie-Anne Moss"   | "The Matrix Reloaded"    | 2003      |
| "Carrie-Anne Moss"   | "The Matrix"             | 1999      |
+-------------------------------------------------------------+

9 rows available after 61 ms, consumed after another 7 ms

Pass a Cypher script file to a Neo4j Docker container

There are different ways to pass a Cypher script file to a Neo4j Docker container, all of them using the Cypher Shell tool.

  • Using the --file option of the cypher-shell command followed by the file name. After the statements are executed cypher-shell shuts down.

  • Using the :source command followed by the file name when in the Cypher interactive shell.

  • Using the commands cat or curl with cypher-shell to pipe the contents of your script file into your container.

To use the --file option or the :source command of Cypher Shell, the Cypher script file must be readable from inside the container, otherwise cypher-shell will not be able to open the file. The folder containing the examples must be mounted to the container when the container is started.

The following are syntax examples of how to use these commands:

example.cypher script
match (n:Actors)-[r]->(m:Movies) return n.name AS Actors, m.title AS Movies, m.year AS MovieYear;
Invoke cypher-shell with the --file option
# Put the example.cypher file in the local folder ./examples.

# Start a Neo4j container and mount the ./examples folder inside the container:

docker run --rm \
--volume /path/to/local/examples:/examples \
--publish=7474:7474 \
--publish=7687:7687 \
--env NEO4J_AUTH=neo4j/ \
neo4j:5.8.0

# Run the Cypher Shell tool with the --file option passing the example.cypher file:

docker exec --interactive --tty  cypher-shell -u neo4j -p  --file /examples/example.cypher
Use the :source command to run a Cypher script file
# Put the example.cypher file in the local folder ./examples.

# Start a Neo4j container and mount the ./examples folder inside the container:

docker run --rm \
--volume /path/to/local/examples:/examples \
--publish=7474:7474 \
--publish=7687:7687 \
--env NEO4J_AUTH=neo4j/ \
neo4j:5.8.0

# Use the container ID or name to get into the container, and then, run the cypher-shell command and authenticate.

docker exec --interactive --tty  cypher-shell -u neo4j -p 

# Invoke the :source command followed by the file name.

neo4j@neo4j> :source example.cypher
Invoke curl with Cypher Shell
curl http://mysite.com/config/example.cypher | sudo docker exec --interactive <containerID/name> cypher-shell -u neo4j -p <password>
Invoke cat with Cypher Shell
cat example.cypher | sudo  docker exec --interactive  <containerID/name> cypher-shell -u neo4j -p <password>
Example output
Actors, Movies, MovieYear
"Keanu Reeves", "The Matrix Revolutions", 2003
"Keanu Reeves", "The Matrix Reloaded", 2003
"Keanu Reeves", "The Matrix", 1999
"Laurence Fishburne", "The Matrix Revolutions", 2003
"Laurence Fishburne", "The Matrix Reloaded", 2003
"Laurence Fishburne", "The Matrix", 1999
"Carrie-Anne Moss", "The Matrix Revolutions", 2003
"Carrie-Anne Moss", "The Matrix Reloaded", 2003
"Carrie-Anne Moss", "The Matrix", 1999

These commands take the contents of the script file and pass it into the Docker container using Cypher Shell. Then, they run a Cypher example, LOAD CSV dataset, which might be hosted somewhere on a server (with curl), create indexes, constraints, or do other administrative operations.

Install user-defined procedures

To install user-defined procedures, mount the /plugins volume containing the jars.

docker run \
   --publish=7474:7474 --publish=7687:7687 \
   --volume=$HOME/neo4j/plugins:/plugins \
   neo4j:5.8.0

Configure Neo4j plugins

The Neo4j Docker image includes a startup script that can automatically download and configure certain Neo4j plugins at runtime.

This feature is intended to facilitate using Neo4j plugins in development environments, but it is not recommended for use in production environments.

To use plugins in production with Neo4j Docker containers, see Install user-defined procedures.

The NEO4J_PLUGINS environment variable can be used to specify the plugins to install using this method. This should be set to a JSON-formatted list of supported plugins.

The following plugins are supported:

Table 1. Supported Neo4j plugins
Name Key Further information

APOC

apoc

https://neo4j.com/labs/apoc/

APOC Core

apoc-core

APOC

Bloom

bloom

Neo4j Bloom

Streams

streams

Neo4j Streaming Data Integrations User Guide

Graph Data Science

graph-data-science

Graph Data Science

Neo Semantics

n10s

https://neo4j.com/labs/nsmtx-rdf/

Running Bloom in a Docker container requires Neo4j Docker image 4.2.3-enterprise or later.

If invalid NEO4J_PLUGINS values are passed, Neo4j returns a notification that the plugin is not known. For example, --env NEO4J_PLUGINS='["gds"]' returns the following notification:

Example output
"gds" is not a known Neo4j plugin. Options are:
apoc
apoc-core
bloom
graph-data-science
graphql
n10s
Example 2. Install the APOC plugin (apoc)

You can use the Docker argument --env NEO4J_PLUGINS='["apoc"]' and run the following command:

docker run -it --rm \
  --publish=7474:7474 --publish=7687:7687 \
  --env NEO4J_AUTH=none \
  --env NEO4J_PLUGINS='["apoc"]' \
  neo4j:5.8.0
Example 3. Install the APOC plugin (apoc) and the Neo Semantics plugin (n10s)

You can use the Docker argument --env NEO4J_PLUGINS='["apoc", "n10s"]' and run the following command:

docker run -it --rm \
  --publish=7474:7474 --publish=7687:7687 \
  --env NEO4J_AUTH=none \
  --env NEO4J_PLUGINS='["apoc", "n10s"]' \
  neo4j:5.8.0