Launching PuppyGraph in Docker

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_PASSWORD=puppygraph123  -e QUERY_TIMEOUT=5m -d --name puppy --rm --pull=always puppygraph/puppygraph:stable

Here's a breakdown of the command:

docker run: This command creates and starts a new container.
-p 8081:8081: Maps port 8081 of the container to port 8081 on the host machine. This is the port for the PuppyGraph Web UI.
-p 8182:8182: Maps port 8182 of the container to port 8182 on the host machine. This is the port for the Gremlin server.
-p 7687:7687: Maps port 7687 of the container to port 7687 on the host machine. This is the port for openCypher queries over Bolt.
-e PUPPYGRAPH_PASSWORD=puppygraph123: Sets the environment variable PUPPYGRAPH_PASSWORD to puppygraph123. This sets password for the PuppyGraph Web UI. It is recommended to change this password to a more secure one in a production environment.
-e QUERY_TIMEOUT=5m: Sets the environment variable QUERY_TIMEOUT to 5m. This sets the timeout for queries to 5 minutes.
-d: Runs the container in detached mode (in the background).
--name puppy: Names the container puppy.
--rm: Automatically removes the container when it exits. If you want to keep the container after it stops, you can remove this option.
--pull=always: Always pull the latest image from the Docker registry. This is recommended when you want to use the latest stable version of PuppyGraph.
puppygraph/puppygraph:stable: Specifies the image to use. In this case, it uses the puppygraph/puppygraph image with the stable tag. If you want to use a specific version, you can replace stable with the desired version tag.

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_PASSWORD=puppygraph123  -e QUERY_TIMEOUT=5m -d --name puppy --pull=always puppygraph/puppygraph:stable

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_PASSWORD=puppygraph123 -e QUERY_TIMEOUT=5m -e STORAGE_PATH_ROOT=/data/storage -d --name puppy --pull=always -v puppygraph-data:/data/storage puppygraph/puppygraph:stable

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_PASSWORD=puppygraph123 -e QUERY_TIMEOUT=5m -e STORAGE_PATH_ROOT=/data/storage -d --name puppy --pull=always -v puppygraph-data:/data/storage puppygraph/puppygraph:stable

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 default username (puppygraph) and the password (puppygraph123) specified by the configuration PUPPYGRAPH_PASSWORD.

At times, the PuppyGraph initialization might still be underway, and the Schema page will display a prompt. Please refresh the page to see if the server is ready.

Once the server is ready, the schema page will appear as follows.

Explore the Example Graph

In this tutorial, we'll be utilizing the demo data supplied by PuppyGraph. Click on Use example schema/data, and the UI will show that loading is underway.

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.