To self-host Neo4j on Control Plane, create a secret with the admin password and install the Neo4j template from the Template Catalog, Control Plane’s library of ready-to-install apps. You get one Neo4j Community server with Bolt kept private, the password in that secret, daily volume snapshots, and APOC ready for GraphRAG.
Neo4j stores data as nodes and relationships, so a question that takes a stack of self-joins in SQL is one Cypher pattern that walks the relationships directly. The project calls itself “the world’s leading Graph Database”, and its repository has more than 17,000 GitHub stars. The same queries now feed LLM apps: GraphRAG pulls the facts around an entity from a knowledge graph before the model answers. The slow part is the setup around Cypher: a durable volume, a safe home for the admin password, a Bolt port that should never face the internet, and a backup plan for an edition that cannot back up a running database. The template settles all four before you write your first MATCH.
Why self-host Neo4j on Control Plane
- A volume that keeps the graph. Stores and transaction logs sit on a persistent volume, outside the container.
- Daily snapshots, restorable in place. Control Plane snapshots that volume on a schedule, and one command rolls it back.
- Bolt gets no public address. Port 7687 stays private even after you publish Neo4j Browser.
- The
neo4jpassword lives in a Control Plane secret. You create it, the chart reads it by name, and it never appears in Helm values or the install command. - A Control Plane identity scoped to one secret. A Control Plane policy created by the template lets Neo4j reveal your credentials secret and no other.
- APOC loaded for LLM tooling. APOC Core is on by default, because the LangChain and LlamaIndex Neo4j integrations require it.
Included out of the box
- Neo4j Community Edition (GPLv3), one stateful server
- Bolt on 7687; Neo4j Browser and the HTTP Query API on 7474
/dataon a 10 GiB ext4 volume, with optional autoscaling to a ceiling you choose- Snapshot schedule and retention as two values (03:00 UTC daily, kept 7 days by default)
- JVM heap and page cache sizes as plain settings
- An internal DNS name reachable from every app in the same Global Virtual Cloud (GVC), Control Plane’s term for the set of locations a workload runs in
- Built-in Control Plane logs and metrics, with tracing available to turn on
How to back up and restore Neo4j Community Edition
Community Edition has no online backup, so a dump job would mean stopping the database. Volume snapshots take its place. List them with the Control Plane CLI, cpln volumeset snapshot get, pick one, and cpln volumeset snapshot restore writes it back; Neo4j restarts on the restored stores.
Two things to know. Snapshots stay with the volume set, Control Plane’s managed persistent storage for a workload, and are not copied off-site, so uninstalling the release removes them too. And after a restore, the neo4j password is whichever one was in use when that snapshot was taken.
How to keep Neo4j private
Apps in the same GVC connect to bolt://RELEASE_NAME-neo4j.GVC_NAME.cpln.local:7687. That is the default, same-gvc; set internalAccess.type to same-org, workload-list (named workloads only), or none to redraw that circle. Traffic between workloads uses mTLS.
For Neo4j Browser on your laptop, cpln port-forward tunnels 7474 and 7687 to localhost and exposes nothing. Set publicAccess.enabled to true and the Browser and HTTP Query API move to the workload’s public endpoint behind the neo4j login (always use the https:// address), while Bolt keeps its private address. Neo4j also locks an account for 5 seconds after 3 wrong password attempts.
How to store the Neo4j admin password
One Control Plane dictionary secret, a secret that holds named key-value pairs, with one key: password, at least 8 characters, no /, and not neo4j. The user is always neo4j. Neo4j applies that password on the first start only. To change it later, run ALTER CURRENT USER SET PASSWORD FROM 'old-password' TO 'new-password' in Cypher, update the secret to match, and redeploy the apps that read it.
How to size and scale Neo4j on Control Plane
Neo4j reserves clustering for its Enterprise Edition, so this template runs one Community server and refuses Enterprise images. There is no failover: an upgrade or setting change restarts Neo4j briefly, and daily snapshots are the recovery point for the data. Install it into a GVC with one location, because a second location would start a separate, empty graph. For data that must stay online through a node or region loss, the Template Catalog also has multi-location databases such as CockroachDB and pgEdge.
To grow, raise maxMemory and grow the volume with cpln volumeset expand or volume autoscaling. Set heap and page cache explicitly and keep them together to about three quarters of maxMemory; the JVM and the OS need the rest.
Neo4j for GraphRAG
GraphRAG retrieves the entities and relationships around a question from a knowledge graph and passes them to the model as context. The LangChain and LlamaIndex Neo4j integrations connect over Bolt and use APOC procedures, which the template enables. Run your LLM app as a workload in the same GVC and it reaches the graph over internal DNS, with no public port and no credentials in code. Give the app’s identity reveal access to the same secret, and it reads the password by reference.
How to deploy Neo4j on Control Plane
Sign up for Control Plane and create the credentials secret first: without it the workload waits and logs nothing. Then pick Neo4j in the Template Catalog in the Control Plane Console, or run:
cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/neo4j \
--version 1.0.0 --gvc GVC_NAME \
--set auth.credentialsSecretName=SECRET_NAMEThe Neo4j template documentation covers sizing, restores, password changes and troubleshooting.
FAQ
Answers to common questions about running Neo4j on Control Plane.
How do I self-host Neo4j?
Create a dictionary secret with a password key, then install the Neo4j template from the Template Catalog in the Control Plane Console or with cpln helm install. The template creates the stateful workload, its volume, its snapshot schedule, and an identity that can read only that secret.
How do I back up Neo4j Community Edition?
Use volume snapshots. Control Plane snapshots the Neo4j volume daily at 03:00 UTC and keeps snapshots for 7 days by default, and cpln volumeset snapshot restore rolls the volume back in place. Snapshots stay with the volume set and are deleted with it when you uninstall the release.
Is the Neo4j Bolt port exposed to the internet?
No. Bolt on port 7687 has only an internal address in the GVC, even when you turn on public access for Neo4j Browser and the HTTP Query API.
How do I connect to Neo4j Browser without a public endpoint?
Run cpln port-forward to tunnel ports 7474 and 7687 to localhost, then open Neo4j Browser locally.
Where is the Neo4j admin password stored?
In a Control Plane secret you create, under the key password. The workload reads it by reference, and its identity can reveal that secret and no other.
Can Neo4j on Control Plane run in more than one location?
One location per install. Neo4j Community Edition has no clustering, so each extra location would hold its own empty graph. For multi-location data, use a catalog database built for it, such as CockroachDB or pgEdge.
Can I use Neo4j on Control Plane for GraphRAG?
Yes. APOC Core is enabled by default, and LangChain and LlamaIndex connect over Bolt from workloads in the same GVC.
How do I scale Neo4j on Control Plane?
Vertically. Raise maxMemory along with heapSize and pageCacheSize, and grow storage with cpln volumeset expand or volume autoscaling (off by default), which grows the volume up to a maximum capacity you set.
How do I deploy Neo4j without managing a Kubernetes cluster?
Install the Neo4j template on Control Plane. cpln helm install uses a Helm chart, and Control Plane runs the workload, so there is no Kubernetes cluster for you to operate.
Which clouds can I deploy Neo4j on?
AWS, GCP, and Azure. You choose the location when you create the GVC, and the template runs Neo4j there.
