3.2. Configuration

This chapter describes how configure Neo4j to run in a Docker container.

The default configuration provided by this 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_dbms_memory_pagecache_size=512M and NEO4J_dbms_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 Section A.1, “Configuration settings”.

There are three ways to modify the configuration:

Which one to choose depends on how much you need to customize the image.

3.2.1. Environment variables

Pass environment variables to the container when you run it.

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 \

Any configuration value (see Section A.1, “Configuration settings”) can be passed using the following naming scheme:

  • Prefix with NEO4J_.
  • Underscores must be written twice: _ is written as __.
  • Periods are converted to underscores: . is written as _.

As an example, dbms.tx_log.rotation.size could be set by specifying the following argument to Docker:


Variables which can take multiple options, such as dbms_jvm_additional, must be defined just once, and include a concatenation of the multiple values. For example:

--env=NEO4J_dbms_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" Neo4j Enterprise Edition

The following environment variables are specific to Causal Clustering, and are available in the Neo4j Enterprise Edition:

  • NEO4J_dbms_mode: the database mode, defaults to SINGLE, set to CORE or READ_REPLICA for Causal Clustering.
  • NEO4J_causal__clustering_expected__core__cluster__size: the initial cluster size (number of Core instances) at startup.
  • NEO4J_causal__clustering_initial__discovery__members: the network addresses of an initial set of Core cluster members.
  • NEO4J_causal__clustering_discovery__advertised__address: hostname/ip address and port to advertise for member discovery management communication.
  • NEO4J_causal__clustering_transaction__advertised__address: hostname/ip address and port to advertise for transaction handling.
  • NEO4J_causal__clustering_raft__advertised__address: hostname/ip address and port to advertise for cluster communication.

See Section 3.3, “Clustering” for examples of how to configure Causal Clustering on Docker.

3.2.2. /conf volume

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 \

Any configuration files in the /conf volume will override 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 will still 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 dbms.connectors.default_listen_address=

To dump an initial set of configuration files, run the image with the dump-config command.

docker run --rm \
    --volume=$HOME/neo4j/conf:/conf \
    neo4j:3.5 dump-config

3.2.3. Building a new image

For more complex customization of the image you can create a new image based on this one.

FROM neo4j:3.5

If you need to make your own configuration changes, we provide a hook so you can do that in a script:

COPY extra_conf.sh /extra_conf.sh

Then you can pass in the EXTENSION_SCRIPT environment variable at runtime to source the script:

docker run -e "EXTENSION_SCRIPT=/extra_conf.sh" cafe12345678

When the extension script is sourced, the current working directory will be the root of the Neo4j installation.