ddev-neo4j

A DDEV add-on that provisions a Neo4j graph database service alongside your DDEV project. Designed to be zero-config for Drupal sites that consume Neo4j but useful for any DDEV project that needs a local graph database.

What you get

• A Neo4j 5 (community) container reachable from the web container at bolt://neo4j:7687 and http://neo4j:7474.
• The Neo4j Browser UI at https://<project>.ddev.site:7475, with a valid TLS cert provided by DDEV’s router.
• The APOC and Graph Data Science plugins enabled by default.
• Named persistent volumes for graph data, logs, and plugins that survive ddev stop and are wiped only by ddev add-on remove neo4j.
• For Drupal projects: a settings.ddev.neo4j.php snippet wired into sites/default/settings.php that populates $settings['content_graph_neo4j'] so the Drupal side connects with no extra wiring.

Install

ddev add-on get kevinquillen/ddev-neo4j
ddev restart

First boot takes ~30 seconds while Neo4j downloads and installs APOC and GDS into the plugins volume; subsequent boots are fast.

Open the Browser UI:

ddev launch :7475
# or visit https://<project>.ddev.site:7475 directly

In the Browser’s Connect form:

The cert is generated at install time with mkcert — the same tool DDEV uses for its own TLS — so it’s signed by the same root CA your browser already trusts. No certificate warning, no bolt+ssc:// workaround.

If mkcert wasn’t available at install time, the add-on falls back to an openssl self-signed cert; use bolt+ssc://<project>.ddev.site:7687 in that case (the Browser will prompt you to trust it once).

Connect from your project

From PHP (Drupal-ready)

If your project type is Drupal, the add-on writes web/sites/default/settings.ddev.neo4j.php and includes it from settings.php. It populates:

$settings['content_graph_neo4j'] = [
  'uri' => 'bolt://neo4j:7687',
  'username' => 'neo4j',
  'password' => getenv('DDEV_NEO4J_PASSWORD') ?: 'ddevpassword',
  'database' => getenv('DDEV_NEO4J_DATABASE') ?: 'neo4j',
];

Sites that need bespoke credentials can simply not include the file and define their own block.

From the CLI

ddev exec cypher-shell -a bolt://neo4j:7687 -u neo4j -p ddevpassword

Connection endpoints

Neo4j is configured with server.bolt.tls_level=OPTIONAL, so the same port 7687 accepts both plaintext Bolt (for in-network clients) and TLS-wrapped Bolt (for the Browser UI and any host-side client).

Override the host-side Bolt port via DDEV_NEO4J_BOLT_HOST_PORT in .ddev/config.neo4j.yaml if 7687 collides with another project.

Configuration overrides

The add-on ships .ddev/config.neo4j.yaml for per-project tuning. Edit it and run ddev restart:

web_environment:
  - DDEV_NEO4J_PASSWORD=ddevpassword
  - DDEV_NEO4J_DATABASE=neo4j
  - DDEV_NEO4J_HEAP_INITIAL=512m
  - DDEV_NEO4J_HEAP_MAX=1G
  - DDEV_NEO4J_PAGECACHE=512m
  - NEO4J_DOCKER_IMAGE=neo4j:5-community
  - NEO4J_ACCEPT_LICENSE_AGREEMENT=no

To claim ownership of the file (so a future ddev add-on get won’t overwrite your edits), delete the #ddev-generated marker comment at the top.

Note: values that contain YAML flow indicators ([, ], {, }, ,) cannot live in config.neo4j.yaml — they get inlined as plain scalars into the rendered base compose file and break the merged-file YAML parse. To override the plugin list, edit NEO4J_PLUGINS directly in .ddev/docker-compose.neo4j.yaml.

Use Neo4j Enterprise (opt-in)

web_environment:
  - NEO4J_DOCKER_IMAGE=neo4j:5-enterprise
  - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes

You are responsible for complying with Neo4j’s commercial license.

Disable plugins

Edit the NEO4J_PLUGINS line in .ddev/docker-compose.neo4j.yaml and set it to []:

      - 'NEO4J_PLUGINS=[]'

Then run ddev restart.

Low-memory hosts

web_environment:
  - DDEV_NEO4J_HEAP_MAX=512m
  - DDEV_NEO4J_PAGECACHE=256m

Wipe the database

Three options, in order of severity:

# Drop all nodes/relationships, keep credentials and config.
ddev exec cypher-shell -a bolt://neo4j:7687 -u neo4j -p ddevpassword \
  'MATCH (n) DETACH DELETE n'

# Remove the data volume only.
ddev stop
docker volume rm "ddev-${DDEV_PROJECT:-$(basename $PWD)}-neo4j-data"
ddev start

# Remove the add-on entirely (wipes data, logs, plugin caches,
# Drupal settings include).
ddev add-on remove neo4j

Compatibility

Operational notes

• Cold-start time. First boot is ~30s while plugins install. The web container waits on Neo4j’s healthcheck, so ddev start blocks briefly. This is not a hang.
• Memory. Defaults consume ~1.5 GB resident. Tune DDEV_NEO4J_HEAP_MAX and DDEV_NEO4J_PAGECACHE if your Docker VM is smaller.
• Bolt is plaintext inside the DDEV network. Fine for local dev; configure TLS at the Neo4j level if you need to expose Bolt externally (uncommon in DDEV).
• Volume naming. Volumes are scoped per project as ddev-<project>-neo4j-{data,logs,plugins}, so multiple DDEV sites on the same host don’t collide.

Removing the add-on

ddev add-on remove neo4j

This removes:

• .ddev/docker-compose.neo4j.yaml
• .ddev/config.neo4j.yaml
• .ddev/neo4j/conf/neo4j.conf
• .ddev/settings.ddev.neo4j.php
• The Drupal settings.php include block (left intact if you modified it).
• The ddev-<project>-neo4j-{data,logs,plugins} Docker volumes.

Testing

brew install bats-core bats-assert bats-file bats-support
bats ./tests/test.bats

CI runs the same suite via ddev/github-action-add-on-test on every PR, every push to main, and weekly on a cron schedule.

License

Apache 2.0. See LICENSE.

Neo4j community edition is GPL v3; Neo4j enterprise edition is commercial. APOC is Apache 2.0; Graph Data Science community edition is GPL v3. You are responsible for compliance with their respective licenses when running the add-on.