Launching PuppyGraph in Docker

Running PuppyGraph 0.x?

This page documents PuppyGraph 1.0. For the 0.x version, see the archived page.

Summary

In this tutorial, you will:

Launch a PuppyGraph Docker container;
Explore an example graph using PuppyGraph Web UI.

Prerequisites

Docker Installation

Please ensure that docker is available. The installation can be verified by running:

docker version

See https://www.docker.com/get-started/ for more details on Docker.

Make sure the container architecture aligns with the host system

PuppyGraph provides docker images for both amd64 and arm64 architecture. By default docker pulls the image based on host machine's architecture. However, environment variables like DOCKER_DEFAULT_PLATFORM could override its default behavior.

If there is a mismatch, you will see warnings as follows when running PuppyGraph in Docker:

request platform(Linux/amd64) doesn't match detected platform(Linux/arm64/v8)

Hardware

Please see System Requirements for the minimum hardware requirements.

Start a PuppyGraph Container

Run the command below to start a PuppyGraph Docker container. This command will also download the PuppyGraph image if it hasn't been downloaded previously.

docker run \
  -p 8081:8081 -p 8182:8182 -p 7687:7687 \
  -e PUPPYGRAPH_USERNAME=puppygraph \
  -e PUPPYGRAPH_PASSWORD=puppygraph123 \
  -e QUERY_TIMEOUT=5m \
  -d --name puppy --rm --pull=always \
  puppygraph/puppygraph:latest

The flags:

Flag	Purpose
`-p 8081:8081`	Web UI and REST API.
`-p 8182:8182`	Gremlin server.
`-p 7687:7687`	openCypher over Bolt.
`-e PUPPYGRAPH_USERNAME`	Web UI username.
`-e PUPPYGRAPH_PASSWORD`	Web UI password. Change this in production.
`-e QUERY_TIMEOUT=5m`	Per-query timeout.
`-d`	Run detached.
`--name puppy`	Container name.
`--rm`	Remove the container when it exits. Drop this flag to keep it around between runs.
`--pull=always`	Pull the latest image matching the specified tag.
`puppygraph/puppygraph:latest`	Image and tag. To pin a specific version, replace `latest` with the desired tag (see Use a Specific Version).

Use a Specific Version

Replace latest with a version tag (for example, 1.0):

docker run \
  -p 8081:8081 -p 8182:8182 -p 7687:7687 \
  -e PUPPYGRAPH_USERNAME=puppygraph \
  -e PUPPYGRAPH_PASSWORD=puppygraph123 \
  -e QUERY_TIMEOUT=5m \
  -d --name puppy --rm --pull=always \
  puppygraph/puppygraph:1.0

You can find available version tags on Docker Hub and check the release notes for version details.

Data Persistence Options

If you want to keep your schema data and configurations between container runs, you have two options:

Option 1: Simple Container Persistence

Remove the --rm flag to keep the container and its data:

docker run \
  -p 8081:8081 -p 8182:8182 -p 7687:7687 \
  -e PUPPYGRAPH_USERNAME=puppygraph \
  -e PUPPYGRAPH_PASSWORD=puppygraph123 \
  -e QUERY_TIMEOUT=5m \
  -d --name puppy --pull=always \
  puppygraph/puppygraph:latest

With this approach, all your data will be preserved within the container. No volumes or storage environment variables are needed for this simple approach.

To stop the container while keeping data: Use docker stop puppy. Your data is preserved within the container.
To restart with existing data: Use docker start puppy to restart the same container with all your data intact.

Option 2: Docker Volumes

For more advanced scenarios or when using Docker Compose, use volumes to persist data:

docker volume create puppygraph-data
docker run \
  -p 8081:8081 -p 8182:8182 -p 7687:7687 \
  -e PUPPYGRAPH_USERNAME=puppygraph \
  -e PUPPYGRAPH_PASSWORD=puppygraph123 \
  -e QUERY_TIMEOUT=5m \
  -e STORAGE_PATH_ROOT=/data/storage \
  -v puppygraph-data:/data/storage \
  -d --name puppy --pull=always \
  puppygraph/puppygraph:latest

This creates a Docker volume named puppygraph-data that persists your schema configurations, graph data, and other important files even when the container is removed.

To stop the container while keeping data: Use docker stop puppy as shown above. Your schema data and configurations are preserved in the puppygraph-data volume.

To restart with existing data: Use the same command with volume mounting:

docker run \
  -p 8081:8081 -p 8182:8182 -p 7687:7687 \
  -e PUPPYGRAPH_USERNAME=puppygraph \
  -e PUPPYGRAPH_PASSWORD=puppygraph123 \
  -e QUERY_TIMEOUT=5m \
  -e STORAGE_PATH_ROOT=/data/storage \
  -v puppygraph-data:/data/storage \
  -d --name puppy --pull=always \
  puppygraph/puppygraph:latest

Advanced Configuration

For Docker Compose deployments or custom storage configurations, you can also use the STORAGE_PATH_ROOT environment variable to specify a custom root path for persistent storage. This is particularly useful in cluster deployments. For example: -e STORAGE_PATH_ROOT=/custom/storage/path

Access the PuppyGraph

Access the PuppyGraph Web UI at http://localhost:8081.

Sign in to PuppyGraph with the username (puppygraph) and the password (puppygraph123) specified by the configuration environment variables.

Once signed in, the schema page appears with three quick-start options: connect a data source, use a built-in example graph, or upload a schema JSON file.

Explore the Example Graph

In this tutorial, we'll be utilizing the demo data supplied by PuppyGraph. Under Use Example Graph, click Load Example and pick Modern Graph. The UI shows the loading progress.

Once the schema is loaded, the page visualizes the schema of the graph.

PuppyGraph features a dashboard, enabling you to quickly access essential information from the graph right away.

The default tiles on the dashboard count the total number of nodes / edges and also display the sample data from the graph.

Cleaning up

To sign out, click on the button located in the top right corner.

Run the following command to stop and clean up the container.

docker stop puppy

Managing Persistent Data

Here are the instructions for cleaning up based on the data persistence option you chose when starting the container.

Cleaning up a Persistent Container

If you used Option 1 (removed the --rm flag), remove the container:

docker rm puppy

Cleaning up Docker Volumes

If you used Option 2 (Docker volumes), first remove the container, then delete the volume:

docker rm puppy
docker volume rm puppygraph-data

Data Loss Warning

Removing the Docker volume will permanently delete all your schema configurations and graph data. Make sure to backup any important data before removing the volume.