---
title: "Deploy Neo4J"
description: "Graph database for storing and querying connected data"
category: "Queues"
url: https://railway.com/deploy/database-neo4j
---

# Deploy Neo4J

Graph database for storing and querying connected data

**[Deploy Neo4J on Railway](https://railway.com/template/database-neo4j)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/database-neo4j/manifest.json

- **Creator:** A3A
- **Category:** Queues
- **Total deploys:** 2

## Template content

### Neo4j https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/neo4j.svg

- **Image:** neo4j:2026
- **Start command:** `/bin/sh -c 'M=$(cat /sys/fs/cgroup/memory.max 2>/dev/null || cat /sys/fs/cgroup/memory/memory.limit_in_bytes 2>/dev/null || echo max); case "$M" in ""|*[!0-9]*) M=8589934592;; esac; MB=$((M/1048576)); [ "$MB" -gt 131072 ] && MB=131072; H=$((MB*35/100)); P=$((MB*30/100)); [ "$H" -lt 512 ] && H=512; [ "$H" -gt 31744 ] && H=31744; [ "$P" -lt 256 ] && P=256; export NEO4J_server_memory_heap_initial__size="${H}m"; export NEO4J_server_memory_heap_max__size="${H}m"; export NEO4J_server_memory_pagecache_size="${P}m"; echo "railway: cgroup ${MB}MB -> heap ${H}m pagecache ${P}m"; exec tini -s -g -- /startup/docker-entrypoint.sh neo4j'`
- **Health check:** /

### Gateway https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/caddy.svg

- **Image:** caddy:2-alpine
- **Start command:** `/bin/sh -c 'H="$NEO4J_HOST"; case "$H" in ""|:*) H=neo4j.railway.internal;; esac; P="${PORT:-8080}"; printf "%s\n" "{" "admin off" "auto_https off" "servers {" "trusted_proxies static 100.64.0.0/10 fd00::/8" "}" "}" "" ":$P {" "handle /healthz {" "respond 200" "}" "@ws header Upgrade *ebsocket*" "handle @ws {" "reverse_proxy $H:7687" "}" "handle {" "reverse_proxy $H:7474 {" "header_up X-Forwarded-Host {host}" "header_up X-Forwarded-Proto https" "}" "}" "}" > /etc/caddy/Caddyfile; caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile; exec caddy run --config /etc/caddy/Caddyfile --adapter caddyfile'`
- **Health check:** /healthz
- **Public domain:** Yes

## Documentation

# Deploy and Host Neo4j on Railway

Neo4j is a native graph database. It stores nodes and the relationships between them as first-class records, so traversing a connection is a pointer hop rather than a join. That suits anything where the shape of the connections *is* the data: recommendation engines, fraud rings, identity graphs, and the knowledge graphs behind GraphRAG systems. Queries use Cypher, a pattern language where `(:Person)-[:WORKS_ON]->(:Project)` means what it looks like. Community Edition is open source under GPL-3.0.

Self-host Neo4j here with a persistent volume, memory tuning that adapts to whatever plan you put it on, and the APOC procedure library preloaded. Two services deploy: **Neo4j** itself, and a small **Gateway** built on Caddy that owns the public domain. Neo4j speaks on two ports — 7474 for the query workspace and HTTP Query API, 7687 for Bolt — and a Railway domain maps to one port, so the gateway splits traffic by protocol: WebSocket upgrades reach Bolt, everything else the UI. One HTTPS URL covers both, and a TCP proxy exposes raw Bolt to drivers outside Railway.

![Diagram of the Neo4j and Caddy gateway services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787299386/neo4j-architecture.png)

## Getting Started with Neo4j on Railway

Open the deployed URL and you land in Neo4j's query workspace, with a **Connect to instance** dialog already filled in from the server's discovery endpoint. Pick `neo4j+s://` in the Protocol dropdown — the page is HTTPS, so only encrypted schemes are offered — leave the connection URL and `neo4j` username as they are, and paste the password from the `BOLT_PASSWORD` variable. Once connected, the left panel fills with node labels, relationship types and property keys, which is the fastest confirmation the deployment is healthy.

Try a first query by pasting this Cypher into the editor and pressing run:

```
CREATE (a:Person {name:'Alice'})-[:WORKS_ON {since:2026}]->(p:Project {name:'Knowledge Graph'}) RETURN a, p
```

Then run `MATCH p=()-[]->() RETURN p` to see it drawn as a graph, and `CALL apoc.meta.graph()` to confirm APOC is loaded. Change the password with `ALTER CURRENT USER SET PASSWORD FROM 'old' TO 'new'` — the initial one applies only while the credential store is empty, so your change survives later redeploys.

![Neo4j graph visualisation of people working on projects](https://res.cloudinary.com/rroe4rtk/image/upload/v1787299389/neo4j-graph-explorer.png)
![Neo4j Cypher query results shown as a table](https://res.cloudinary.com/rroe4rtk/image/upload/v1787299393/neo4j-results-table.png)
![APOC schema graph of Person and Project node labels](https://res.cloudinary.com/rroe4rtk/image/upload/v1787299397/neo4j-apoc-schema-graph.png)

## About Hosting Neo4j

Self-hosting Neo4j makes sense when the graph holds data you would rather keep off a managed cloud, when you want it beside the app querying it, or when an instance priced by memory footprint stops paying for itself.

- **Cypher** — a declarative pattern-matching query language, now standardised as GQL
- **Index-free adjacency** — traversal cost does not grow with database size
- **ACID transactions** — full guarantees, not eventual consistency
- **APOC** — 450+ procedures for algorithms, import, refactoring and schema introspection
- **HTTP Query API** — run Cypher over HTTPS from any language, no driver
- **Drivers** — Python, JavaScript, Java, .NET and Go, plus LangChain and LlamaIndex

**Neo4j** is the database: store, transaction logs and credentials live on the volume at `/data`, and it listens on 7474 and 7687 inside the private network only. **Gateway** is the Caddy proxy holding the public domain, and it pins the forwarded host and protocol headers so the addresses Neo4j advertises cannot be spoofed.

## Why Deploy Neo4j on Railway

Railway removes the setup work self-hosting a graph database involves:

- Persistent volume attached and mounted before first boot
- Heap and page cache sized from the container's real limits
- HTTPS and certificates handled at the edge
- Private networking, so your app reaches Bolt without touching the internet
- Redeploys that leave the volume intact

## Common Use Cases

- **GraphRAG and knowledge graphs** — store entities pulled from documents, then let an LLM traverse them for grounded answers
- **Recommendations** — "customers who bought this also bought" as a two-hop traversal, not a nightly batch job
- **Fraud analysis** — surface shared devices, addresses or accounts linking unrelated-looking users
- **Dependency mapping** — model microservices or supply chains and query what breaks when a node fails

## Dependencies for Neo4j

- `neo4j:2026` — Neo4j Community Edition, the official Docker Hub image, on the 2026 release line
- `caddy:2-alpine` — the reverse proxy fronting both Neo4j ports on one domain
- One Railway volume mounted at `/data`

No external database is needed, and APOC Core ships inside the image, so nothing downloads at boot.

### Environment Variables Reference

| Variable | Service | Purpose |
|---|---|---|
| `BOLT_PASSWORD` | Neo4j | Password for the `neo4j` user; the one value to keep |
| `NEO4J_AUTH` | Neo4j | `neo4j/`; applied only while the credential store is empty |
| `NEO4J_PLUGINS` | Neo4j | `["apoc"]` loads the bundled APOC Core library |
| `NEO4J_server_bolt_advertised__address` | Neo4j | Bolt address the discovery endpoint hands clients |
| `BOLT_URL` | Neo4j | Private connection string for other services |
| `QUERY_API_URL` | Neo4j | HTTPS endpoint for the Cypher Query API |
| `NEO4J_HOST` | Gateway | Private hostname of the Neo4j service |

Anything prefixed `NEO4J_` goes straight into `neo4j.conf`, and an unknown setting stops the server starting — use it only for real settings from the operations manual.

### Deployment Dependencies

- [Neo4j on Docker Hub](https://hub.docker.com/_/neo4j)
- [Neo4j GitHub repository](https://github.com/neo4j/neo4j)
- [Neo4j Operations Manual](https://neo4j.com/docs/operations-manual/current/)
- [APOC documentation](https://neo4j.com/docs/apoc/current/)
- [Cypher Query API reference](https://neo4j.com/docs/query-api/current/)

## Hardware Requirements for Self-Hosting Neo4j

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 vCPU | 4–8 vCPU |
| RAM | 2 GB | 8 GB or more |
| Storage | 10 GB volume | 20 GB+ SSD, sized to your graph |

Neo4j keeps a page cache of the store files plus a JVM heap for queries. This template derives both from the container's limit — roughly 35% heap, 30% page cache — so an 8 GB instance gets ~2.6 GB heap and ~2.3 GB page cache, retuned whenever you resize.

## Self-Hosting Neo4j with Docker

The local equivalent is one Docker command, which starts Neo4j with a persistent volume and APOC enabled:

```
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -v neo4j-data:/data \
  -e NEO4J_AUTH=neo4j/your-strong-password \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:2026
```

You can then query it over HTTP with no driver installed, using `curl` against the Cypher Query API:

```
curl -u neo4j:your-strong-password \
  -H 'Content-Type: application/json' \
  -d '{"statement":"MATCH (n) RETURN count(n) AS nodes"}' \
  http://localhost:7474/db/neo4j/query/v2
```


## How Much Does Neo4j Cost to Self-Host?

Neo4j Community Edition is free and open source under GPL-3.0, with no per-core licence, seat count or feature gate on the graph engine. You pay only for infrastructure — on Railway, usage-based compute plus the volume. Managed AuraDB starts around $65 per month and scales with memory, and Enterprise Edition is licensed per core. Enterprise adds clustering, role-based access control and online backup; Community gives you the full engine, Cypher and APOC on one instance.

## FAQ

**What is Neo4j?**
An open-source native graph database that stores data as nodes and relationships and queries it with Cypher, now standardised as GQL. It is the most widely deployed property-graph database and the usual starting point for GraphRAG.

**What does this Railway template deploy?**
Neo4j Community Edition on a persistent volume, plus a Caddy gateway serving the query workspace, the HTTP Query API and Bolt-over-WebSocket on one HTTPS domain. A TCP proxy exposes raw Bolt to outside drivers.

**Why is there a gateway service instead of just Neo4j?**
Neo4j listens on two ports and a Railway domain maps to one. The gateway routes WebSocket upgrades to Bolt on 7687 and everything else to the UI and Query API on 7474, so one URL covers both.

**How do I connect my application to self-hosted Neo4j?**
Inside the same project use `bolt://neo4j.railway.internal:7687` over private networking — reference `${{Neo4j.BOLT_URL}}` from your app. From outside, use the TCP proxy address with the `bolt://` scheme, or the HTTPS Query API. Prefer `bolt://` over `neo4j://`: routing is a clustering feature and Community Edition is single-instance.

**Does this template include APOC, and can I add Graph Data Science?**
APOC Core is loaded, because it ships inside the official image. To add more, extend `NEO4J_PLUGINS` — `["apoc","graph-data-science"]` — but those download at container start, lengthening every deploy.

**Will my data survive a redeploy?**
Yes — everything lives on the volume at `/data`, reattached to each new container, including a password changed through Cypher.

**How do I back up a self-hosted Neo4j database?**
Community Edition has no online backup, so use Railway's volume backups for point-in-time copies and `neo4j-admin database dump` against a stopped database for a portable archive. `apoc.export.cypher.all` is a good logical export for smaller graphs.


## Similar templates

- [Celery | Web, Worker and Scheduler as Three Services](https://railway.com/deploy/celery-or-web-work-1) — Web, worker and scheduler wired up: Celery on Redis, outcomes in Postgres.
- [Redpanda](https://railway.com/deploy/redpanda-1) — Redpanda 26.2: Kafka-compatible streaming, single node, with Kafbat UI.
- [smoothmq](https://railway.com/deploy/AJv-64) — A drop-in replacement for AWS SQS

Open this page in a browser: https://railway.com/deploy/database-neo4j