Neo4j setup

Connect Create Context Graph to Neo4j using Aura, Docker, neo4j-local, or an existing instance.

Create Context Graph supports four ways to connect to Neo4j. Choose the option that fits your workflow.

Neo4j Aura

Neo4j Aura is a fully managed cloud graph database with a free tier. It requires no local installation and is the fastest way to get started.

Prerequisites

• A Neo4j Aura account (free tier available)

1. Create an Aura instance

   1. Go to console.neo4j.io.
   2. Click New Instance.
   3. Choose AuraDB Free (or a paid tier for production).
   4. Select a region close to you.
   5. Click Create.
   6. Save the generated password — you need it in the next step.
2. Download the .env file

   After the instance is created, click the Download .env button. The file contains your connection credentials:

   NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your-generated-password
   

   Save this file somewhere accessible.

3. Scaffold your project

   Pass the --neo4j-aura-env flag to import your Aura credentials directly:

   uvx create-context-graph my-app \
     --domain healthcare \
     --framework pydanticai \
     --neo4j-aura-env /path/to/Neo4j-xxxxxxxx-Created-2026-03-28.txt \
     --demo-data
   

   This parses the .env file, configures the generated project to use your Aura instance, and sets neo4j_type to aura automatically.

4. Verify the connection

   cd my-app
   make test-connection
   

   You should see:

   ✅ Connected to Neo4j Aura (neo4j+s://xxxxxxxx.databases.neo4j.io)
   
5. Seed data and start

   make install
   make seed
   make start
   

Connection refused

• Ensure your Aura instance is Running (not paused).
• Free-tier instances pause after 3 days of inactivity — resume from the Aura console.
• Check that NEO4J_URI starts with neo4j+s:// (TLS is required for Aura).

Authentication failed

• Double-check the password in your .env file.
• If you lost the password, reset it from the Aura console under Instance settings.

Slow queries

Free-tier Aura instances have limited resources — queries may take 2–5 seconds. Upgrade to a paid tier for better performance.

Docker

The generated project includes a docker-compose.yml that runs Neo4j locally in a Docker container. This is the default setup when you don’t specify --neo4j-aura-env or --neo4j-local.

Prerequisites

• Docker installed and running
• Docker Compose (included with Docker Desktop)

1. Scaffold your project

   uvx create-context-graph my-app \
     --domain healthcare \
     --framework pydanticai \
     --demo-data
   

   By default, the generated project uses Docker for Neo4j with these settings:

   NEO4J_URI=neo4j://localhost:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=password
   
2. Start Neo4j

   cd my-app
   make docker-up
   

   This runs docker-compose up -d, which starts Neo4j on:

   • Bolt: localhost:7687 (driver connections)
   • Browser: localhost:7474 (Neo4j Browser UI)
3. Verify and seed

   make test-connection  # Verify Neo4j is reachable
   make seed             # Load demo data
   
4. Start the application

   make install
   make start
   

Managing the Neo4j container

# Stop Neo4j
make docker-down

# View logs
docker-compose logs neo4j

# Reset all data
make docker-down
docker volume rm $(docker volume ls -q | grep neo4j)
make docker-up

Neo4j data is stored in a Docker volume and persists across container restarts. Remove the volume as shown above to start fresh.

Neo4j Browser

While the container is running, open http://localhost:7474 to access the Neo4j Browser. Connect with:

• Connect URL: neo4j://localhost:7687
• Username: neo4j
• Password: password

Port already in use

If port 7687 or 7474 is already in use, either stop the conflicting service or update the ports in docker-compose.yml.

Container won't start

Check Docker logs:

docker-compose logs neo4j

Common causes: insufficient memory (Neo4j needs at least 512 MB RAM) or file permission issues on the data volume.

neo4j-local

@johnymontana/neo4j-local is an npm package that downloads and runs Neo4j Community Edition directly on your machine. It requires Node.js but no Docker installation.

Prerequisites

• Node.js 18+

1. Start neo4j-local

   You can start Neo4j before scaffolding:

   npx @johnymontana/neo4j-local
   

   This starts Neo4j on the default ports:

   • Bolt: neo4j://localhost:7687
   • Browser: http://localhost:7474

   Default credentials: neo4j / neo4j (you will be prompted to change the password on first login).

2. Scaffold your project

   Pass the --neo4j-local flag to configure your project for local Neo4j:

   uvx create-context-graph my-app \
     --domain healthcare \
     --framework pydanticai \
     --neo4j-local \
     --demo
   
3. Start Neo4j via the Makefile target

   The generated project also includes a make neo4j-start target that wraps the same npm package:

   cd my-app
   make neo4j-start
   
4. Seed and start

   make install
   make seed
   make start
   

You can also configure the connection manually by setting these values in your .env file:

NEO4J_URI=neo4j://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

Port already in use

If port 7687 is busy, another Neo4j instance may already be running. Stop it first or change the port.

Authentication failed

If you get auth errors after changing the password:

1. Stop Neo4j.
2. Delete the data directory (usually ~/.neo4j-local/data/).
3. Restart — you will get the default credentials again.

Connection refused

Neo4j may take 10–30 seconds to fully start on first launch while it initializes the database. Wait and retry.

Existing instance

Connect to any running Neo4j instance — a self-hosted server, Neo4j Desktop, or a single Docker container — by providing the URI directly.

1. Gather your connection details

   You need:

   • URI — e.g., neo4j://localhost:7687 or neo4j+s://host:7687 for TLS
   • Username — typically neo4j
   • Password — the password you set when creating the instance
2. Scaffold with --neo4j-uri

   uvx create-context-graph my-app \
     --domain healthcare \
     --framework pydanticai \
     --neo4j-uri neo4j://localhost:7687 \
     --neo4j-username neo4j \
     --neo4j-password your-password \
     --demo-data
   

   You can also set these as environment variables and omit the flags:

   export NEO4J_URI=neo4j://localhost:7687
   export NEO4J_USERNAME=neo4j
   export NEO4J_PASSWORD=your-password
   
   uvx create-context-graph my-app --domain healthcare --framework pydanticai --demo-data
   
3. Verify the connection

   cd my-app
   make test-connection
   
4. Seed and start

   make install
   make seed
   make start
   

All four Neo4j connection options (--neo4j-aura-env, --neo4j-local, --neo4j-uri, and the default Docker path) produce the same generated project structure. Only the .env values and neo4j_type setting differ.