Run Neo4j with Docker inside GitHub Codespaces

Run Neo4j with Docker inside GitHub Codespaces article shows you how to stand up a production-like Neo4j environment in minutes, right inside your browser, with no local installs.

About Neo4j

Before we dive into commands, let’s ground the idea. Neo4j is a native graph database built to model and query connected data using nodes (entities) and relationships (edges). It shines for problems where relationships are first-class citizens: fraud detection, access control, knowledge graphs, supply chain, and network analytics. Querying uses Cypher, a declarative language designed for graph patterns. Running Neo4j in Docker provides reproducibility, isolation, and quick reset. Running it in GitHub Codespaces adds a fully hosted, consistent dev environment tied to your repo. Together, you get fast spins, clean tear-downs, shared team settings—and fewer “works on my machine” surprises.

What you’ll set up

You’ll create a Codespace that can run Docker containers, add a Docker container for Neo4j, persist data into your repository workspace, and forward ports so you can use the Neo4j Browser over HTTPS from your codespace.

Prerequisites

A GitHub account and access to GitHub Codespaces.
A repository where you can commit devcontainer and compose files.
Basic familiarity with Docker and environment variables.

Why Neo4j in Codespaces?

Zero local install: Everything runs in the cloud; your laptop stays clean.
Consistency: All teammates get the same versions and config.
Speed: Start/stop/reset in seconds using Docker .
Security: Keep ports private by default; don’t expose your DB to the internet accidentally.

Store the password safely

First pull the Neoj4 Docker image.

NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password

Create a .env next to your compose file. Don’t commit it.

Ensure .env is ignored:

echo ".env" >> .gitignore

Create a Neo4j Docker Container

docker pull neo4j:5.26.0

Deploy a Docker container running Neoj4

docker run -d \
  -p 7474:7474 \
  -p 7687:7687 \
  -v /workspaces/mydata:/data \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc", "graph-data-science"]' \
  neo4j:5.26.0

This setup binds data/logs/plugins/import to your repository workspace so data persists between container restarts. If you later rebuild your dev container, those files remain in the repo.

Docker automatically reads .env from the directory where you run commands.

Open Neo4j Browser via forwarded ports

Codespaces forwards ports 7474 (HTTP) and 7687 (Bolt). In the Ports panel, click the 7474 URL. Log in with neo4j and your password. If prompted, change the password.

By default, Codespaces ports are private to your account. Keep them private for database services. If you must share, set limited visibility and always use strong credentials.

Loading the Movie Graph Guide in Neo4j Browser

The Neo4j Browser comes with built-in Guides that let you load and experiment with sample datasets.

Open Neo4j Browser
Start your Neo4j instance and open the Neo4j Browser (usually at http://localhost:7474).
Access the Guides Menu
On the left-hand side panel, you’ll see a menu with different icons. Click the book icon (📖) to open the Guides menu.
Select the Movie Graph Guide
In the Guides list, choose “Movie Graph”. This guide walks you through how to load a sample dataset of movies, actors, and their relationships.
Follow the Steps
- The guide will show you Cypher commands to create nodes and relationships.
- Run the provided queries to load the dataset into your Neo4j database.
- You’ll then see how to query for movies, actors, directors, and explore the relationships.
Experiment
Once loaded, you can try your own queries. For example:

MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
RETURN p.name, m.title
LIMIT 10;

Run a quick Cypher test

You can use the Browser’s query editor or connect with cypher-shell directly inside the container:

docker exec -it neo4j cypher-shell -u neo4j
# it will prompt for the password

Try a simple write and read:

CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'});
MATCH p = (:Person {name: 'Alice'})-[:KNOWS]->(:Person) RETURN p;

Memory and plugins

The sample memory settings suit a small 2–4 core Codespace. If you see out-of-memory or slow queries, adjust heap and page cache.
APOC is included via NEO4J_PLUGINS. Graph Data Science (GDS) can be memory-hungry; remove it if you don’t need it right away.

Examples:

# Increase heap (if your machine type allows it)
NEO4J_server_memory_heap_initial__size=2G
NEO4J_server_memory_heap_max__size=2G
NEO4J_server_memory_pagecache_size=1G

Persisting data and backups

Your database files live under ./neo4j/data in the workspace. For shareable backups, prefer database dumps:

# Create a portable dump of the "neo4j" database into /import
docker exec neo4j neo4j-admin database dump neo4j --to-path=/import

# The dump file will appear locally at ./neo4j/import
# You can version this file if it’s small enough, or store it in cloud storage.

Avoid committing ./neo4j/data to git. Dumps are more portable and safer for collaboration.

Connecting from apps in the Codespace

Use the Bolt URL and credentials in your application code. From the same codespace, bolt://localhost:7687 is fine. From the Browser’s forwarded URL, the Browser automatically connects through your Codespaces tunnel.

URI: bolt://localhost:7687
User: neo4j
Password: the value in .env

Troubleshooting

“docker: command not found” or “Cannot connect to the Docker daemon”

Confirm your devcontainer includes the feature: ghcr.io/devcontainers/features/docker-outside-of-docker:1.
Rebuild your codespace: Command Palette → Codespaces: Rebuild Container.

Ports don’t open

Check Neo4j is running: docker ps and docker compose logs -f neo4j.
Ensure port 7474 is forwarded. In devcontainer.json, forwardPorts includes 7474 and 7687.
Keep port visibility private unless you explicitly need to share.

Write permission errors on mounted folders

Let Docker create the ./neo4j subfolders on first run. If they already exist, fix ownership:

sudo chown -R 7474:7474 neo4j

The neo4j image uses UID/GID 7474 by default.

High memory usage or OOM

Lower heap and page cache settings, or pick a larger Codespaces machine type.
Remove GDS from NEO4J_PLUGINS if you’re not using it.

Enterprise vs Community

The example uses neo4j:5.22-community. If you need Enterprise features (RBAC, multi-database scale, ops tooling), switch to neo4j:5.22-enterprise and add:

NEO4J_ACCEPT_LICENSE_AGREEMENT=yes

Only do this if you have the appropriate license for development and testing.

Recap

You set up a Codespace that can run Docker, launched Neo4j with Docker Compose, forwarded ports for the Browser and Bolt driver, and stored data in your workspace. This workflow delivers reproducible, shareable, and secure graph development in the cloud—without installing Neo4j locally. From here, wire your app to bolt://localhost:7687, write Cypher, and iterate fast on graph models.

Discover more from CPI Consulting

Subscribe to get the latest posts sent to your email.