Table of Contents

• Local Setup
  • Requirements
  • Running the API locally
  • Published Ports
  • Viewing the log outputs from the services
  • Creating a Dgraph backup
  • Loading a Dgraph backup using the live loader
  • Resetting Dgraph
• Updating the GraphQL schema
• Reporting Bugs
• Reporting Security Issues
• Contributing
• License

Local setup

Requirements

• Docker & Docker Compose
• Visual Studio Code
• A POSIX-compliant terminal, such as:
  • Visual Studio Code terminal
  • cmder
  • Cygwin
  • Bash
  • Zsh

If you're on Linux or Mac, you already have a POSIX-compliant terminal.

Optional, but recommended:

• BuildKit

Running the API locally

docker-compose up --detach

When running for the first time, you might get this message:

ERROR: The image for the service you're trying to recreate has been removed. If you continue, volume data could be lost. Consider backing up your data before continuing.

Continue with the new image? [yN]

In which case you can go ahead and type y and continue.

To stop the API:

docker-compose stop

Published ports

Port numbers published to your host machine.

Port	Service
8800	API
8080	Dgraph Alpha/GraphQL (HTTP)
7080	Dgraph Alpha (gRPC)
6080	Dgraph Zero

Viewing the log outputs from the services

# Displaying all logs.
docker-compose logs

# Displaying logs for the API service.
docker-compose logs api

# Displaying logs for several services, e.g. API and Dgraph Alpha
docker-compose logs api alpha

# Tailing the last 5 lines of the logs from the API service.
docker-compose logs --tail 5 api

# Following the logs for the API service as they come in (CMD/CTRL+C to exit).
docker-compose logs --follow api

# Following the logs for several services as they come in, e.g. Dgraph Alpha and Dgraph Zero.
docker-compose logs --follow api alpha zero

For more details, see the docs or run the command docker-compose logs --help

Creating a Dgraph backup

./run shell alpha

# Create RDF backup.
curl --url http://localhost:8080/admin \
    --header 'content-type: application/json' \
    --data '{"query":"mutation {export(input: {format: \"rdf\"}) {response {message code}}}"}'
tar --create --file temp.rdf.tar.gz --gzip $(ls --directory -t export/* | head -1)
mv temp.rdf.tar.gz doraboateng.$(date +"%Y-%m-%d").$(sha1sum temp.rdf.tar.gz | cut -c 1-6).rdf.tar.gz

# Note the name of the backup file, then exit the container.
ls doraboateng.*.rdf.tar.gz
exit

# Copy RDF backup.
docker cp boateng-api_alpha_1:/dgraph/doraboateng.<DATE>.<HASH>.rdf.tar.gz tmp/

Loading sample data using the live loader

./run clear-graph
./run load-sample-data

Resetting Dgraph

The local Dgraph instance uses a Docker volume to persist data. In order to reset the graph, the volume must be removed along with the containers:

# Stop and remove containers.
docker-compose down

# Remove Dgraph volume.
docker volume rm boateng-api_dgraph_volume

# Rebuild containers.
docker-compose up --detach --force-recreate

Updating the GraphQL schema

Create a new branch from the latest stable branch.

Then, retrieve the latest schema from doraboateng/graph:

# Downloads the latest schema from doraboateng/graph and removes the "@id"
# directives.
curl \
    --output src/graph/schema/graph.gql \
    https://raw.githubusercontent.com/doraboateng/graph/stable/src/schema/graph.gql \
    && sed -i 's/\(@[a-zA-Z]*\)/# \1/g' src/graph/schema/graph.gql

Finally, use gqlgen to generate the Go bindings:

# If the API is not already running, start it using Docker Compose:
docker-compose up --detach

# Launch a shell inside the API container:
./run shell api

# Generate the Go bindings:
go run github.com/99designs/gqlgen generate
exit

Reporting Bugs

TODO

Reporting Security Issues

TODO

License

GNU General Public License v3

Copyright © Kwahu & Cayes