Dgraph

Search the Azure Marketplace for Dgraph on Ubuntu 24.04 and choose Create. Pick your VM size and SSH key.

Attach a network security group that allows TCP 22 from your management network. Allow TCP 443 from the networks and applications that will query Dgraph. Port 80 only issues an HTTPS redirect.

Azure creates the data disk from the image automatically. First boot takes about a minute after the VM is reachable. During that time it generates this VM's certificate, signing key and groot password, and it loads the demo graph.

Run these commands on your own workstation:

RG="dgraph-prod"; LOCATION="eastus"; VM_NAME="dgraph-01" IMAGE_URN="sac1647283583153:dgraph-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name dgraph-vnet --address-prefix 10.90.0.0/16 --subnet-name dgraph-subnet --subnet-prefix 10.90.1.0/24 az network nsg create -g "$RG" --name dgraph-nsg az network nsg rule create -g "$RG" --nsg-name dgraph-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name dgraph-nsg --name allow-https --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 443 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn "$IMAGE_URN"
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name dgraph-vnet --subnet dgraph-subnet --nsg dgraph-nsg --public-ip-sku Standard

ssh azureuser@<vm-ip>

The login banner shows the API and GraphQL URLs for this VM.

Confirm that Zero, Alpha and nginx are running and that first boot has finished. Confirm that the health endpoint answers over HTTPS and that the installed version is 25.5.1:

systemctl is-active dgraph-zero.service dgraph-alpha.service nginx.service test -f /var/lib/sac/data/dgraph-firstboot.done && echo first-boot-done curl -sk -o /dev/null -w 'healthz: HTTP %{http_code}\n' https://localhost/healthz /opt/dgraph/bin/dgraph version 2>/dev/null | grep -E 'Dgraph version|Go version'

All three services report active, and the first-boot marker is present. /healthz returns HTTP 200, and the binary reports v25.5.1 built with go1.27.3.

Every Dgraph port is on loopback, and nginx owns the public ports:

sudo ss -tlnp | grep -E ':(5080|6080|7080|8080|9080|80|443) '

The output shows dgraph on 127.0.0.1 ports 5080 and 6080 (Zero) and 7080, 8080 and 9080 (Alpha). It shows nginx on ports 80 and 443.

The groot password is unique to this VM. First boot writes it to a root-only file. Print only the field names, never the password itself:

sudo stat -c '%a %U:%G %n' /root/dgraph-credentials.txt
sudo grep -oE '^[A-Z_]+=' /root/dgraph-credentials.txt

The file is mode 600 and owned by root. It holds DGRAPH_HOST, DGRAPH_URL, DGRAPH_GRAPHQL_URL, DGRAPH_ADMIN_URL, DGRAPH_GROOT_USER (groot) and DGRAPH_GROOT_PASSWORD.

Read the password with sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt when you need it. Keep it safe, because groot is the Dgraph administrator (a member of the guardians group). Dgraph stores only a bcrypt hash of the password.

Dgraph answers a refused request with HTTP 200 and an errors body, so read the message. A query without a token is refused. A wrong password and Dgraph's documented default password are refused too:

curl -sk -H 'Content-Type: application/dql' -X POST https://localhost/query \
  -d '{ q(func: has(name)) { uid } }' | grep -o 'requires an identified caller' printf '{"userid":"groot","password":"%s"}' 'wrong-password' | curl -sk -X POST --data-binary @- https://localhost/login | grep -o 'invalid username or password' printf '{"userid":"groot","password":"%s"}' 'password' | curl -sk -X POST --data-binary @- https://localhost/login | grep -o 'invalid username or password'

Each line prints the refusal. Now log in with the per-VM password to get an access token. The password is sent on standard input, so it never appears in the process list or your shell history:

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
echo "access token received: ${#JWT} characters"

Send the token as the X-Dgraph-AccessToken header on every call. Access tokens last 6 hours. The /login response also carries a refreshJWT, which you can exchange for a new access token.

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/dql' -X POST https://localhost/query \
  -d '{ people(func: type(Person), orderasc: name) { name age friend { name } } }' \
  | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)["data"], indent=1))'

The answer lists Alice (31), Bob (27) and Carol (35). Each entry includes the friend that its friend edge points to.

Add to the schema, write nodes with an RDF mutation, and query them back. /alter changes the schema, and /mutate?commitNow=true writes and commits in one call:

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
curl -sk -H "X-Dgraph-AccessToken: $JWT" -X POST https://localhost/alter \
  -d 'title: string @index(term) . directed_by: [uid] .'; echo
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/rdf' -X POST 'https://localhost/mutate?commitNow=true' \
  -d '{ set { _:film <title> "The Graph Story" . _:film <directed_by> _:director . _:director <name> "Dana Director" . } }' | grep -o '"code":"Success"'
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/dql' -X POST https://localhost/query \
  -d '{ films(func: anyofterms(title, "graph")) { title directed_by { name } } }' \
  | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)["data"], indent=1))'

The schema change returns "code":"Success", and the mutation commits. The query finds the film by a word in its title and follows the directed_by edge to its director.

Dgraph generates a complete GraphQL API from a GraphQL schema. Upload a schema to /admin/schema. Then query and mutate at /graphql with the same access token:

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
curl -sk -H "X-Dgraph-AccessToken: $JWT" -X POST https://localhost/admin/schema \
  --data-binary 'type Task { id: ID! title: String! @search(by: [term]) done: Boolean }' | grep -o '"code":"Success"' sleep 3
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/json' -X POST https://localhost/graphql \
  -d '{"query":"mutation { addTask(input: [{title: \"Try Dgraph GraphQL\", done: false}]) { task { title done } } }"}'; echo
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/json' -X POST https://localhost/graphql \
  -d '{"query":"{ queryTask { title done } }"}'; echo

The schema upload returns "code":"Success". The mutation and the query both return the Try Dgraph GraphQL task. GraphQL subscriptions work over WebSocket at the same /graphql path for same-origin clients.

From your own machine, call https://<vm-ip>/. Open TCP 443 to your address in the network security group first.

The certificate is self-signed and unique to this VM. Either pass -k, or copy /etc/ssl/dgraph/dgraph.crt to your workstation and trust it with --cacert. Log in first, then send the token:

read -rs -p 'groot password: ' PW; echo
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://<vm-ip>/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/dql' -X POST https://<vm-ip>/query \
  -d '{ people(func: type(Person)) { name } }'

The gRPC port (9080) used by the official clients (dgo, pydgraph and dgraph-js) stays on loopback. Reach it, and Alpha's HTTP port, through an SSH tunnel from your workstation:

ssh -N -L 9080:127.0.0.1:9080 -L 8080:127.0.0.1:8080 azureuser@<vm-ip>

Point a client at localhost:9080 and log in as groot with the per-VM password. ACL applies on gRPC too.

Dgraph's Ratel query UI is a separate project and is not installed. If you run Ratel on your workstation, connect it to http://localhost:8080 through the same tunnel.

These are the locations of the main components. Each line gives the component, then its path or command.

Dgraph binary (read-only, root-owned): /opt/dgraph/bin/dgraph

Units: dgraph-zero.service and dgraph-alpha.service, in /etc/systemd/system/

ACL signing key (per VM, mode 0640, owned by root:dgraph): /etc/dgraph/acl-secret

Data disk: /var/lib/dgraph

Zero write-ahead log: /var/lib/dgraph/zw

Alpha postings, write-ahead log and temporary files: /var/lib/dgraph/p, /var/lib/dgraph/w and /var/lib/dgraph/t

Exports: /var/lib/dgraph/export

Logs: journalctl -u dgraph-alpha -u dgraph-zero

Credentials file (mode 0600): /root/dgraph-credentials.txt

Per-VM certificate: /etc/ssl/dgraph/

nginx site: /etc/nginx/sites-available/sac-dgraph

License: /usr/share/doc/dgraph/LICENSE.txt

The data disk is mounted by filesystem UUID:

findmnt /var/lib/dgraph df -h /var/lib/dgraph

To change a Dgraph flag (for example Alpha's cache size), run sudo systemctl edit dgraph-alpha.service. Override ExecStart= and restart the service.

Keep --bindall=false, --acl "secret-file=/etc/dgraph/acl-secret" and --security "whitelist=127.0.0.1; anonymous=none" in place. They keep Dgraph on loopback with ACL enforced.

Export the whole database as RDF (or json) into /var/lib/dgraph/export:

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/json' -X POST https://localhost/admin \
  -d '{"query":"mutation { export(input: {format: \"rdf\"}) { response { code message } } }"}'; echo
sudo ls /var/lib/dgraph/export

The call returns "code":"Success", and a dgraph.r... directory appears with the RDF and schema files. Copy exports off the VM, for example to Azure Blob Storage.

Take Azure snapshots of the /var/lib/dgraph data disk for point-in-time backups. Dgraph's backup mutation (full and incremental binary backups) also writes only under /var/lib/dgraph on this image, or to an S3-compatible or MinIO destination that you configure.

Use a dedicated user with only the permissions it needs instead of groot. Create a user and a group, and give the group read access to the name predicate. Replace the password with a strong one of your own:

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/json' -X POST https://localhost/admin \
  -d '{"query":"mutation { addGroup(input: [{name: \"readers\", rules: [{predicate: \"name\", permission: 4}]}]) { group { name } } }"}'; echo
curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/json' -X POST https://localhost/admin \
  -d '{"query":"mutation { addUser(input: [{name: \"app\", password: \"your-strong-password\", groups: [{name: \"readers\"}]}]) { user { name } } }"}'; echo

Permission 4 is read, 2 is write and 1 is modify (schema). Add the values together for combined rights.

Rotate the administrator password whenever you need to. The command generates a new random password and updates the credentials file. It sends the password to Dgraph in a request body written to a root-only file in memory, never on a command line:

PW=$(sudo sed -n 's/^DGRAPH_GROOT_PASSWORD=//p' /root/dgraph-credentials.txt)
JWT=$(printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login \
  | sed -n 's/.*"accessJWT":"\([^"]*\)".*/\1/p')
NEW=$(head -c 600 /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32)
REQ=$(mktemp -p /dev/shm); chmod 600 "$REQ" printf '{"query":"mutation { updateUser(input: {filter: {name: {eq: \\"groot\\"}}, set: {password: \\"%s\\"}}) { user { name } } }"}' "$NEW" > "$REQ" curl -sk -H "X-Dgraph-AccessToken: $JWT" -H 'Content-Type: application/json' -X POST --data-binary @"$REQ" https://localhost/admin; echo shred -u "$REQ" printf 'DGRAPH_GROOT_PASSWORD=%s\n' "$NEW" | sudo sh -c 'C=/root/dgraph-credentials.txt; { grep -v "^DGRAPH_GROOT_PASSWORD=" "$C"; cat; } > "$C.new" && chmod 600 "$C.new" && mv -f "$C.new" "$C"' printf '{"userid":"groot","password":"%s"}' "$PW" | curl -sk -X POST --data-binary @- https://localhost/login | grep -o 'invalid username or password' unset PW NEW JWT

Dgraph answers {"data":{"updateUser":{"user":[{"name":"groot"}]}}}. The credentials file now holds the new password, and the old password is refused. Access tokens issued before the change stay valid until they expire.

Point a DNS record at the VM, for example an Azure DNS A record or the VM's public IP DNS label. Then regenerate the certificate and pin the served hostname:

sudo dgraph-set-hostname dgraph.example.com

This issues a new self-signed certificate for that name and makes nginx answer only for it. For production, replace it with your own CA-issued certificate.

For a public, browser-trusted certificate, you can also terminate TLS at Azure Application Gateway or Azure Front Door in front of the VM. Then open port 443 only to that front end.