grandstack-server: overview
A Docker image that serves GraphQL over Neo4j. You give it a Neo4j connection (environment variables), a GraphQL schema (a file) and optionally some seed data; it gives you a full API with queries, filters, sorting, relationships and create/update/delete. Built on @neo4j/graphql v7, GraphQL Yoga and the Neo4j driver. It is the server half of GRANDstack, where the “A” now stands for Agent: the same API serves people and coding agents.
Authentication is off by default. Anyone who can reach the endpoint can read, change and delete data. To require logins, set the
AUTH_*variables (configuration); thegrandstack-authrepo is a complete example with a gateway, Keycloak and row-level rules. Do not expose an open server publicly.
Run it
The easiest way is the grandstack umbrella repo, which starts Neo4j, this server and the web app together (docker compose up --build). To run this server on its own against a Neo4j you already have, clone this repository, go into the folder, then build and run the image:
git clone https://github.com/grand-stack/grandstack-server
cd grandstack-server
docker build -t grandstack-server:local .
docker run --rm -p 4000:4000 \
-e NEO4J_URI=bolt://host.docker.internal:7687 -e NEO4J_PASSWORD=secret \
grandstack-server:local
# GraphQL and GraphiQL: http://localhost:4000/graphql
host.docker.internal reaches a Neo4j running on your own machine. Under Podman host.containers.internal is the equivalent alias. Make sure it is the Neo4j you mean: if more than one Neo4j listens on port 7687 you can reach the wrong one and get an authentication error.
The bundled Movies seed loads into an empty database on first start. See configuration for every setting, including how to use your own schema and data.
Documentation
| Read | To learn |
|---|---|
| How it works | Startup sequence, request flow, the per-request context |
| Schema guide | Writing the schema: @node, relationships, @cypher, v7 rules |
| Schema reference | Every type and field in the current schema (generated) |
| Mutations | Create, update and delete, relationship diffs, the counts plugin |
| Seeding | Seed format, versioning, using your own data |
| Configuration | Environment variables, files, image, releases |
| Recipes | Step-by-step common changes |
| Troubleshooting | Errors we hit and their fixes |
npm ci prints npm warn install-scripts notices; they are harmless.
Working with a coding agent? Start with AGENTS.md.
The bundled data is sample data: titles, casts and relationships are real, but ratings and runtimes are approximate.
Last verified: v0.7.1 with @neo4j/graphql 7.6.4, Neo4j 2026.10 community, Node 24 (image) and Node 26 (development).
Licence
Apache License 2.0. See LICENSE and NOTICE. The same licence applies to every GRANDstack repository and to grandstack.ai.
Source: grandstack-server/README.md (this page is a copy; edit it in the repository)