Deploy and Host Dgraph on Railway

Built for an LLM agent to deploy and use. There is no setup wizard and nothing to fill in: a 40-character API token is generated at deploy time and every query, mutation and schema call must present it. A stock Dgraph answers anonymous queries, mutations and schema drops from any address; this template switches that off from the first boot. The contract below lists every URL, variable name and the one script that proves it works.

Dgraph is an open-source distributed graph database with a native GraphQL API and its own query language, DQL. It is used for knowledge graphs, recommendation engines, entity resolution and the relationship layer of AI applications. This template runs a single-node Dgraph (one Zero and one Alpha) in one container.

About Hosting Dgraph

This template runs one service, dgraph, built from the official Dgraph v25.5.1 image (dgraph/dgraph, pinned by digest). Upstream documents Zero and Alpha as two processes; here one start command runs both in the same container against one volume at /dgraph, and stops the container if either exits so Railway restarts it instead of leaving a half-alive node. Zero listens on the loopback interface only. Alpha serves HTTP (GraphQL, DQL and admin) on port 8080 and gRPC on port 9080. The Alpha cache is sized to a quarter of the container memory limit and the Go runtime is told the real CPU and memory limits, because Dgraph otherwise assumes a 4096 MB cache and the host's core count. Data, the write-ahead log and the Zero state all live on the volume and survive redeploys. After a deploy, /health turns 200 before the GraphQL admin endpoint is ready; retry schema calls for a few seconds.

Agent contract

Public URL: https:// plus the RAILWAY_PUBLIC_DOMAIN of the dgraph service, as DGRAPH_PUBLIC_URL. It serves /graphql, /query, /mutate, /alter, /admin and /health (HTTP).
Private URL: http://dgraph.railway.internal:8080 (HTTP) and dgraph.railway.internal:9080 (gRPC for the official clients).
Credentials: the token in DGRAPH_TOKEN. There is no username; ACL logins are not enabled.
Auth: send the header X-Dgraph-AuthToken with the token on every call. Without it, query, mutation, alter, admin and state calls are rejected with an unauthenticated error. Only /health is open.
Health: GET /health returns 200 with no credentials. GraphQL admin readiness: POST /admin/schema succeeds with the token.

# run with DGRAPH_PUBLIC_URL and DGRAPH_TOKEN set; needs curl
H="X-Dgraph-AuthToken: $DGRAPH_TOKEN"
curl -s -o /dev/null -w 'health %{http_code}\n' "$DGRAPH_PUBLIC_URL/health"
curl -s "$DGRAPH_PUBLIC_URL/query" -H 'Content-Type: application/dql' -d '{ q(func: has(name)) { name } }' | grep -o 'Unauthenticated\|Invalid X-Dgraph-AuthToken' | head -1
until curl -fsS -H "$H" -H 'Content-Type: application/graphql' -d 'type Person { id: ID! name: String! @search(by: [hash]) }' "$DGRAPH_PUBLIC_URL/admin/schema" | grep -q Success; do sleep 3; done
echo schema ok
curl -fsS -H "$H" -H 'Content-Type: application/json' -d '{"query":"mutation { addPerson(input: [{name: \"Ada\"}]) { numUids } }"}' "$DGRAPH_PUBLIC_URL/graphql"; echo
curl -fsS -H "$H" -H 'Content-Type: application/json' -d '{"query":"{ queryPerson(filter: {name: {eq: \"Ada\"}}) { name } }"}' "$DGRAPH_PUBLIC_URL/graphql"; echo

A fresh deploy prints health 200, the word Unauthenticated or Invalid X-Dgraph-AuthToken for the anonymous call, schema ok, "numUids":1 and "name":"Ada". Use the DQL endpoint the same way: POST /query with Content-Type: application/dql and the same header. Official Dgraph clients take the gRPC address DGRAPH_PRIVATE_GRPC and the token as an auth header.

Why Deploy Dgraph on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Dgraph on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - generated token, contract block and one working script; no setup step.
Closed by default - anonymous queries, mutations, schema changes and drops are rejected, unlike a stock Dgraph.
One container - Zero and Alpha together on one volume, so one service to run and pay for instead of two.
Right-sized - cache and Go limits come from the container limits, not from the host.
State survives redeploys - data, write-ahead log and cluster state live on a volume.
Pinned image - the Dgraph version is pinned, so a redeploy never changes the server underneath you.

Common Use Cases

Knowledge graphs for AI agents - store entities and relations and traverse them with GraphQL or DQL.
Recommendations and entity resolution - multi-hop traversals over users, items and links.
Backend for a GraphQL API - define a schema and get queries and mutations generated for it.

Dependencies for Dgraph Hosting

None. Dgraph stores its own data on the volume at /dgraph.

Deployment Dependencies

dgraph-io/dgraph - upstream project