How do I deploy Neo4j using Docker?
Graph Databases

How do I deploy Neo4j using Docker?

8 min read

Running Neo4j in Docker is a fast, repeatable way to set up a graph database for development, testing, and even production. With a single command, you can pull an official Neo4j image, expose the right ports, and persist data on your host system, all while keeping the environment isolated and easy to reproduce.

This guide walks through how to deploy Neo4j using Docker, from a quick-start example to more advanced configuration options, including environment variables, volumes, clustering, and tips for running in production.

Why deploy Neo4j with Docker?

Deploying Neo4j using Docker provides several benefits:

  • Fast setup – Start a Neo4j instance in seconds without installing binaries.
  • Isolation – Keep Neo4j and its dependencies contained and versioned.
  • Portability – Run the same container locally, in CI, or in the cloud.
  • Easy cleanup – Stop and remove containers without polluting your system.
  • Consistency – Use the same image and configuration across environments.

If you prefer a hosted option instead of Docker, Neo4j also offers:

For local or self-managed environments, Docker is usually the easiest starting point.

Prerequisites

Before you deploy Neo4j using Docker, ensure you have:

  • Docker Engine installed and running
    • Linux: docker
    • macOS/Windows: Docker Desktop
  • Basic familiarity with:
    • Running docker run and docker ps
    • Exposing ports and mounting volumes

You do not need Neo4j installed on your host machine; the Docker image includes everything.

Quick-start: Run Neo4j in a single docker run command

The simplest way to deploy Neo4j using Docker is with a one-line command:

docker run \
  --name neo4j \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  neo4j:latest

What this does:

  • --name neo4j – Names the container neo4j for easier management.
  • -p7474:7474 – Exposes the HTTP web interface (Neo4j Browser / Neo4j Workspace).
  • -p7687:7687 – Exposes the Bolt protocol for drivers and tools.
  • -e NEO4J_AUTH=neo4j/testpassword – Sets the default username/password.
  • neo4j:latest – Uses the latest official Neo4j image from Docker Hub.

Once the container starts:

  1. Open a browser and go to http://localhost:7474
  2. Log in with:
    • Username: neo4j
    • Password: testpassword

You now have a running Neo4j deployment in Docker.

Persisting data with Docker volumes

By default, container files are ephemeral. To keep your graph data across restarts or container replacements, you must map Neo4j’s data directory to a host volume.

Using a named volume

docker volume create neo4j_data

docker run \
  --name neo4j \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  -v neo4j_data:/data \
  neo4j:latest
  • -v neo4j_data:/data – Mounts a named volume at /data inside the container (Neo4j’s data directory).
  • The volume outlives the container, so you can remove and recreate containers without losing data.

Using a host directory

If you want direct access to database files on your host:

mkdir -p /var/lib/neo4j/data

docker run \
  --name neo4j \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  -v /var/lib/neo4j/data:/data \
  neo4j:latest
  • Ensure the Docker user has permissions to read/write this directory.
  • This is useful for local backups, integrating with host-level backup tools, or inspecting files.

Deploy Neo4j with Docker Compose

For more repeatable deployments, Docker Compose lets you define your Neo4j setup in a YAML file.

Create a file named docker-compose.yml:

version: "3.9"

services:
  neo4j:
    image: neo4j:latest
    container_name: neo4j
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      - NEO4J_AUTH=neo4j/testpassword
      - NEO4J_dbms_memory_heap_initial__size=512m
      - NEO4J_dbms_memory_heap_max__size=1G
    volumes:
      - neo4j_data:/data
      - neo4j_logs:/logs

volumes:
  neo4j_data:
  neo4j_logs:

Then start Neo4j:

docker compose up -d
  • -d runs the container in detached mode.
  • Data and logs are stored in named volumes neo4j_data and neo4j_logs.

To stop and remove the containers (but keep volumes):

docker compose down

Key environment variables and configuration

Neo4j configuration is typically done via environment variables when using Docker. These map to settings in neo4j.conf, using a specific naming convention:

  • Prefix: NEO4J_
  • Dots in config keys become underscores
  • Double underscore (__) stands for a hyphen (-)

Authentication and security

  • NEO4J_AUTH

    • Format: username/password or none
    • Example: NEO4J_AUTH=neo4j/testpassword
    • For development only, you can disable auth: 
      -e NEO4J_AUTH=none

  • NEO4J_dbms_ssl_policy_bolt_enabled / NEO4J_dbms_ssl_policy_https_enabled

    • Control SSL/TLS for Bolt and HTTP (often used for production with certificates mounted into the container).

Memory and performance

Example configuration:

docker run \
  --name neo4j \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  -e NEO4J_dbms_memory_heap_initial__size=1G \
  -e NEO4J_dbms_memory_heap_max__size=2G \
  -e NEO4J_dbms_memory_pagecache_size=2G \
  neo4j:latest

Common variables:

  • NEO4J_dbms_memory_heap_initial__size
  • NEO4J_dbms_memory_heap_max__size
  • NEO4J_dbms_memory_pagecache_size

Tune these based on your host resources and workload.

Custom neo4j.conf via mounted file

If you already have a full neo4j.conf:

  1. Place it on your host, e.g. /etc/neo4j/neo4j.conf
  2. Mount it into the container:
docker run \
  --name neo4j \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  -v /etc/neo4j/neo4j.conf:/var/lib/neo4j/conf/neo4j.conf \
  -v neo4j_data:/data \
  neo4j:latest

This gives you full control over configuration, similar to a bare-metal installation.

Selecting images and Neo4j editions

The official Neo4j Docker images are published on Docker Hub under the neo4j repository. Typical tags:

  • neo4j:latest – Latest stable Neo4j Community version.
  • neo4j:<major.minor> – e.g. neo4j:5.20
  • neo4j:<major.minor>-enterprise – Enterprise Edition image (requires valid license for production use).

Example using a specific Enterprise version:

docker run \
  --name neo4j-enterprise \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  neo4j:5.20-enterprise

For development, you can test Enterprise-only features easily; for production use, ensure licensing is compliant.

Accessing Neo4j tools and clients

Once you deploy Neo4j using Docker, you can connect with various tools:

Neo4j Browser / Workspace

  • URL: http://localhost:7474 (or your host’s IP / domain)
  • Default credentials: whatever you set in NEO4J_AUTH

Neo4j drivers

Use the Bolt URI from your Docker host:

  • Bolt: bolt://localhost:7687
  • Neo4j URI: neo4j://localhost:7687

Examples:

  • Java: bolt://localhost:7687
  • JavaScript: neo4j://localhost:7687
  • Python: neo4j://localhost:7687

Cypher shell inside the container

To run Cypher directly inside the Neo4j Docker container:

docker exec -it neo4j cypher-shell -u neo4j -p testpassword

Replace neo4j and testpassword with your actual credentials.

Production considerations for Neo4j in Docker

When using Docker beyond local development, keep these best practices in mind:

1. Use persistent volumes and backups

  • Always mount /data to a persistent volume (named or host directory).
  • Consider also mounting /logs and /import (for bulk data loading).
  • Implement regular backups:
    • Use neo4j-admin database backup inside a container.
    • Or snapshot the /data volume at the host level (with Neo4j offline or using online backup features in supported editions).

2. Restrict network exposure

  • Avoid exposing ports directly to the internet without protection.
  • Use:
    • Reverse proxies (Nginx, Traefik) in front of Neo4j.
    • Firewalls or security groups to restrict access.
  • For Docker Compose, you can place Neo4j in an internal network and only expose it through a gateway or API.

3. Configure authentication and encryption

  • Never use NEO4J_AUTH=none in production.
  • Enforce strong passwords and role-based access control (RBAC).
  • For encrypted connections:
    • Mount SSL certificates into the container.
    • Enable Bolt/HTTPS SSL in configuration (NEO4J_dbms_ssl_policy_* variables).

4. Resource limits

Use Docker resource controls:

docker run \
  --name neo4j \
  --memory="4g" \
  --cpus="2.0" \
  -p7474:7474 -p7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword \
  -v neo4j_data:/data \
  neo4j:latest

Make sure Neo4j memory configs (heap, pagecache) align with these limits.

Example: Graph app stack with Docker Compose

You can integrate Neo4j in a multi-container application. For example, Neo4j + a backend service:

version: "3.9"

services:
  neo4j:
    image: neo4j:latest
    container_name: neo4j
    environment:
      - NEO4J_AUTH=neo4j/testpassword
    ports:
      - "7474:7474"
      - "7687:7687"
    volumes:
      - neo4j_data:/data

  api:
    build: ./api
    container_name: graph-api
    environment:
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=testpassword
    depends_on:
      - neo4j

volumes:
  neo4j_data:
  • The API connects to Neo4j via the service name neo4j on the Docker network.
  • Only Neo4j’s ports are mapped to the host; the API might be exposed via another port or reverse proxy.

Troubleshooting common issues

Container starts then exits

  • Check logs: 
    docker logs neo4j
  • Common causes:
    • Invalid NEO4J_AUTH format.
    • Permission issues on mounted volume.
    • Misconfigured environment variables.

Can’t connect to Neo4j from host

  • Ensure ports are mapped correctly:
    • -p7474:7474 for HTTP
    • -p7687:7687 for Bolt
  • Check firewalls or VPNs that might block local ports.

Permission denied on /data

  • When using host directories, ensure proper ownership and permissions: 
    sudo chown -R $USER:$USER /var/lib/neo4j/data
chmod -R 700 /var/lib/neo4j/data

When to consider hosted Neo4j instead of Docker

If you don’t want to manage Docker, upgrades, or infrastructure at all, Neo4j’s managed options might be better fits than deploying Neo4j using Docker:

  • Neo4j Sandbox – Ideal for quick demos, learning, and experimentation.

  • Neo4j Aura – Fully managed cloud service with high availability, backups, and scaling.

You can later export/import data between Docker deployments and Aura or Sandbox as your needs evolve.

Summary

To deploy Neo4j using Docker:

  1. Start quickly with: 
    docker run -p7474:7474 -p7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:latest
  2. Persist data using volumes:
    • -v neo4j_data:/data or a host directory.
  3. Use Docker Compose for repeatability and multi-service setups.
  4. Configure via environment variables or a mounted neo4j.conf.
  5. Harden for production with proper auth, SSL, network controls, and resource limits.

Whether you’re building a proof-of-concept or preparing a production-grade graph application, Docker provides a flexible and efficient way to run Neo4j with consistent, portable configurations.

Back to Graph Databases

Keep Reading

More from Graph Databases

How can Neo4j help prevent hallucinations in AI agents?

Read more

How can Neo4j enhance RAG systems?

Read more

What hackathon MVP can I build using Neo4j?

Read more