Modify the default configuration
The default configuration provided by the Neo4j image is intended for learning about Neo4j but must be modified to make it suitable for production use.
In particular, the default memory assignments to Neo4j are very limited (
NEO4J_server_memory_heap_max__size=512M), to allow multiple containers to be run on the same server.
You can read more about configuring Neo4j in the Docker specific configuration settings.
There are three ways to modify the configuration:
Set environment variables.
Mount a /conf volume.
Build a new image.
Which one to choose depends on how much you need to customize the image.
Pass environment variables to the container when you run it, for example:
docker run \ --detach \ --publish=7474:7474 --publish=7687:7687 \ --volume=$HOME/neo4j/data:/data \ --volume=$HOME/neo4j/logs:/logs \ --env NEO4J_dbms_memory_pagecache_size=4G \ neo4j:5.14.0
Any configuration value (see Configuration settings) can be passed using the following naming scheme:
Underscores must be written twice:
_is written as
Periods are converted to underscores:
.is written as
As an example,
db.tx_log.rotation.size could be set by specifying the following argument to Docker:
Variables that can take multiple options, such as
NEO4J_server_jvm_additional, must be defined just once, and include a concatenation of the multiple values.
--env NEO4J_server_jvm_additional="-Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.password.file=$HOME/conf/jmx.password -Dcom.sun.management.jmxremote.access.file=$HOME/conf/jmx.access -Dcom.sun.management.jmxremote.port=3637"
From Neo4j 5.6 onwards, Docker additional configuration settings via an environment variable for JVM no longer override the default JVM configurations but are appended to them.
To make arbitrary modifications to the Neo4j configuration, provide the container with a /conf volume:
docker run \ --detach \ --publish=7474:7474 --publish=7687:7687 \ --volume=$HOME/neo4j/data:/data \ --volume=$HOME/neo4j/logs:/logs \ --volume=$HOME/neo4j/conf:/conf \ neo4j:5.14.0
The configuration files in the /conf volume override the files provided by the image. So if you want to change one value in a file, you must ensure that the rest of the file is complete and correct. Environment variables passed to the container by Docker override the values in configuration files in /conf volume.
If you use a configuration volume you must make sure to listen on all network interfaces.
This can be done by setting
To dump the initial set of configuration files, run the image with the
You must set the
neo4j user as the owner of $HOME/neo4j/conf to allow write access from the Neo4j Docker container:
sudo chown neo4j:neo4j $HOME/neo4j/conf
Processes in the Neo4j docker container run under the
docker run --rm \ --volume=$HOME/neo4j/conf:/conf \ neo4j:5.14.0 dump-config
To customize a Neo4j Docker image, you create a custom Dockerfile based on a Neo4j image (using the
FROM instruction), build that image, and run a container based on it.
It is recommended to specify an explicit version of the base Neo4j Docker image. For available Neo4j Docker images, see https://hub.docker.com/_/neo4j.
Additionally, you can pass
EXTENSION_SCRIPT as an environment variable, pointing to a location in a folder you need to mount.
You can use this script to perform an additional initialization or configuration of the environment, for example, loading credentials or dynamically setting neo4j.conf settings, etc.
The Neo4j image
entrypoint script will check for the presence of an
EXTENSION_SCRIPT environment variable.
If set, it will first execute the
entrypoint code, then the extension script specified, and finally, it will start Neo4j.
The following is an example of how to create a custom Dockerfile based on a Neo4j image, build the image, and run a container based on it.
It also shows how to use the
# Create a custom Dockerfile based on a Neo4j image: /example/Dockerfile FROM neo4j:5.14.0-enterprise COPY extension_script.sh /extension_script.sh ENV EXTENSION_SCRIPT=/extension_script.sh /example/extension_script.sh echo "extension logic" # Build the custom image: docker build --file /example/Dockerfile --tag neo4j:5.14.0-enterprise-custom-container-1 /example # Create and run a container based on the custom image: docker run --interactive --tty --name custom-container-1 -p7687:7687 -p7474:7474 -p7473:7473 --env NEO4J_AUTH=neo4j/password --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes neo4j:5.14.0-enterprise-custom-container-1
The recommended best practices and methods for building efficient Docker images can be found at the Docker documentation → Best practices for writing Dockerfiles.