From bfe433e12bd988cb05d1dfa5b3c2f3d0731ed832 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 12:28:29 -0400 Subject: [PATCH 01/37] Add instructions for readme in each folder --- .kiro/steering/documentation.md | 37 +++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.kiro/steering/documentation.md b/.kiro/steering/documentation.md index 6b23caa1c..00e0286d2 100644 --- a/.kiro/steering/documentation.md +++ b/.kiro/steering/documentation.md @@ -92,6 +92,43 @@ additionaldocs/ - Use descriptive names that match user tasks: `first-connection.md` - Group related content in folders by user journey +### Folder README Files + +Each documentation folder should include a `README.md` file that serves as a +table of contents for that folder: + +- **Purpose**: Explain what the folder contains and who it's for +- **File Listing**: List all files in the folder with brief descriptions +- **Reading Order**: Suggest the recommended order for reading files +- **Prerequisites**: Note any required knowledge or setup before starting +- **Navigation**: Link to parent folder and related sections + +Example folder README structure: + +```markdown +# Getting Started + +This section helps new users install and configure Graph Explorer for the first +time. + +## Files in this section + +1. [Installation](installation.md) - Local and Docker setup options +2. [First Connection](first-connection.md) - Connect to your first database +3. [Basic Usage](basic-usage.md) - Essential features walkthrough + +## Prerequisites + +- Basic familiarity with graph databases +- Access to a graph database endpoint +- Docker or Node.js >=24.4.0 installed + +## Next Steps + +After completing this section, see the [User Guide](../user-guide/) for detailed +feature documentation. +``` + ## Formatting Standards ### Code Examples From f768d93f1608945149f111100502c51f70ce9456 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 12:34:34 -0400 Subject: [PATCH 02/37] Add staging to changes --- .kiro/steering/documentation.md | 59 +++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/.kiro/steering/documentation.md b/.kiro/steering/documentation.md index 00e0286d2..1ddc32047 100644 --- a/.kiro/steering/documentation.md +++ b/.kiro/steering/documentation.md @@ -222,6 +222,65 @@ feature documentation. - Use Git history for version tracking - Clearly mark deprecated features or methods +### Git Workflow for Documentation Changes + +When making documentation updates, commit changes in logical, isolated stages to +maintain a clean history and enable easier reviews: + +#### Commit Stages + +1. **File Structure Changes** (commit separately) + - Creating new folders or moving files + - Renaming files or folders + - Deleting obsolete documentation + - Link updates and corrections + +2. **Content Reorganization** (commit separately) + - Moving sections between files + - Restructuring existing content + - Breaking large files into smaller ones + - Link updates and corrections + +3. **Content Updates** (commit by logical grouping) + - New feature documentation + - Updated installation instructions + - Revised examples or code snippets + - Link updates and corrections + +4. **Formatting and Style** (commit separately) + - Markdown formatting fixes + - Style consistency improvements + - Non-functional formatting changes + - Link updates and corrections + +#### Example Commit Messages + +```bash +# Structure changes +git commit -m "docs: create user-guide folder structure" +git commit -m "docs: move authentication content to user-guide/" + +# Content reorganization +git commit -m "docs: split installation.md into docker and local setup" +git commit -m "docs: move troubleshooting sections to dedicated files" + +# Content updates +git commit -m "docs: add React 19 migration guide" +git commit -m "docs: update Neptune connection examples" + +# Formatting +git commit -m "docs: fix broken links in getting-started section" +git commit -m "docs: standardize code block formatting" +``` + +#### Benefits of Staged Commits + +- **Easier Reviews**: Reviewers can focus on specific types of changes +- **Safer Reverts**: Roll back specific changes without losing other work +- **Clear History**: Git log shows the evolution of documentation clearly +- **Conflict Resolution**: Merge conflicts are easier to resolve with focused + commits + ## Example Structure ### Good README Introduction From cd4de21abf7108a0f59ee7989aa024fcff0aefe7 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 21:38:00 -0400 Subject: [PATCH 03/37] Add missing sections to ToC --- additionaldocs/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/additionaldocs/README.md b/additionaldocs/README.md index 40092c509..99ad5d55a 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -2,5 +2,8 @@ - [Connections](./connections.md) - [Development](./development.md) +- [Getting Started](./getting-started) +- [Features](./features) - [SageMaker](./sagemaker) - [ECS](./ecs) +- [Troubleshooting](./troubleshooting.md) From dafe90e7c3d3dd1d3f936dbd46873667dfcfb0dd Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 21:39:15 -0400 Subject: [PATCH 04/37] Move ECS docs to deployment --- additionaldocs/README.md | 2 +- additionaldocs/deployment/README.md | 20 +++++++++++++++++++ .../aws-ecs-fargate.md} | 0 3 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 additionaldocs/deployment/README.md rename additionaldocs/{ecs/ECS_FARGATE_DEPLOYMENT.md => deployment/aws-ecs-fargate.md} (100%) diff --git a/additionaldocs/README.md b/additionaldocs/README.md index 99ad5d55a..a3cefb5e1 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -4,6 +4,6 @@ - [Development](./development.md) - [Getting Started](./getting-started) - [Features](./features) +- [Deployment](./deployment) - [SageMaker](./sagemaker) -- [ECS](./ecs) - [Troubleshooting](./troubleshooting.md) diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md new file mode 100644 index 000000000..9b7c5e72b --- /dev/null +++ b/additionaldocs/deployment/README.md @@ -0,0 +1,20 @@ +# Deployment + +This section contains guides for deploying Graph Explorer in production +environments. + +## Files in this section + +1. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS + using Fargate + +## Prerequisites + +- Basic familiarity with containerized deployments +- Access to your chosen deployment platform +- Graph database endpoint accessible from your deployment environment + +## Next Steps + +After completing deployment, see the [Getting Started](../getting-started/) +guide for connecting to your first database and basic usage. diff --git a/additionaldocs/ecs/ECS_FARGATE_DEPLOYMENT.md b/additionaldocs/deployment/aws-ecs-fargate.md similarity index 100% rename from additionaldocs/ecs/ECS_FARGATE_DEPLOYMENT.md rename to additionaldocs/deployment/aws-ecs-fargate.md From 5651f4113477a53426c3a761d3180334235c1270 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 21:46:33 -0400 Subject: [PATCH 05/37] Move sagemaker docs to deployment --- Changelog.md | 6 +++--- README.md | 2 +- additionaldocs/README.md | 1 - additionaldocs/deployment/README.md | 2 ++ .../README.md => deployment/aws-sagemaker.md} | 10 +++++----- .../graph-explorer-neptune-analytics-policy.json | 0 .../graph-explorer-neptune-db-policy.json | 0 .../aws-sagemaker}/install-graph-explorer-lc.sh | 0 additionaldocs/troubleshooting.md | 4 ++-- 9 files changed, 13 insertions(+), 12 deletions(-) rename additionaldocs/{sagemaker/README.md => deployment/aws-sagemaker.md} (84%) rename additionaldocs/{sagemaker => deployment/aws-sagemaker}/graph-explorer-neptune-analytics-policy.json (100%) rename additionaldocs/{sagemaker => deployment/aws-sagemaker}/graph-explorer-neptune-db-policy.json (100%) rename additionaldocs/{sagemaker => deployment/aws-sagemaker}/install-graph-explorer-lc.sh (100%) diff --git a/Changelog.md b/Changelog.md index a840819c2..6a686ce92 100644 --- a/Changelog.md +++ b/Changelog.md @@ -662,11 +662,11 @@ a more pleasant experience, especially for users with larger databases. - **Improved** diagnostic logging in Neptune Notebooks by adding CloudWatch logs ([#517](https://github.com/aws/graph-explorer/pull/517)) - Check out the example - [lifecycle script](additionaldocs/sagemaker/install-graph-explorer-lc.sh) + [lifecycle script](additionaldocs/deployment/aws-sagemaker/install-graph-explorer-lc.sh) and IAM policies for - [Neptune](additionaldocs/sagemaker/graph-explorer-neptune-db-policy.json) + [Neptune](additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) and - [Neptune Analytics](additionaldocs/sagemaker/graph-explorer-neptune-analytics-policy.json) + [Neptune Analytics](additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) **Bug Fixes and Minor Changes** diff --git a/README.md b/README.md index afadcef05..1785b9335 100644 --- a/README.md +++ b/README.md @@ -230,7 +230,7 @@ through IAM roles. For information about what permissions Graph Explorer requires check out the documentation on -[SageMaker configuration](./additionaldocs/sagemaker/README.md#minimum-database-permissions). +[SageMaker configuration](./additionaldocs/deployment/aws-sagemaker.md#minimum-database-permissions). > [!CAUTION] diff --git a/additionaldocs/README.md b/additionaldocs/README.md index a3cefb5e1..379e75d50 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -5,5 +5,4 @@ - [Getting Started](./getting-started) - [Features](./features) - [Deployment](./deployment) -- [SageMaker](./sagemaker) - [Troubleshooting](./troubleshooting.md) diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index 9b7c5e72b..1c746d190 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -7,6 +7,8 @@ environments. 1. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS using Fargate +2. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker + Notebooks ## Prerequisites diff --git a/additionaldocs/sagemaker/README.md b/additionaldocs/deployment/aws-sagemaker.md similarity index 84% rename from additionaldocs/sagemaker/README.md rename to additionaldocs/deployment/aws-sagemaker.md index 00d14e1c8..a2c0cf104 100644 --- a/additionaldocs/sagemaker/README.md +++ b/additionaldocs/deployment/aws-sagemaker.md @@ -6,12 +6,12 @@ how to create one, see the [documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/notebook-lifecycle-config.html). You can use the provided sample lifecycle configuration, -[`install-graph-explorer-lc.sh`](install-graph-explorer-lc.sh), or create your -own shell script. If using the sample lifecycle, you should also create an IAM -role with a policy containing the permissions described in either -[`graph-explorer-neptune-db-policy.json`](graph-explorer-neptune-db-policy.json) +[`install-graph-explorer-lc.sh`](aws-sagemaker/install-graph-explorer-lc.sh), or +create your own shell script. If using the sample lifecycle, you should also +create an IAM role with a policy containing the permissions described in either +[`graph-explorer-neptune-db-policy.json`](aws-sagemaker/graph-explorer-neptune-db-policy.json) or -[`graph-explorer-neptune-analytics-policy.json`](graph-explorer-neptune-analytics-policy.json), +[`graph-explorer-neptune-analytics-policy.json`](aws-sagemaker/graph-explorer-neptune-analytics-policy.json), depending on the service used. After you have created the lifecycle configuration and IAM role, you can attach diff --git a/additionaldocs/sagemaker/graph-explorer-neptune-analytics-policy.json b/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json similarity index 100% rename from additionaldocs/sagemaker/graph-explorer-neptune-analytics-policy.json rename to additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json diff --git a/additionaldocs/sagemaker/graph-explorer-neptune-db-policy.json b/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json similarity index 100% rename from additionaldocs/sagemaker/graph-explorer-neptune-db-policy.json rename to additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json diff --git a/additionaldocs/sagemaker/install-graph-explorer-lc.sh b/additionaldocs/deployment/aws-sagemaker/install-graph-explorer-lc.sh similarity index 100% rename from additionaldocs/sagemaker/install-graph-explorer-lc.sh rename to additionaldocs/deployment/aws-sagemaker/install-graph-explorer-lc.sh diff --git a/additionaldocs/troubleshooting.md b/additionaldocs/troubleshooting.md index fdd5f15f3..2d608cc24 100644 --- a/additionaldocs/troubleshooting.md +++ b/additionaldocs/troubleshooting.md @@ -227,5 +227,5 @@ need to add those permissions manually. Below are examples of which IAM permissions you need for Graph Explorer. -- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/sagemaker/graph-explorer-neptune-db-policy.json) -- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/sagemaker/graph-explorer-neptune-analytics-policy.json) +- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) +- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) From 0b2f16f62481f7eb2482499d637c8e22d6d721ea Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 21:54:09 -0400 Subject: [PATCH 06/37] Move EC2 instructions to deployment --- README.md | 4 +- additionaldocs/deployment/README.md | 5 +- additionaldocs/deployment/aws-ec2.md | 68 +++++++++++++++++++++++ additionaldocs/getting-started/README.md | 69 ------------------------ 4 files changed, 73 insertions(+), 73 deletions(-) create mode 100644 additionaldocs/deployment/aws-ec2.md diff --git a/README.md b/README.md index 1785b9335..945878482 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ databases and Graph Explorer, we recommend that you check out the - [Local Docker Setup](./additionaldocs/getting-started/README.md#local-docker-setup) - A quick start guide to deploying Graph Explorer locally using the official Docker image. -- [Amazon EC2 Setup](./additionaldocs/getting-started/README.md#amazon-ec2-setup) - - A quick start guide to setting up Graph Explorer on Amazon EC2 with Neptune. +- [Amazon EC2 Setup](./additionaldocs/deployment/aws-ec2.md) - A quick start + guide to setting up Graph Explorer on Amazon EC2 with Neptune. - [Local Development](./additionaldocs/getting-started/README.md#local-development-setup) - A quick start guide building the Docker image from source code. - [Troubleshooting](./additionaldocs/troubleshooting.md) - A collection of diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index 1c746d190..50947c374 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -5,9 +5,10 @@ environments. ## Files in this section -1. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS +1. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances +2. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS using Fargate -2. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker +3. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks ## Prerequisites diff --git a/additionaldocs/deployment/aws-ec2.md b/additionaldocs/deployment/aws-ec2.md new file mode 100644 index 000000000..c4d5890e8 --- /dev/null +++ b/additionaldocs/deployment/aws-ec2.md @@ -0,0 +1,68 @@ +# Deploying Graph Explorer on Amazon EC2 + +The following instructions detail how to deploy Graph Explorer onto an Amazon +EC2 instance and use it as a proxy server with SSH tunneling to connect to +Amazon Neptune. + + +> [!NOTE] +> +> This documentation is not an official recommendation on +network setups as there are many ways to connect to Amazon Neptune from outside +of the VPC, such as setting up a load balancer or VPC peering. + +## Prerequisites + +- Provision an Amazon EC2 instance that will be used to host the application and + connect to Neptune as a proxy server. For more details, see instructions + [here](https://github.com/aws/graph-notebook/tree/main/additional-databases/neptune). +- Ensure the Amazon EC2 instance can send and receive on ports `22` (SSH), + `8182` (Neptune), and `443` or `80` depending on protocol used + (graph-explorer). + +## Steps + +These steps describe how to install Graph Explorer on your Amazon EC2 instance. + +1. Open an SSH client and connect to the EC2 instance. +2. Download and install the necessary command line tools such as + [Git](https://git-scm.com/downloads) and + [Docker](https://docs.docker.com/get-docker/). +3. Clone the repository + ``` + git clone https://github.com/aws/graph-explorer.git + ``` +4. Navigate to the repository + ``` + cd graph-explorer + ``` +5. Build the image + ``` + docker build -t graph-explorer . + ``` + + +> [!TIP] +> +> If you receive an error relating to the docker service not running, run +> `service docker start`. + +4. Run the container substituting the `{hostname-or-ip-address}` with the + hostname or IP address of the EC2 instance. + ``` + docker run -p 80:80 -p 443:443 \ + --env HOST={hostname-or-ip-address} \ + graph-explorer + ``` +5. Navigate to the public URL of your EC2 instance accessing the `/explorer` + endpoint. You will receive a warning as the SSL certificate used is + self-signed. The URL will look like this: + ``` + https://ec2-1-2-3-4.us-east-1.compute.amazonaws.com/explorer + ``` +6. Since the application is set to use HTTPS by default and contains a + self-signed certificate, you will need to add the Graph Explorer certificates + to the trusted certificates directory and manually trust them. See the + [HTTPS Connections](../troubleshooting.md#https-connections) section. +7. After completing the trusted certification step and refreshing the browser, + you should now see the Connections UI. diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 6b190767f..2fd255a66 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -96,75 +96,6 @@ It comes with a very small graph dataset. - Using Proxy Server: `true` - Graph Connection URL: `http://localhost:8182` -## Amazon EC2 Setup - -The following instructions detail how to deploy graph-explorer onto an Amazon -EC2 instance and use it as a proxy server with SSH tunneling to connect to -Amazon Neptune. - - -> [!NOTE] -> -> This documentation is not an official recommendation on -network setups as there are many ways to connect to Amazon Neptune from outside -of the VPC, such as setting up a load balancer or VPC peering. - -### Prerequisites - -- Provision an Amazon EC2 instance that will be used to host the application and - connect to Neptune as a proxy server. For more details, see instructions - [here](https://github.com/aws/graph-notebook/tree/main/additional-databases/neptune). -- Ensure the Amazon EC2 instance can send and receive on ports `22` (SSH), - `8182` (Neptune), and `443` or `80` depending on protocol used - (graph-explorer). - -### Steps - -These steps describe how to install Graph Explorer on your Amazon EC2 instance. - -1. Open an SSH client and connect to the EC2 instance. -2. Download and install the necessary command line tools such as - [Git](https://git-scm.com/downloads) and - [Docker](https://docs.docker.com/get-docker/). -3. Clone the repository - ``` - git clone https://github.com/aws/graph-explorer.git - ``` -4. Navigate to the repository - ``` - cd graph-explorer - ``` -5. Build the image - ``` - docker build -t graph-explorer . - ``` - - -> [!TIP] -> -> If you receive an error relating to the docker service not running, run -> `service docker start`. - -4. Run the container substituting the `{hostname-or-ip-address}` with the - hostname or IP address of the EC2 instance. - ``` - docker run -p 80:80 -p 443:443 \ - --env HOST={hostname-or-ip-address} \ - graph-explorer - ``` -5. Navigate to the public URL of your EC2 instance accessing the `/explorer` - endpoint. You will receive a warning as the SSL certificate used is - self-signed. The URL will look like this: - ``` - https://ec2-1-2-3-4.us-east-1.compute.amazonaws.com/explorer - ``` -6. Since the application is set to use HTTPS by default and contains a - self-signed certificate, you will need to add the Graph Explorer certificates - to the trusted certificates directory and manually trust them. See - [HTTPS Connections](#https-connections) section. -7. After completing the trusted certification step and refreshing the browser, - you should now see the Connections UI. - ## Local Development Setup You can build the Docker image locally by following the steps below. From 70a8b4d7978e38295cdef20ab79e8fea583660c1 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Tue, 9 Sep 2025 22:40:22 -0400 Subject: [PATCH 07/37] Move docker setup to deployment --- README.md | 5 +- additionaldocs/deployment/README.md | 7 +- additionaldocs/deployment/docker.md | 84 +++++++++++++++++++++++ additionaldocs/getting-started/README.md | 85 ------------------------ 4 files changed, 90 insertions(+), 91 deletions(-) create mode 100644 additionaldocs/deployment/docker.md diff --git a/README.md b/README.md index 945878482..41b7ea2dc 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,8 @@ There are many ways to deploy and run Graph Explorer. If you are new to graph databases and Graph Explorer, we recommend that you check out the [Getting Started](./additionaldocs/getting-started/README.md) guide. -- [Local Docker Setup](./additionaldocs/getting-started/README.md#local-docker-setup) - - A quick start guide to deploying Graph Explorer locally using the official - Docker image. +- [Local Docker Setup](./additionaldocs/deployment/docker.md) - A quick start + guide to deploying Graph Explorer locally using the official Docker image. - [Amazon EC2 Setup](./additionaldocs/deployment/aws-ec2.md) - A quick start guide to setting up Graph Explorer on Amazon EC2 with Neptune. - [Local Development](./additionaldocs/getting-started/README.md#local-development-setup) - diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index 50947c374..42b61ddc7 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -5,10 +5,11 @@ environments. ## Files in this section -1. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances -2. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS +1. [Docker](docker.md) - Deploy Graph Explorer locally using Docker +2. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances +3. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS using Fargate -3. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker +4. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks ## Prerequisites diff --git a/additionaldocs/deployment/docker.md b/additionaldocs/deployment/docker.md new file mode 100644 index 000000000..9569b27a7 --- /dev/null +++ b/additionaldocs/deployment/docker.md @@ -0,0 +1,84 @@ +# Docker Deployment + +The quickest way to get started with Graph Explorer is to use the official +Docker image. You can find the latest version of the image on +[Amazon's ECR Public Registry](https://gallery.ecr.aws/neptune/graph-explorer). + + +> [!NOTE] +> +> Make sure to use the version of the image that does not include `sagemaker` in the tag. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) installed on your machine +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) + installed on your machine + +## Steps + +1. Authenticate with the Amazon ECR Public Registry. + [More information](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html#public-registry-auth) + + ``` + aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws + ``` + +2. Pull down the docker image + + ``` + docker pull public.ecr.aws/neptune/graph-explorer + ``` + +3. Create and run a docker container using the image + + ``` + docker run -p 80:80 -p 443:443 \ + --env HOST=localhost \ + --name graph-explorer \ + public.ecr.aws/neptune/graph-explorer + ``` + + The `HOST` environment variable is used for SSL certificates generation since + HTTPS is the default. If you are hosting this on a public domain, you should + replace `HOST=localhost` with your domain name. + +4. Open a browser and type in the URL of the Graph Explorer server instance + + ``` + https://localhost/explorer + ``` + +5. You will receive a warning as the SSL certificate used is self-signed. Since + the application is set to use HTTPS by default and contains a self-signed + certificate, you will need to add the Graph Explorer certificates to the + trusted certificates directory and manually trust them. See the + [HTTPS Connections](../troubleshooting.md#https-connections) section. +6. After completing the trusted certification step and refreshing the browser, + you should now see the Connections UI. See below description on Connections + UI to configure your first connection to Amazon Neptune. + +## Gremlin Server Database + +Gremlin Server is an easy way to get started with graph databases. This example +will configure a simple Gremlin Server instance to be used with Graph Explorer. +It comes with a very small graph dataset. + +1. Pull the latest Gremlin Server image from Docker Hub. + ``` + docker pull tinkerpop/gremlin-server:latest + ``` +2. Create and run the Gremlin Server container using the HTTP REST modern + configuration. + ``` + docker run -p 8182:8182 \ + --name gremlin-server \ + tinkerpop/gremlin-server:latest \ + conf/gremlin-server-rest-modern.yaml + ``` +3. Open Graph Explorer and add a new connection + - Name: `Gremlin Server` + - Graph Type: `Gremlin` + - Public or Proxy Endpoint: `https://localhost` + - Using Proxy Server: `true` + - Graph Connection URL: `http://localhost:8182` diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 2fd255a66..6ed17eaa2 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -11,91 +11,6 @@ be optionally used. ## Examples -### Local Docker Setup - -The quickest way to get started with Graph Explorer is to use the official -Docker image. You can find the latest version of the image on -[Amazon's ECR Public Registry](https://gallery.ecr.aws/neptune/graph-explorer). - - -> [!NOTE] -> -> Make sure to use the version of the image that does not include `sagemaker` in the tag. - -#### Prerequisites - -- [Docker](https://docs.docker.com/get-docker/) installed on your machine -- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) - installed on your machine - -#### Steps - -1. Authenticate with the Amazon ECR Public Registry. - [More information](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html#public-registry-auth) - - ``` - aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws - ``` - -2. Pull down the docker image - - ``` - docker pull public.ecr.aws/neptune/graph-explorer - ``` - -3. Create and run a docker container using the image - - ``` - docker run -p 80:80 -p 443:443 \ - --env HOST=localhost \ - --name graph-explorer \ - public.ecr.aws/neptune/graph-explorer - ``` - - The `HOST` environment variable is used for SSL certificates generation since - HTTPS is the default. If you are hosting this on a public domain, you should - replace `HOST=localhost` with your domain name. - -4. Open a browser and type in the URL of the Graph Explorer server instance - - ``` - https://localhost/explorer - ``` - -5. You will receive a warning as the SSL certificate used is self-signed. Since - the application is set to use HTTPS by default and contains a self-signed - certificate, you will need to add the Graph Explorer certificates to the - trusted certificates directory and manually trust them. See the - [HTTPS Connections](../troubleshooting.md#https-connections) section. -6. After completing the trusted certification step and refreshing the browser, - you should now see the Connections UI. See below description on Connections - UI to configure your first connection to Amazon Neptune. - -#### Gremlin Server Database - -Gremlin Server is an easy way to get started with graph databases. This example -will configure a simple Gremlin Server instance to be used with Graph Explorer. -It comes with a very small graph dataset. - -1. Pull the latest Gremlin Server image from Docker Hub. - ``` - docker pull tinkerpop/gremlin-server:latest - ``` -2. Create and run the Gremlin Server container using the HTTP REST modern - configuration. - ``` - docker run -p 8182:8182 \ - --name gremlin-server \ - tinkerpop/gremlin-server:latest \ - conf/gremlin-server-rest-modern.yaml - ``` -3. Open Graph Explorer and add a new connection - - Name: `Gremlin Server` - - Graph Type: `Gremlin` - - Public or Proxy Endpoint: `https://localhost` - - Using Proxy Server: `true` - - Graph Connection URL: `http://localhost:8182` - ## Local Development Setup You can build the Docker image locally by following the steps below. From 129d196c6001a9660a24a9b86c9b47b58c7d9b51 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 09:55:04 -0400 Subject: [PATCH 08/37] Move docker build to development folder --- README.md | 10 +++--- additionaldocs/README.md | 2 +- .../{development.md => development/README.md} | 25 +++++++++++++ .../development/development-setup.md | 35 ++++++++++++++++++ additionaldocs/getting-started/README.md | 36 ------------------- additionaldocs/troubleshooting.md | 2 +- 6 files changed, 67 insertions(+), 43 deletions(-) rename additionaldocs/{development.md => development/README.md} (93%) create mode 100644 additionaldocs/development/development-setup.md diff --git a/README.md b/README.md index 41b7ea2dc..22b5413d3 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ databases and Graph Explorer, we recommend that you check out the guide to deploying Graph Explorer locally using the official Docker image. - [Amazon EC2 Setup](./additionaldocs/deployment/aws-ec2.md) - A quick start guide to setting up Graph Explorer on Amazon EC2 with Neptune. -- [Local Development](./additionaldocs/getting-started/README.md#local-development-setup) - - A quick start guide building the Docker image from source code. +- [Local Development](./additionaldocs/development/development-setup.md) - A + quick start guide building the Docker image from source code. - [Troubleshooting](./additionaldocs/troubleshooting.md) - A collection of helpful tips if you run in to issues while setting up Graph Explorer. - [Samples](./samples) - A collection of Docker Compose files that show various @@ -174,7 +174,7 @@ docker run -p 80:80 -p 443:443 \ ## Development -For development guidance, see [Development](./additionaldocs/development.md). +For development guidance, see [Development](./additionaldocs/development/). ## Security @@ -185,7 +185,7 @@ database endpoint. Graph Explorer supports the HTTPS protocol by default and provides a self-signed certificate as part of the Docker image. You can choose to use HTTP instead by changing the -[environment variable default settings](./additionaldocs/development.md#environment-variables). +[environment variable default settings](./additionaldocs/development/#environment-variables). ### HTTPS Connections @@ -219,7 +219,7 @@ systems will have slightly different steps. > [!TIP] > > To get rid of the “Not Secure” warning, see -[Using self-signed certificates on Chrome](./additionaldocs/development.md#using-self-signed-certificates-on-chrome). +[Using self-signed certificates on Chrome](./additionaldocs/development/#using-self-signed-certificates-on-chrome). ## Permissions diff --git a/additionaldocs/README.md b/additionaldocs/README.md index 379e75d50..efc2745d7 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -1,8 +1,8 @@ ## Table of Contents - [Connections](./connections.md) -- [Development](./development.md) - [Getting Started](./getting-started) - [Features](./features) - [Deployment](./deployment) +- [Development](./development) - [Troubleshooting](./troubleshooting.md) diff --git a/additionaldocs/development.md b/additionaldocs/development/README.md similarity index 93% rename from additionaldocs/development.md rename to additionaldocs/development/README.md index a9448f205..e49df83bf 100644 --- a/additionaldocs/development.md +++ b/additionaldocs/development/README.md @@ -1,3 +1,28 @@ +# Development + +This section contains guides for developers who want to contribute to Graph +Explorer or set up a local development environment. + +## Files in this section + +1. [Development Setup](development-setup.md) - Local development environment + setup + +## Prerequisites + +- Node.js >=24.4.0 +- pnpm >=10.12.1 +- Basic familiarity with React and TypeScript +- Docker (for containerized development) + +## Next Steps + +After setting up your development environment, see the +[Contributing Guidelines](../../CONTRIBUTING.md) for information on how to +contribute to the project. + +--- + ## Development This developer README details instructions for building on top of the diff --git a/additionaldocs/development/development-setup.md b/additionaldocs/development/development-setup.md new file mode 100644 index 000000000..c2dae8784 --- /dev/null +++ b/additionaldocs/development/development-setup.md @@ -0,0 +1,35 @@ +# Local Development Setup + +You can build the Docker image locally by following the steps below. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) installed on your machine +- [Git](https://git-scm.com/downloads) installed on your machine + +## Steps + +1. Clone the repository + ``` + git clone https://github.com/aws/graph-explorer.git + ``` +2. Navigate to the repository + ``` + cd graph-explorer + ``` +3. Build the image + ``` + docker build -t graph-explorer . + ``` +4. Run the container (HTTPS disabled) + ``` + docker run -p 80:80 \ + --name graph-explorer \ + --env PROXY_SERVER_HTTPS_CONNECTION=false \ + --env GRAPH_EXP_HTTPS_CONNECTION=false \ + graph-explorer + ``` +5. Connect to the Graph Explorer UI + ``` + http://localhost/explorer + ``` diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 6ed17eaa2..935454c00 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -11,42 +11,6 @@ be optionally used. ## Examples -## Local Development Setup - -You can build the Docker image locally by following the steps below. - -### Prerequisites - -- [Docker](https://docs.docker.com/get-docker/) installed on your machine -- [Git](https://git-scm.com/downloads) installed on your machine - -### Steps - -1. Clone the repository - ``` - git clone https://github.com/aws/graph-explorer.git - ``` -2. Navigate to the repository - ``` - cd graph-explorer - ``` -3. Build the image - ``` - docker build -t graph-explorer . - ``` -4. Run the container (HTTPS disabled) - ``` - docker run -p 80:80 \ - --name graph-explorer \ - --env PROXY_SERVER_HTTPS_CONNECTION=false \ - --env GRAPH_EXP_HTTPS_CONNECTION=false \ - graph-explorer - ``` -5. Connect to the Graph Explorer UI - ``` - http://localhost/explorer - ``` - ## Troubleshooting If the instructions above do not work for you, please see the diff --git a/additionaldocs/troubleshooting.md b/additionaldocs/troubleshooting.md index 2d608cc24..3e6074741 100644 --- a/additionaldocs/troubleshooting.md +++ b/additionaldocs/troubleshooting.md @@ -44,7 +44,7 @@ Which will result in the following URLs: If you do not want to use SSL and HTTPS, you can disable it by setting the following -[environment variables](/additionaldocs/development.md#environment-variables): +[environment variables](/additionaldocs/development/#environment-variables): ``` PROXY_SERVER_HTTPS_CONNECTION=false From 7d2a6a59d2618285ed45e9972e5f172821b45a01 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 09:55:37 -0400 Subject: [PATCH 09/37] Move environment variables to deployment folder --- README.md | 2 +- additionaldocs/deployment/README.md | 1 + additionaldocs/deployment/configuration.md | 76 ++++++++++++++++++++++ additionaldocs/development/README.md | 72 -------------------- additionaldocs/troubleshooting.md | 3 +- 5 files changed, 79 insertions(+), 75 deletions(-) create mode 100644 additionaldocs/deployment/configuration.md diff --git a/README.md b/README.md index 22b5413d3..3c7b03f10 100644 --- a/README.md +++ b/README.md @@ -185,7 +185,7 @@ database endpoint. Graph Explorer supports the HTTPS protocol by default and provides a self-signed certificate as part of the Docker image. You can choose to use HTTP instead by changing the -[environment variable default settings](./additionaldocs/development/#environment-variables). +[environment variable default settings](./additionaldocs/deployment/configuration.md). ### HTTPS Connections diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index 42b61ddc7..f59ef6f76 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -11,6 +11,7 @@ environments. using Fargate 4. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks +5. [Configuration](configuration.md) - Environment variables and settings ## Prerequisites diff --git a/additionaldocs/deployment/configuration.md b/additionaldocs/deployment/configuration.md new file mode 100644 index 000000000..340019252 --- /dev/null +++ b/additionaldocs/deployment/configuration.md @@ -0,0 +1,76 @@ +# Configuration + +This guide covers the environment variables and configuration options available +for Graph Explorer deployment. + +## Environment Variables + +### `GRAPH_EXP_ENV_ROOT_FOLDER` + +Base path used to serve the `graph-explorer` front end application. + +Example: `/explorer` + +- Optional +- Default: `/` +- Type: `string` + +### `GRAPH_EXP_CONNECTION_NAME` + +Default connection name. + +- Optional +- Default is empty +- Type: `string` + +### `GRAPH_EXP_CONNECTION_ENGINE` + +The query engine to use for the default connection. + +- Optional +- Default is `gremlin` +- Valid values are `gremlin`, `openCypher`, or `sparql` +- Type: `string` + +### `HOST` + +The public hostname of the server. This is used to generate the SSL certificate +during the Docker build. + +Example: `localhost` + +- Required when using HTTPS connections +- Default is empty +- Type: `string` + +### `GRAPH_EXP_HTTPS_CONNECTION` + +Uses the self-signed certificate to serve Graph Explorer over https if true. + +- Optional +- Default `true` +- Type: `boolean` + +### `PROXY_SERVER_HTTPS_PORT` + +The port to use for the HTTPS server. + +- Optional +- Default `443` +- Type: `number` + +### `PROXY_SERVER_HTTP_PORT` + +The port to use for the HTTP server. + +- Optional +- Default `80` +- Type: `number` + +### `PROXY_SERVER_HTTPS_CONNECTION` + +Uses the self-signed certificate to serve the proxy-server over https if true. + +- Optional +- Default `true` +- Type: `boolean` diff --git a/additionaldocs/development/README.md b/additionaldocs/development/README.md index e49df83bf..2005e0f69 100644 --- a/additionaldocs/development/README.md +++ b/additionaldocs/development/README.md @@ -145,78 +145,6 @@ release version is being prepared, the version number should be increased in all specifically extracted from the `/packages/graph-explorer/package.json`. file -### Environment variables - -#### `GRAPH_EXP_ENV_ROOT_FOLDER` - -Base path used to serve the `graph-explorer` front end application. - -Example: `/explorer` - -- Optional -- Default: `/` -- Type: `string` - -#### `GRAPH_EXP_CONNECTION_NAME` - -Default connection name. - -- Optional -- Default is empty -- Type: `string` - -#### `GRAPH_EXP_CONNECTION_ENGINE` - -The query engine to use for the default connection. - -- Optional -- Default is `gremlin` -- Valid values are `gremlin`, `openCypher`, or `sparql` -- Type: `string` - -#### `HOST` - -The public hostname of the server. This is used to generate the SSL certificate -during the Docker build. - -Example: `localhost` - -- Required when using HTTPS connections -- Default is empty -- Type: `string` - -#### `GRAPH_EXP_HTTPS_CONNECTION` - -Uses the self-signed certificate to serve Graph Explorer over https if true. - -- Optional -- Default `true` -- Type: `boolean` - -#### `PROXY_SERVER_HTTPS_PORT` - -The port to use for the HTTPS server. - -- Optional -- Default `443` -- Type: `number` - -#### `PROXY_SERVER_HTTP_PORT` - -The port to use for the HTTP server. - -- Optional -- Default `80` -- Type: `number` - -#### `PROXY_SERVER_HTTPS_CONNECTION` - -Uses the self-signed certificate to serve the proxy-server over https if true. - -- Optional -- Default `true` -- Type: `boolean` - ### Using self-signed certificates with Docker - Self-signed certificates will use the hostname provided in the `docker run` diff --git a/additionaldocs/troubleshooting.md b/additionaldocs/troubleshooting.md index 3e6074741..e049d0d70 100644 --- a/additionaldocs/troubleshooting.md +++ b/additionaldocs/troubleshooting.md @@ -43,8 +43,7 @@ Which will result in the following URLs: ### HTTP Only If you do not want to use SSL and HTTPS, you can disable it by setting the -following -[environment variables](/additionaldocs/development/#environment-variables): +following [environment variables](/additionaldocs/deployment/configuration.md): ``` PROXY_SERVER_HTTPS_CONNECTION=false From 922607f369d98faa6c9912080b5d7d81e888a389 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 09:59:02 -0400 Subject: [PATCH 10/37] Move release preparation to development --- additionaldocs/development/README.md | 22 ++-------------------- additionaldocs/development/release.md | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 20 deletions(-) create mode 100644 additionaldocs/development/release.md diff --git a/additionaldocs/development/README.md b/additionaldocs/development/README.md index 2005e0f69..ade097ad2 100644 --- a/additionaldocs/development/README.md +++ b/additionaldocs/development/README.md @@ -7,6 +7,8 @@ Explorer or set up a local development environment. 1. [Development Setup](development-setup.md) - Local development environment setup +2. [Release Preparation](release.md) - Guide for preparing and releasing new + versions ## Prerequisites @@ -125,26 +127,6 @@ pnpm add react --filter graph-explorer pnpm add -D vitest --filter graph-explorer-proxy-server ``` -#### Preparation of a release - -This repository is composed by 2 packages and a mono-repository structure -itself. Then, you need to take into account 3 different `package.json` files: - -- `/package.json` is intended to keep the dependencies for managing the - repository. It has utilities like linter, code formatter, or git checks. -- `/packages/graph-explorer/package.json` is the package file that - describes the UI client package. -- `/packages/graph-explorer-proxy-server/package.json` is the package file - for the node server which is in charge of authentication and redirection of - requests. - -Each of these `package.json` files has an independent `version` property. -However, in this project we should keep them correlated. Therefore, when a new -release version is being prepared, the version number should be increased in all -3 files. Regarding the version number displayed in the user interface, it is -specifically extracted from the `/packages/graph-explorer/package.json`. -file - ### Using self-signed certificates with Docker - Self-signed certificates will use the hostname provided in the `docker run` diff --git a/additionaldocs/development/release.md b/additionaldocs/development/release.md new file mode 100644 index 000000000..8b42adfeb --- /dev/null +++ b/additionaldocs/development/release.md @@ -0,0 +1,24 @@ +# Release Preparation + +This guide covers the process for preparing and releasing new versions of Graph +Explorer. + +## Preparation of a release + +This repository is composed by 2 packages and a mono-repository structure +itself. Then, you need to take into account 3 different `package.json` files: + +- `/package.json` is intended to keep the dependencies for managing the + repository. It has utilities like linter, code formatter, or git checks. +- `/packages/graph-explorer/package.json` is the package file that + describes the UI client package. +- `/packages/graph-explorer-proxy-server/package.json` is the package file + for the node server which is in charge of authentication and redirection of + requests. + +Each of these `package.json` files has an independent `version` property. +However, in this project we should keep them correlated. Therefore, when a new +release version is being prepared, the version number should be increased in all +3 files. Regarding the version number displayed in the user interface, it is +specifically extracted from the `/packages/graph-explorer/package.json`. +file From e942b6c88e12984e351ec38d6806ea12257429f9 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 10:04:35 -0400 Subject: [PATCH 11/37] Move development setup --- additionaldocs/development/README.md | 168 ------------------ .../development/development-setup.md | 166 ++++++++++++++++- 2 files changed, 163 insertions(+), 171 deletions(-) diff --git a/additionaldocs/development/README.md b/additionaldocs/development/README.md index ade097ad2..8a80709a5 100644 --- a/additionaldocs/development/README.md +++ b/additionaldocs/development/README.md @@ -22,171 +22,3 @@ Explorer or set up a local development environment. After setting up your development environment, see the [Contributing Guidelines](../../CONTRIBUTING.md) for information on how to contribute to the project. - ---- - -## Development - -This developer README details instructions for building on top of the -graph-explorer application, or for configuring advanced settings, like using -environment variables to switch to HTTP. - -### Requirements - -- pnpm >=10.12.1 -- node >=24.4.0 - -#### Node Version - -Ensure you are running the correct Node version. If you are using -[NVM](https://github.com/nvm-sh/nvm), you can simply do: - -```bash -nvm use -``` - -Otherwise, use whatever method you use to install -[Node v24.4.0](https://nodejs.org/en/download). - -#### Node Corepack - -[Corepack](https://nodejs.org/api/corepack.html) is used to ensure the package -manager used for the project is consistent. - -```bash -corepack enable -``` - -### Supported Graph Types - -- Labelled Property Graph (PG) using Gremlin or openCypher -- Resource Description Framework (RDF) using SPARQL - -### Run in development mode - -Install any missing or updated dependencies. - -```bash -pnpm install -``` - -Start the development servers. - -```bash -pnpm dev -``` - -Launch your web browser of choice and navigate to - -``` -http://localhost:5173 -``` - -At this point, Graph Explorer should be successfully running and it is asking -you for connection details. This part is specific to your personal setup. - -### Build for production - -Building Graph Explorer is simple. - -```bash -pnpm install -pnpm build -``` - -This will run the build across the both the client code and the proxy server -code. You'll end up with two `dist` folders: - -``` -{ROOT_PATH}/packages/graph-explorer/dist/ -{ROOT_PATH}/packages/graph-explorer-proxy-server/dist/ -``` - -The recommended way to server Graph Explorer is using the proxy server. - -```bash -pnpm start -``` - -However, if you want to run Graph Explorer without the proxy server, you can: - -```bash -pnpm start:client -``` - -### Managing dependencies - -If you need to add, remove, or update a dependency you can easily do so from the -root folder in the CLI: - -```bash -# Adding a package for the react app -pnpm add react --filter graph-explorer - -# Adding a dev only dependency for the server app -pnpm add -D vitest --filter graph-explorer-proxy-server -``` - -### Using self-signed certificates with Docker - -- Self-signed certificates will use the hostname provided in the `docker run` - command, so unless you have specific requirements, there are no extra steps - here besides providing the hostname. -- If you would like to modify the certificate files, be aware that the - Dockerfile will make automatic modifications on run, in lines 8 and 9 of the - [entrypoint script](https://github.com/aws/graph-explorer/blob/main/docker-entrypoint.sh), - so you will need to remove these lines. -- If you only serve one of either the proxy server or Graph Explorer UI over an - HTTPS connection and wish to download from the browser, you should navigate to - the one served over HTTPS to download the certificate. -- The other certificate files can also be found at - /packages/graph-explorer-proxy-server/cert-info/ on the Docker container that - is created. - -### Using Self-signed certificates on Chrome - -For browsers like Safari and Firefox, -[trusting the certificate from the browser](../README.md/#https-connections) is -enough to bypass the “Not Secure” warning. However, Chrome treats self-signed -certificates differently. If you want to use a self-signed certificate on Chrome -**without** the “Not Secure” warning and you do not have your own certificate, -or one provided by Let’s Encrypt, you can use the following instructions to add -the root certificate and remove the warning. These instructions assume you’re -using an EC2 instance to run the Docker container for Graph Explorer. - -1. After the Docker container is built and running, open a terminal prompt and - SSH into your proxy server instance (e.g., EC2). -2. Get the container ID by running `sudo docker ps` -3. Copy the root certificate file (rootCA.crt) from the container to EC2: - `sudo docker cp {container_id}:~/graph-explorer/packages/graph-explorer-proxy-server/cert-info/rootCA.crt ~/rootCA.crt` -4. Exit SSH session -5. Copy the root certificate file from EC2 to your local machine (where you - would run Graph Explorer on Chrome): - `scp -i {path_to_pem_file} {EC2_login}:~/rootCA.crt {path_on_local_to_place_file}` - For example, - `scp -i /Users/user1/EC2.pem ec2-user@XXX.XXX.XXX.XXX:~/rootCA.crt /Users/user1/downloads` -6. After copying the certificate from the container to your local machine’s file - system, you can delete the rootCA.crt file from the EC2 file store with - `rm -rf ~/rootCA.crt` -7. Once you have the certificate, you will need to trust it on your machine. For - MacOS, you can open the Keychain Access app. Select System under System - Keychains. Then go to File > Import Items... and import the certificate you - downloaded in the previous step. -8. Once imported, select the certificate and right-click to select "Get Info". - Expand the Trust section, and change the value of "When using this - certificate" to "Always Trust". -9. You should now refresh the browser and see that you can proceed to open the - application. For Chrome, the application will remain “Not Secure” due to the - fact that this is a self-signed certificate. If you have trouble accessing - Graph Explorer after completing the previous step and reloading the browser, - consider running a docker restart command and refreshing the browser again. - -### Troubleshooting - -- If you need more detailed logs, you can change the log level from `info` in - the default .env file to `debug`. The logs will begin printing the error's - stack trace. -- If Graph Explorer crashes, you can recreate the container or run `pnpm start` -- If Graph Explorer fails to start, check that the provided endpoint is properly - spelled and that you have access to from the environment you are trying to run - in. If you are in a different VPC, consider VPC Peering. diff --git a/additionaldocs/development/development-setup.md b/additionaldocs/development/development-setup.md index c2dae8784..0fa725524 100644 --- a/additionaldocs/development/development-setup.md +++ b/additionaldocs/development/development-setup.md @@ -1,13 +1,109 @@ # Local Development Setup -You can build the Docker image locally by following the steps below. +This guide details instructions for building on top of the graph-explorer +application, or for configuring advanced settings for development. -## Prerequisites +## Requirements +- pnpm >=10.12.1 +- node >=24.4.0 - [Docker](https://docs.docker.com/get-docker/) installed on your machine - [Git](https://git-scm.com/downloads) installed on your machine -## Steps +### Node Version + +Ensure you are running the correct Node version. If you are using +[NVM](https://github.com/nvm-sh/nvm), you can simply do: + +```bash +nvm use +``` + +Otherwise, use whatever method you use to install +[Node v24.4.0](https://nodejs.org/en/download). + +### Node Corepack + +[Corepack](https://nodejs.org/api/corepack.html) is used to ensure the package +manager used for the project is consistent. + +```bash +corepack enable +``` + +## Supported Graph Types + +- Labelled Property Graph (PG) using Gremlin or openCypher +- Resource Description Framework (RDF) using SPARQL + +## Run in development mode + +Install any missing or updated dependencies. + +```bash +pnpm install +``` + +Start the development servers. + +```bash +pnpm dev +``` + +Launch your web browser of choice and navigate to + +``` +http://localhost:5173 +``` + +At this point, Graph Explorer should be successfully running and it is asking +you for connection details. This part is specific to your personal setup. + +## Build for production + +Building Graph Explorer is simple. + +```bash +pnpm install +pnpm build +``` + +This will run the build across the both the client code and the proxy server +code. You'll end up with two `dist` folders: + +``` +{ROOT_PATH}/packages/graph-explorer/dist/ +{ROOT_PATH}/packages/graph-explorer-proxy-server/dist/ +``` + +The recommended way to server Graph Explorer is using the proxy server. + +```bash +pnpm start +``` + +However, if you want to run Graph Explorer without the proxy server, you can: + +```bash +pnpm start:client +``` + +## Managing dependencies + +If you need to add, remove, or update a dependency you can easily do so from the +root folder in the CLI: + +```bash +# Adding a package for the react app +pnpm add react --filter graph-explorer + +# Adding a dev only dependency for the server app +pnpm add -D vitest --filter graph-explorer-proxy-server +``` + +## Building Docker Image from Source + +You can build the Docker image locally by following the steps below. 1. Clone the repository ``` @@ -33,3 +129,67 @@ You can build the Docker image locally by following the steps below. ``` http://localhost/explorer ``` + +## Using self-signed certificates with Docker + +- Self-signed certificates will use the hostname provided in the `docker run` + command, so unless you have specific requirements, there are no extra steps + here besides providing the hostname. +- If you would like to modify the certificate files, be aware that the + Dockerfile will make automatic modifications on run, in lines 8 and 9 of the + [entrypoint script](https://github.com/aws/graph-explorer/blob/main/docker-entrypoint.sh), + so you will need to remove these lines. +- If you only serve one of either the proxy server or Graph Explorer UI over an + HTTPS connection and wish to download from the browser, you should navigate to + the one served over HTTPS to download the certificate. +- The other certificate files can also be found at + /packages/graph-explorer-proxy-server/cert-info/ on the Docker container that + is created. + +## Using Self-signed certificates on Chrome + +For browsers like Safari and Firefox, +[trusting the certificate from the browser](../../README.md#https-connections) +is enough to bypass the "Not Secure" warning. However, Chrome treats self-signed +certificates differently. If you want to use a self-signed certificate on Chrome +**without** the "Not Secure" warning and you do not have your own certificate, +or one provided by Let's Encrypt, you can use the following instructions to add +the root certificate and remove the warning. These instructions assume you're +using an EC2 instance to run the Docker container for Graph Explorer. + +1. After the Docker container is built and running, open a terminal prompt and + SSH into your proxy server instance (e.g., EC2). +2. Get the container ID by running `sudo docker ps` +3. Copy the root certificate file (rootCA.crt) from the container to EC2: + `sudo docker cp {container_id}:~/graph-explorer/packages/graph-explorer-proxy-server/cert-info/rootCA.crt ~/rootCA.crt` +4. Exit SSH session +5. Copy the root certificate file from EC2 to your local machine (where you + would run Graph Explorer on Chrome): + `scp -i {path_to_pem_file} {EC2_login}:~/rootCA.crt {path_on_local_to_place_file}` + For example, + `scp -i /Users/user1/EC2.pem ec2-user@XXX.XXX.XXX.XXX:~/rootCA.crt /Users/user1/downloads` +6. After copying the certificate from the container to your local machine's file + system, you can delete the rootCA.crt file from the EC2 file store with + `rm -rf ~/rootCA.crt` +7. Once you have the certificate, you will need to trust it on your machine. For + MacOS, you can open the Keychain Access app. Select System under System + Keychains. Then go to File > Import Items... and import the certificate you + downloaded in the previous step. +8. Once imported, select the certificate and right-click to select "Get Info". + Expand the Trust section, and change the value of "When using this + certificate" to "Always Trust". +9. You should now refresh the browser and see that you can proceed to open the + application. For Chrome, the application will remain "Not Secure" due to the + fact that this is a self-signed certificate. If you have trouble accessing + Graph Explorer after completing the previous step and reloading the browser, + consider running a docker restart command and refreshing the browser again. + +## Troubleshooting + +- If you need more detailed logs, you can change the log level from `info` in + the default .env file to `debug`. The logs will begin printing the error's + stack trace. +- If Graph Explorer crashes, you can recreate the container or run `pnpm start` +- If Graph Explorer fails to start, check that the provided endpoint is properly + spelled and that you have access to from the environment you are trying to run + in. If you are in a different VPC, consider VPC Peering. From 7a143eaafb4f1451f5467691ad31121ac7dbb4e8 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 10:14:00 -0400 Subject: [PATCH 12/37] Move troubleshooting in development --- additionaldocs/development/README.md | 2 ++ additionaldocs/development/development-setup.md | 10 ---------- additionaldocs/development/troubleshooting.md | 14 ++++++++++++++ 3 files changed, 16 insertions(+), 10 deletions(-) create mode 100644 additionaldocs/development/troubleshooting.md diff --git a/additionaldocs/development/README.md b/additionaldocs/development/README.md index 8a80709a5..183d25877 100644 --- a/additionaldocs/development/README.md +++ b/additionaldocs/development/README.md @@ -9,6 +9,8 @@ Explorer or set up a local development environment. setup 2. [Release Preparation](release.md) - Guide for preparing and releasing new versions +3. [Troubleshooting](troubleshooting.md) - Common development issues and + solutions ## Prerequisites diff --git a/additionaldocs/development/development-setup.md b/additionaldocs/development/development-setup.md index 0fa725524..da65a3ebd 100644 --- a/additionaldocs/development/development-setup.md +++ b/additionaldocs/development/development-setup.md @@ -183,13 +183,3 @@ using an EC2 instance to run the Docker container for Graph Explorer. fact that this is a self-signed certificate. If you have trouble accessing Graph Explorer after completing the previous step and reloading the browser, consider running a docker restart command and refreshing the browser again. - -## Troubleshooting - -- If you need more detailed logs, you can change the log level from `info` in - the default .env file to `debug`. The logs will begin printing the error's - stack trace. -- If Graph Explorer crashes, you can recreate the container or run `pnpm start` -- If Graph Explorer fails to start, check that the provided endpoint is properly - spelled and that you have access to from the environment you are trying to run - in. If you are in a different VPC, consider VPC Peering. diff --git a/additionaldocs/development/troubleshooting.md b/additionaldocs/development/troubleshooting.md new file mode 100644 index 000000000..9c2733090 --- /dev/null +++ b/additionaldocs/development/troubleshooting.md @@ -0,0 +1,14 @@ +# Development Troubleshooting + +This guide covers common issues and solutions when developing with Graph +Explorer. + +## Common Development Issues + +- If you need more detailed logs, you can change the log level from `info` in + the default .env file to `debug`. The logs will begin printing the error's + stack trace. +- If Graph Explorer crashes, you can recreate the container or run `pnpm start` +- If Graph Explorer fails to start, check that the provided endpoint is properly + spelled and that you have access to from the environment you are trying to run + in. If you are in a different VPC, consider VPC Peering. From d4fbf44946fe6b8f4f4de8091ac34dab135e34b4 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 10:31:17 -0400 Subject: [PATCH 13/37] Move troubleshooting tips in to folder and split --- README.md | 4 +- additionaldocs/README.md | 2 +- additionaldocs/deployment/aws-ec2.md | 3 +- additionaldocs/deployment/docker.md | 3 +- additionaldocs/getting-started/README.md | 2 +- additionaldocs/troubleshooting.md | 230 ------------------ additionaldocs/troubleshooting/README.md | 32 +++ .../troubleshooting/backup-restore.md | 21 ++ .../troubleshooting/docker-issues.md | 92 +++++++ .../troubleshooting/sagemaker-logs.md | 40 +++ additionaldocs/troubleshooting/schema-sync.md | 82 +++++++ 11 files changed, 275 insertions(+), 236 deletions(-) delete mode 100644 additionaldocs/troubleshooting.md create mode 100644 additionaldocs/troubleshooting/README.md create mode 100644 additionaldocs/troubleshooting/backup-restore.md create mode 100644 additionaldocs/troubleshooting/docker-issues.md create mode 100644 additionaldocs/troubleshooting/sagemaker-logs.md create mode 100644 additionaldocs/troubleshooting/schema-sync.md diff --git a/README.md b/README.md index 3c7b03f10..c0b5858fb 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,8 @@ databases and Graph Explorer, we recommend that you check out the guide to setting up Graph Explorer on Amazon EC2 with Neptune. - [Local Development](./additionaldocs/development/development-setup.md) - A quick start guide building the Docker image from source code. -- [Troubleshooting](./additionaldocs/troubleshooting.md) - A collection of - helpful tips if you run in to issues while setting up Graph Explorer. +- [Troubleshooting](./additionaldocs/troubleshooting/) - A collection of helpful + tips if you run in to issues while setting up Graph Explorer. - [Samples](./samples) - A collection of Docker Compose files that show various ways to configure and use Graph Explorer. diff --git a/additionaldocs/README.md b/additionaldocs/README.md index efc2745d7..aeedd4af0 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -5,4 +5,4 @@ - [Features](./features) - [Deployment](./deployment) - [Development](./development) -- [Troubleshooting](./troubleshooting.md) +- [Troubleshooting](./troubleshooting/) diff --git a/additionaldocs/deployment/aws-ec2.md b/additionaldocs/deployment/aws-ec2.md index c4d5890e8..e2881fadc 100644 --- a/additionaldocs/deployment/aws-ec2.md +++ b/additionaldocs/deployment/aws-ec2.md @@ -63,6 +63,7 @@ These steps describe how to install Graph Explorer on your Amazon EC2 instance. 6. Since the application is set to use HTTPS by default and contains a self-signed certificate, you will need to add the Graph Explorer certificates to the trusted certificates directory and manually trust them. See the - [HTTPS Connections](../troubleshooting.md#https-connections) section. + [HTTPS Connections](../troubleshooting/docker-issues.md#https-connections) + section. 7. After completing the trusted certification step and refreshing the browser, you should now see the Connections UI. diff --git a/additionaldocs/deployment/docker.md b/additionaldocs/deployment/docker.md index 9569b27a7..84b6fa517 100644 --- a/additionaldocs/deployment/docker.md +++ b/additionaldocs/deployment/docker.md @@ -53,7 +53,8 @@ Docker image. You can find the latest version of the image on the application is set to use HTTPS by default and contains a self-signed certificate, you will need to add the Graph Explorer certificates to the trusted certificates directory and manually trust them. See the - [HTTPS Connections](../troubleshooting.md#https-connections) section. + [HTTPS Connections](../troubleshooting/docker-issues.md#https-connections) + section. 6. After completing the trusted certification step and refreshing the browser, you should now see the Connections UI. See below description on Connections UI to configure your first connection to Amazon Neptune. diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 935454c00..7e37edc32 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -14,5 +14,5 @@ be optionally used. ## Troubleshooting If the instructions above do not work for you, please see the -[Troubleshooting](../troubleshooting.md) page for more information. It contains +[Troubleshooting](../troubleshooting/) page for more information. It contains workarounds for common issues and information on how to diagnose other issues. diff --git a/additionaldocs/troubleshooting.md b/additionaldocs/troubleshooting.md deleted file mode 100644 index e049d0d70..000000000 --- a/additionaldocs/troubleshooting.md +++ /dev/null @@ -1,230 +0,0 @@ -# Troubleshooting - -This page contains workarounds for common issues and information on how to -diagnose other issues. - -- [Docker Container Issues](#docker-container-issues) -- [Schema Sync Fails](#schema-sync-fails) -- [Backup Graph Explorer Data](#backup-graph-explorer-data) -- [Gathering SageMaker Logs](#gathering-sagemaker-logs) - -## Docker Container Issues - -1. If the container does not start, or immediately stops, use - `docker logs graph-explorer` to check the container console logs for any - related error messages that might provide guidance on why graph-explorer did - not start. -2. If you are having issues connecting graph-explorer to your graph database, - use your browser's Developer Tools feature to monitor both the browser - console and network calls to determine if here are any errors related to - connectivity. - -### Ports in Use - -If the default ports of 80 and 443 are already in use, you can use the `-p` flag -to change the ports to something else. The host machine ports are the first of -the two numbers. You can change those to whatever you want. - -For example, if you want to use port 8080 and 4431, you can use the following -command: - -``` -docker run -p 8080:80 -p 4431:443 \ - --name graph-explorer \ - --env HOST=localhost \ - public.ecr.aws/neptune/graph-explorer -``` - -Which will result in the following URLs: - -- HTTPS: `https://localhost:4431/explorer` -- HTTP: `http://localhost:8080/explorer` - -### HTTP Only - -If you do not want to use SSL and HTTPS, you can disable it by setting the -following [environment variables](/additionaldocs/deployment/configuration.md): - -``` -PROXY_SERVER_HTTPS_CONNECTION=false -GRAPH_EXP_HTTPS_CONNECTION=false -``` - -These can be passed when creating the Docker container like so: - -``` -docker run -p 80:80 \ - --name graph-explorer \ - --env PROXY_SERVER_HTTPS_CONNECTION=false \ - --env GRAPH_EXP_HTTPS_CONNECTION=false \ - public.ecr.aws/neptune/graph-explorer -``` - -### HTTPS Connections - -If either of the Graph Explorer or the proxy-server are served over an HTTPS -connection (which it is by default), you will have to bypass the warning message -from the browser due to the included certificate being a self-signed -certificate. - -You can bypass by manually ignoring them from the browser or downloading the -correct certificate and configuring them to be trusted. Alternatively, you can -provide your own certificate. - -The following instructions can be used as an example to bypass the warnings for -Chrome, but note that different browsers and operating systems will have -slightly different steps. - -1. Download the certificate directly from the browser. For example, if using - Google Chrome, click the “Not Secure” section on the left of the URL bar and - select “Certificate is not valid” to show the certificate. Then click Details - tab and click Export at the bottom. -2. Once you have the certificate, you will need to trust it on your machine. For - MacOS, you can open the Keychain Access app. Select System under System - Keychains. Then go to File > Import Items... and import the certificate you - downloaded in the previous step. -3. Once imported, select the certificate and right-click to select "Get Info". - Expand the Trust section, and change the value of "When using this - certificate" to "Always Trust". -4. You should now refresh the browser and see that you can proceed to open the - application. For Chrome, the application will remain “Not Secure” due to the - fact that this is a self-signed certificate. If you have trouble accessing - Graph Explorer after completing the previous step and reloading the browser, - consider running a docker restart command and refreshing the browser again. - - -> [!TIP] -> To get rid of the “Not Secure” warning, see -[Using self-signed certificates on Chrome](../development.md#using-self-signed-certificates-on-chrome). - -## Schema Sync Fails - -This can happen for many reasons. Below are a few of the common ones. - -### Mismatched Proxy Server URL - -When running a schema sync, a common cause of failures is a mismatch between the -proxy server URL in your connection settings and the URL currently loaded in -your browser. This mismatch can trigger a "Connection Error" message in Graph -Explorer. - -Modern browsers enforce a security policy called -[Same-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), -which requires API requests to be sent to the same domain as the page you're -viewing. If your connection settings specify a different domain than your -current browser URL, the request will be blocked. - -To resolve this issue: - -1. Check your connection settings -2. Ensure the proxy server URL matches the domain portion of your current - browser URL -3. Update the connection if necessary - -For example: - -``` -# if the current browser page URL is -https://graph-explorer.mydomain.com/explorer/#/connections - -# the connection setting's proxy server URL should be -https://graph-explorer.mydomain.com -``` - -### Timeout - -There are multiple sources of timeouts. - -- Database server -- Networking layer (load balancer, proxy, etc) -- Browser -- Graph Explorer connection configuration - -The error you receive in Graph Explorer can interpret Neptune timeout errors and -timeouts from Graph Explorer's configuration. - -### Out of Memory - -This can happen when your database is very large. Graph Explorer does its best -to support larger databases and is always improving. Please -[file an issue](https://github.com/aws/graph-explorer/issues/new/choose) if you -encounter this situation. - -### Proxy Server Cannot Be Reached - -Communication between the client and proxy server can be configured in different -ways. When Graph Explorer proxy server starts up it will print out its best -approximation of the correct public proxy server address. - -This can manifest as different types of errors depending on the root cause. You -may receive 404 not found responses or get connection refused errors. - -- The proxy server can be hosting HTTP or HTTPS -- The port of the proxy server could be the default (i.e. 80 or 443 with SSL) or - a specific port provided through environment values -- The proxy server paths are not exposed by the networking layer (load balancer, - proxy, firewall, etc) - - The client is hosted at `/explorer` by default, which is configurable - - Queries are handled via `/gremlin`, `/opencypher`, `/sparql` - - Summary APIs are handled via `/summary`, `/pg/statistics/summary`, - `/rdf/statistics/summary` - - Logging is handled by `/logger` - - Default connection is handled by `/defaultConnection` - -> [!IMPORTANT] -> The paths listed here could always change in the future. If they do change, we -> will note that in the release notes. - -## Backup Graph Explorer Data - -Inside of Graph Explorer there is an option to export all the configuration data -that Graph Explorer uses. This data is local to the user’s browser and does not -exist on the server. - -To gather the config data: - -1. Launch Graph Explorer -2. Navigate to the connections screen -3. Press the “Settings” button in the navigation bar -4. Select the “General” page within settings -5. Press the “Save Configuration” button -6. Choose where to save the exported file - -This backup can be restored using the “Load Configuration” button in the same -settings page. - -## Gathering SageMaker Logs - -The Graph Explorer proxy server outputs log statements to standard out. By -default, these logs will be forwarded to CloudWatch if the Notebook has the -proper permissions. - -To gather these logs: - -1. Open the AWS Console -2. Navigate to the Neptune page -3. Select “Notebook” from the sidebar -4. Find the Notebook hosting Graph Explorer -5. Open the details screen for that Notebook -6. In the “Actions” menu, choose “View Details in SageMaker” -7. Press the “View Logs” link in the SageMaker details screen under the field - titled “Lifecycle configuration” -8. Scroll down to the “Log Streams” panel in the CloudWatch details where you - should find multiple log streams -9. For each log stream related to Graph Explorer (LifecycleConfigOnStart.log, - graph-explorer.log) - 1. Open the log stream - 2. In the “Actions” menu, choose “Download search results (CSV)” - -### Graph Explorer Log Stream Does Not Exist - -New Neptune Notebooks automatically apply the correct IAM permissions to write -to CloudWatch. If your Notebook does not automatically create a -graph-explorer.log in the CloudWatch Log Streams, then it is possible that the -Neptune Notebook was created before those IAM permissions were added. You’ll -need to add those permissions manually. - -Below are examples of which IAM permissions you need for Graph Explorer. - -- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) -- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) diff --git a/additionaldocs/troubleshooting/README.md b/additionaldocs/troubleshooting/README.md new file mode 100644 index 000000000..514d40c75 --- /dev/null +++ b/additionaldocs/troubleshooting/README.md @@ -0,0 +1,32 @@ +# Troubleshooting + +This section contains workarounds for common issues and information on how to +diagnose problems with Graph Explorer. + +## Files in this section + +1. [Docker Issues](docker-issues.md) - Container startup, ports, and HTTPS + certificate issues +2. [Schema Sync](schema-sync.md) - Schema synchronization failures and + connection problems +3. [Backup and Restore](backup-restore.md) - Backing up and restoring Graph + Explorer configuration +4. [SageMaker Logs](sagemaker-logs.md) - Gathering logs when running on Amazon + SageMaker + +## General Troubleshooting Tips + +- Use your browser's Developer Tools to monitor console errors and network + requests +- Check container logs with `docker logs graph-explorer` for Docker deployments +- Verify network connectivity between Graph Explorer and your graph database +- Ensure proper IAM permissions when using AWS services + +## Getting Help + +If you encounter issues not covered in these guides, please: + +1. Check the [GitHub Issues](https://github.com/aws/graph-explorer/issues) for + similar problems +2. [File a new issue](https://github.com/aws/graph-explorer/issues/new/choose) + with detailed information about your setup and the problem diff --git a/additionaldocs/troubleshooting/backup-restore.md b/additionaldocs/troubleshooting/backup-restore.md new file mode 100644 index 000000000..aed8bfd30 --- /dev/null +++ b/additionaldocs/troubleshooting/backup-restore.md @@ -0,0 +1,21 @@ +# Backup and Restore + +This guide covers how to backup and restore Graph Explorer configuration data. + +## Backup Graph Explorer Data + +Inside of Graph Explorer there is an option to export all the configuration data +that Graph Explorer uses. This data is local to the user's browser and does not +exist on the server. + +To gather the config data: + +1. Launch Graph Explorer +2. Navigate to the connections screen +3. Press the "Settings" button in the navigation bar +4. Select the "General" page within settings +5. Press the "Save Configuration" button +6. Choose where to save the exported file + +This backup can be restored using the "Load Configuration" button in the same +settings page. diff --git a/additionaldocs/troubleshooting/docker-issues.md b/additionaldocs/troubleshooting/docker-issues.md new file mode 100644 index 000000000..496aab2c8 --- /dev/null +++ b/additionaldocs/troubleshooting/docker-issues.md @@ -0,0 +1,92 @@ +# Docker Container Issues + +This guide covers common Docker-related issues when running Graph Explorer. + +## Container Startup Issues + +1. If the container does not start, or immediately stops, use + `docker logs graph-explorer` to check the container console logs for any + related error messages that might provide guidance on why graph-explorer did + not start. +2. If you are having issues connecting graph-explorer to your graph database, + use your browser's Developer Tools feature to monitor both the browser + console and network calls to determine if here are any errors related to + connectivity. + +## Ports in Use + +If the default ports of 80 and 443 are already in use, you can use the `-p` flag +to change the ports to something else. The host machine ports are the first of +the two numbers. You can change those to whatever you want. + +For example, if you want to use port 8080 and 4431, you can use the following +command: + +``` +docker run -p 8080:80 -p 4431:443 \ + --name graph-explorer \ + --env HOST=localhost \ + public.ecr.aws/neptune/graph-explorer +``` + +Which will result in the following URLs: + +- HTTPS: `https://localhost:4431/explorer` +- HTTP: `http://localhost:8080/explorer` + +## HTTP Only + +If you do not want to use SSL and HTTPS, you can disable it by setting the +following [environment variables](../deployment/configuration.md): + +``` +PROXY_SERVER_HTTPS_CONNECTION=false +GRAPH_EXP_HTTPS_CONNECTION=false +``` + +These can be passed when creating the Docker container like so: + +``` +docker run -p 80:80 \ + --name graph-explorer \ + --env PROXY_SERVER_HTTPS_CONNECTION=false \ + --env GRAPH_EXP_HTTPS_CONNECTION=false \ + public.ecr.aws/neptune/graph-explorer +``` + +## HTTPS Connections + +If either of the Graph Explorer or the proxy-server are served over an HTTPS +connection (which it is by default), you will have to bypass the warning message +from the browser due to the included certificate being a self-signed +certificate. + +You can bypass by manually ignoring them from the browser or downloading the +correct certificate and configuring them to be trusted. Alternatively, you can +provide your own certificate. + +The following instructions can be used as an example to bypass the warnings for +Chrome, but note that different browsers and operating systems will have +slightly different steps. + +1. Download the certificate directly from the browser. For example, if using + Google Chrome, click the "Not Secure" section on the left of the URL bar and + select "Certificate is not valid" to show the certificate. Then click Details + tab and click Export at the bottom. +2. Once you have the certificate, you will need to trust it on your machine. For + MacOS, you can open the Keychain Access app. Select System under System + Keychains. Then go to File > Import Items... and import the certificate you + downloaded in the previous step. +3. Once imported, select the certificate and right-click to select "Get Info". + Expand the Trust section, and change the value of "When using this + certificate" to "Always Trust". +4. You should now refresh the browser and see that you can proceed to open the + application. For Chrome, the application will remain "Not Secure" due to the + fact that this is a self-signed certificate. If you have trouble accessing + Graph Explorer after completing the previous step and reloading the browser, + consider running a docker restart command and refreshing the browser again. + + +> [!TIP] +> To get rid of the "Not Secure" warning, see +[Using self-signed certificates on Chrome](../development/development-setup.md#using-self-signed-certificates-on-chrome). diff --git a/additionaldocs/troubleshooting/sagemaker-logs.md b/additionaldocs/troubleshooting/sagemaker-logs.md new file mode 100644 index 000000000..be77fd2f9 --- /dev/null +++ b/additionaldocs/troubleshooting/sagemaker-logs.md @@ -0,0 +1,40 @@ +# SageMaker Logs + +This guide covers how to gather and troubleshoot logs when running Graph +Explorer on Amazon SageMaker. + +## Gathering SageMaker Logs + +The Graph Explorer proxy server outputs log statements to standard out. By +default, these logs will be forwarded to CloudWatch if the Notebook has the +proper permissions. + +To gather these logs: + +1. Open the AWS Console +2. Navigate to the Neptune page +3. Select "Notebook" from the sidebar +4. Find the Notebook hosting Graph Explorer +5. Open the details screen for that Notebook +6. In the "Actions" menu, choose "View Details in SageMaker" +7. Press the "View Logs" link in the SageMaker details screen under the field + titled "Lifecycle configuration" +8. Scroll down to the "Log Streams" panel in the CloudWatch details where you + should find multiple log streams +9. For each log stream related to Graph Explorer (LifecycleConfigOnStart.log, + graph-explorer.log) + 1. Open the log stream + 2. In the "Actions" menu, choose "Download search results (CSV)" + +## Graph Explorer Log Stream Does Not Exist + +New Neptune Notebooks automatically apply the correct IAM permissions to write +to CloudWatch. If your Notebook does not automatically create a +graph-explorer.log in the CloudWatch Log Streams, then it is possible that the +Neptune Notebook was created before those IAM permissions were added. You'll +need to add those permissions manually. + +Below are examples of which IAM permissions you need for Graph Explorer. + +- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) +- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) diff --git a/additionaldocs/troubleshooting/schema-sync.md b/additionaldocs/troubleshooting/schema-sync.md new file mode 100644 index 000000000..3404705d7 --- /dev/null +++ b/additionaldocs/troubleshooting/schema-sync.md @@ -0,0 +1,82 @@ +# Schema Sync Issues + +This guide covers common issues when performing schema synchronization in Graph +Explorer. + +## Common Schema Sync Failures + +Schema sync can fail for many reasons. Below are a few of the common ones. + +## Mismatched Proxy Server URL + +When running a schema sync, a common cause of failures is a mismatch between the +proxy server URL in your connection settings and the URL currently loaded in +your browser. This mismatch can trigger a "Connection Error" message in Graph +Explorer. + +Modern browsers enforce a security policy called +[Same-Origin Policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), +which requires API requests to be sent to the same domain as the page you're +viewing. If your connection settings specify a different domain than your +current browser URL, the request will be blocked. + +To resolve this issue: + +1. Check your connection settings +2. Ensure the proxy server URL matches the domain portion of your current + browser URL +3. Update the connection if necessary + +For example: + +``` +# if the current browser page URL is +https://graph-explorer.mydomain.com/explorer/#/connections + +# the connection setting's proxy server URL should be +https://graph-explorer.mydomain.com +``` + +## Timeout + +There are multiple sources of timeouts. + +- Database server +- Networking layer (load balancer, proxy, etc) +- Browser +- Graph Explorer connection configuration + +The error you receive in Graph Explorer can interpret Neptune timeout errors and +timeouts from Graph Explorer's configuration. + +## Out of Memory + +This can happen when your database is very large. Graph Explorer does its best +to support larger databases and is always improving. Please +[file an issue](https://github.com/aws/graph-explorer/issues/new/choose) if you +encounter this situation. + +## Proxy Server Cannot Be Reached + +Communication between the client and proxy server can be configured in different +ways. When Graph Explorer proxy server starts up it will print out its best +approximation of the correct public proxy server address. + +This can manifest as different types of errors depending on the root cause. You +may receive 404 not found responses or get connection refused errors. + +- The proxy server can be hosting HTTP or HTTPS +- The port of the proxy server could be the default (i.e. 80 or 443 with SSL) or + a specific port provided through environment values +- The proxy server paths are not exposed by the networking layer (load balancer, + proxy, firewall, etc) + - The client is hosted at `/explorer` by default, which is configurable + - Queries are handled via `/gremlin`, `/opencypher`, `/sparql` + - Summary APIs are handled via `/summary`, `/pg/statistics/summary`, + `/rdf/statistics/summary` + - Logging is handled by `/logger` + - Default connection is handled by `/defaultConnection` + +> [!IMPORTANT] +> The paths listed here could always change in the future. If they do change, we +> will note that in the release notes. From 0ad8ea6bb2050e70b9793a45f34474502ef2da9f Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Wed, 10 Sep 2025 11:24:11 -0400 Subject: [PATCH 14/37] Move connections to user-guide --- README.md | 2 +- additionaldocs/README.md | 2 +- additionaldocs/user-guide/README.md | 20 +++++++++++++++++++ .../{ => user-guide}/connections.md | 0 4 files changed, 22 insertions(+), 2 deletions(-) create mode 100644 additionaldocs/user-guide/README.md rename additionaldocs/{ => user-guide}/connections.md (100%) diff --git a/README.md b/README.md index c0b5858fb..c1e686960 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. You can connect to Amazon Neptune or you can also connect to open graph databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 protocol, such as Blazegraph. For additional details on connecting to different -graph databases, see [Connections](./additionaldocs/connections.md). +graph databases, see [Connections](./additionaldocs/user-guide/connections.md). ### Providing a Default Connection diff --git a/additionaldocs/README.md b/additionaldocs/README.md index aeedd4af0..b5199df13 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -1,7 +1,7 @@ ## Table of Contents -- [Connections](./connections.md) - [Getting Started](./getting-started) +- [User Guide](./user-guide) - [Features](./features) - [Deployment](./deployment) - [Development](./development) diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md new file mode 100644 index 000000000..9af14df9a --- /dev/null +++ b/additionaldocs/user-guide/README.md @@ -0,0 +1,20 @@ +# User Guide + +This section contains guides for end users on how to use Graph Explorer's +features and connect to different graph databases. + +## Files in this section + +1. [Connections](connections.md) - Connecting to different graph database + engines + +## Prerequisites + +- Graph Explorer installed and running +- Access to a graph database endpoint +- Basic familiarity with graph databases + +## Next Steps + +After connecting to your database, see the [Features](../features/) guide for +detailed information on using Graph Explorer's capabilities. diff --git a/additionaldocs/connections.md b/additionaldocs/user-guide/connections.md similarity index 100% rename from additionaldocs/connections.md rename to additionaldocs/user-guide/connections.md From 4a780b54b46537597db3ecd49c0f964102c4e470 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Thu, 11 Sep 2025 09:04:31 -0400 Subject: [PATCH 15/37] Split features doc in to files --- additionaldocs/features/README.md | 260 +++------------------- additionaldocs/features/connections.md | 59 +++++ additionaldocs/features/data-explorer.md | 11 + additionaldocs/features/graph-explorer.md | 129 +++++++++++ additionaldocs/features/settings.md | 22 ++ additionaldocs/features/table-view.md | 32 +++ 6 files changed, 278 insertions(+), 235 deletions(-) create mode 100644 additionaldocs/features/connections.md create mode 100644 additionaldocs/features/data-explorer.md create mode 100644 additionaldocs/features/graph-explorer.md create mode 100644 additionaldocs/features/settings.md create mode 100644 additionaldocs/features/table-view.md diff --git a/additionaldocs/features/README.md b/additionaldocs/features/README.md index fe28056af..6140d490e 100644 --- a/additionaldocs/features/README.md +++ b/additionaldocs/features/README.md @@ -1,247 +1,37 @@ # Features +This section provides detailed documentation on all Graph Explorer features and +functionality. + If you are interested in where Graph Explorer is headed in the future then check out our [roadmap](../../ROADMAP.md) and participate in the discussions. -## Settings UI - -### General Settings - -- **Default Neighbor Expansion Limit:** This setting will allow you to enable or - disable the default limit applied during neighbor expansion. This applies to - both double click expansion and the expand sidebar. This setting can be - overridden by a similar setting on the connection itself. -- **Save Configuration:** This action will export all the configuration data - within the Graph Explorer local database. This will not store any data from - the connected graph databases. However, the export may contain the shape of - the schema for your databases and the connection URL. -- **Load Configuration:** This action will replace all the Graph Explorer - configuration data you currently have with the data in the provided - configuration file. This is a destructive act and can not be undone. It is - **strongly** suggested that you perform a **Save Configuration** action before - performing a **Load Configuration** action to preserve any existing - configuration data. - -### About - -In the _About_ page you can see the version number and submit any feedback. - -## Connections UI - -You can create and manage connections to graph databases using this feature. -Connections is accessible as the first screen after deploying the application, -when you click `Open Connections` on the top-right. Click `+` on the top-right -to add a new connection. You can also edit and delete connections. - -- **Add a new connection:** - - **Name:** Enter a name for your connection (e.g., `MyNeptuneCluster`). - - **Graph Type:** Choose a graph data model that corresponds to your graph - database. - - **Public or proxy endpoint:** Provide the publicly accessible endpoint URL - for a graph database, e.g., Gremlin Server. If connecting to Amazon Neptune, - then provide a proxy endpoint URL that is accessible from outside the VPC, - e.g., EC2. - - **Note:** For connecting to Amazon Neptune, ensure that the graph - connection URL is in the format `https://[NEPTUNE_ENDPOINT]:8182`, and - that the proxy endpoint URL is either `https://[EC2_PUBLIC_HOSTNAME]:443` - or `http://[EC2_PUBLIC_HOSTNAME]:80`, depending on the protocol used. - Ensure that you don't end either of the URLs with `/`. - - **Using proxy server:** Check this box if using a proxy endpoint. - - **Graph connection URL:** Provide the endpoint for the graph database - - **AWS IAM Auth Enabled:** Check this box if connecting to Amazon Neptune - using IAM Auth and SigV4 signed requests - - **Service Type:** Choose the service type - - **AWS Region:** Specify the AWS region where the Neptune cluster is hosted - (e.g., us-east-1) - - **Fetch Timeout:** Specify the timeout for the fetch request - - **Neighbor Expansion Limit:** Specify the default limit for neighbor - expansion. This will override the app setting for neighbor expansion. - -- **Available Connections:** Once a connection is created, this section will - appear as a left-hand pane. When you create more than one connection to a - graph database, you can only connect to and visualize from one graph database - endpoint at a time. To select the active database, toggle the “Active” switch. - -- **Connection Details:** Once a connection is created, this section will appear - as a right-hand information pane for a selected connection. It shows details - such as the connection name, graph data model type, endpoint and a summary of - the graph data, such as the count of nodes, edges, and a list of node types. -- **Last Synchronization:** When a connection is created, Graph Explorer will - perform a scan of the graph to provide summary data. To re-synchronize after - data has changed on your graph, select a connection, and then click the - “refresh” button next to “Last Synchronization” text. -- **Data Explorer UI:** Under a listed node type, you can click on the ‘>’ arrow - to get to the “Data Explorer” view. This allows you to see a sample list of - nodes under this type and choose one or more nodes to “Send to Explorer” for - getting started quickly if you are new to the data. - -## Graph Explorer UI - -You can search, browse, expand, customize views of your graph data using Graph -Explorer, which is the main UI of this application. Once you create a -connection, you can click “Open Graph Explorer” on the top-right to navigate -here. There are several key features on this UI: - -### Top Bar UI - -- **Toggles:** You can toggle to show/hide the Graph View and/or Table View for - screen real-estate management. -- **Open Connections:** This takes the user back to Connections UI. - -### Graph View UI - -The graph visualization canvas that you can interact with. Double-click to -expand the first-order neighbors of a node. - -- **Layout drop-down & reset:** You can display graph data using standard graph - layouts in the Graph View. You can use the circular arrow to reset the physics - of a layout. -- **Screenshot:** Download a picture of the current window in Graph View. -- **Save Graph:** Save the current rendered graph as a JSON file that can be - shared with others having the same connection or reloaded at a later time. -- **Load Graph:** Load a previously saved graph from a JSON file. -- **Zoom In/Out & Clear:** To help users quickly zoom in/out or clear the whole - canvas in the Graph View. -- **Legend (i):** This displays an informational list of icons, colors, and - display names available. - -### Sidebar Panel UI - -The panel on the right of the graph provides various actions, configuration, and -details about the open graph. - -- [**Search panel**](#search-panel) allows you to search for specific nodes by - filtering on node types & attributes or executing a database query then adding - nodes & edges to the graph panel. -- [**Details panel**](#details-panel) shows details about a selected node/edge - such as properties etc. -- [**Entities filter panel**](#entities-filter-panel) is used to control the - display of nodes and edges that are already expanded in the Graph View; click - to hide or show nodes/edges. -- [**Expand panel**](#expand-panel) provides controls and filters to help focus - large neighbor expansions. -- [**Node styling panel**](#node-styling-panel) of node display options (e.g., - color, icon, the property to use for the displayed name). -- [**Edge styling panel**](#edge-styling-panel) of edge display options (e.g., - color, icon, the property to use for the displayed name). -- [**Namespaces panel (RDF only)**](#namespace-panel) allows you to shorten the - display of Resource URIs within the app based on auto-generated prefixes, - commonly-used prefix libraries, or custom prefixes set by the user. Order of - priority is set to Custom > Common > Auto-generated. - -#### Search Panel - -Graph Explorer Search UI provides two powerful ways to search and interact with -your graph database: - -##### Filter Search - -- Enables faceted filtering of nodes based on: - - Node labels (or rdf:type for RDF databases) - - Node attribute values -- Supports partial text matching -- Search results can be added to the graph individually or all at once -- Supports cancellation of long-running queries - -##### Query Search - -- Available for Gremlin and openCypher connections -- Allows execution of any valid database query, including mutations -- When adding an edge, its connected nodes are automatically included -- Displays scalar values in results (though these cannot be added to the graph) -- Paginates large result sets -- Results can be added to the graph individually or all at once -- Supports cancellation of long-running queries - -#### Details Panel - -- Displays attributes and values for node or edge selections -- Displays neighbor counts by label for node selections -- Displays relationship information for edge selections - -#### Expand Panel - -Provides fine grained control over neighbor expansions - -- Filter by node label (or rdf:type for RDF databases) -- Filter by attribute value -- Limit results to a maximum size - -#### Entities Filter Panel - -Provides the ability to filter nodes or edges from the visualization by label -(or rdf:type for RDF databases) - -#### Node Styling Panel - -Each node type can be customized in a variety of ways. - -- **Display label** allows you to change how the node label (or rdf:type) is - represented -- **Display name attribute** allows you to choose the attribute on the node that - is used to uniquely label the node in the graph visualization and search -- **Display description attribute** allows you to choose the attribute on the - node that is used to describe the node in search -- **Custom symbol** can be uploaded in the form of an SVG icon -- **Colors and borders** can be customized to visually distinguish from other - node types - -#### Edge Styling Panel - -Each edge type can be customized in a variety of ways. - -- **Display label** allows you to change how the edge label (or predicate in RDF - databases) is represented -- **Display name attribute** allows you to choose the attribute on the edge that - is used to uniquely label the edge in the graph visualization and search -- **Arrow symbol** can be chosen for both source and target variations -- **Colors and borders** can be customized for the edge label and the line -- **Line style** can be solid, dotted, or dashed - -#### Namespace Panel - -- Only visible in RDF connections -- Displays any automatically generated namespace prefixes for the connection -- Displays all the common prefixes that are built-in -- Allows creation and management of any custom namespace prefixes - -### Table View UI - -This collapsible view shows a row-column display of the data in the Graph View. -You can use filters in the Table to show/hide elements in the Graph View, and -you can export the table view into a CSV or JSON file. +## Files in this section -The following columns are available for filtering on property graphs (RDF graphs -in parentheses): +1. [Settings](settings.md) - Application settings and configuration management +2. [Connections](connections.md) - Creating and managing database connections +3. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +4. [Table View](table-view.md) - Tabular data view and export functionality +5. [Data Explorer](data-explorer.md) - Node type data exploration -- Node ID (Resource URI) -- Node Type (Class) -- Edge Type (Predicate) -- Source ID (Source URI) -- Source Type (Source Class) -- Target ID (Target URI) -- Target Type (Target Class) -- Display Name - Set in the Node/Edge Styling panes -- Display Description - Set in the Node/Edge Styling panes -- Total Neighbors - Enter an integer to be used as the >= limit +## Prerequisites -#### Additional Table View UI Features +- Graph Explorer installed and running +- At least one database connection configured +- Basic familiarity with graph databases -- **Visibility** - manually show or hide nodes or edges -- **All Nodes / All Edges (or All Resources / All Predicates) dropdown** - - allows you to display a list of either nodes or edges and control - display/filter on them -- **Download** - You can download the current Table View as a CSV or JSON file - with additional customization options -- **Default columns** - You can set which columns you want to display -- Paging of rows +## Getting Started with Features -## Data Explorer UI +1. Start by setting up your [connections](connections.md) to your graph + databases +2. Explore the main [Graph Explorer](graph-explorer.md) interface for + visualization +3. Use the [Table View](table-view.md) for data analysis and export +4. Configure [settings](settings.md) to customize your experience +5. Use the [Data Explorer](data-explorer.md) to examine specific node types -You can use the Data Explorer UI to view the data for the selected node type. -You can open the Data Explorer by clicking the node type row in the connection -details pane. +## Next Steps -- View tabular data for the selected node type -- Set the node type display name and description attributes -- Send a specific node to the graph view +After familiarizing yourself with the features, see the +[User Guide](../user-guide/) for specific usage scenarios and the +[Troubleshooting](../troubleshooting/) section if you encounter any issues. diff --git a/additionaldocs/features/connections.md b/additionaldocs/features/connections.md new file mode 100644 index 000000000..d4cc9407b --- /dev/null +++ b/additionaldocs/features/connections.md @@ -0,0 +1,59 @@ +# Connections UI + +You can create and manage connections to graph databases using this feature. +Connections is accessible as the first screen after deploying the application, +when you click `Open Connections` on the top-right. Click `+` on the top-right +to add a new connection. You can also edit and delete connections. + +## Add a new connection + +- **Name:** Enter a name for your connection (e.g., `MyNeptuneCluster`). +- **Graph Type:** Choose a graph data model that corresponds to your graph + database. +- **Public or proxy endpoint:** Provide the publicly accessible endpoint URL for + a graph database, e.g., Gremlin Server. If connecting to Amazon Neptune, then + provide a proxy endpoint URL that is accessible from outside the VPC, e.g., + EC2. + - **Note:** For connecting to Amazon Neptune, ensure that the graph connection + URL is in the format `https://[NEPTUNE_ENDPOINT]:8182`, and that the proxy + endpoint URL is either `https://[EC2_PUBLIC_HOSTNAME]:443` or + `http://[EC2_PUBLIC_HOSTNAME]:80`, depending on the protocol used. Ensure + that you don't end either of the URLs with `/`. +- **Using proxy server:** Check this box if using a proxy endpoint. +- **Graph connection URL:** Provide the endpoint for the graph database +- **AWS IAM Auth Enabled:** Check this box if connecting to Amazon Neptune using + IAM Auth and SigV4 signed requests +- **Service Type:** Choose the service type +- **AWS Region:** Specify the AWS region where the Neptune cluster is hosted + (e.g., us-east-1) +- **Fetch Timeout:** Specify the timeout for the fetch request +- **Neighbor Expansion Limit:** Specify the default limit for neighbor + expansion. This will override the app setting for neighbor expansion. + +## Available Connections + +Once a connection is created, this section will appear as a left-hand pane. When +you create more than one connection to a graph database, you can only connect to +and visualize from one graph database endpoint at a time. To select the active +database, toggle the "Active" switch. + +## Connection Details + +Once a connection is created, this section will appear as a right-hand +information pane for a selected connection. It shows details such as the +connection name, graph data model type, endpoint and a summary of the graph +data, such as the count of nodes, edges, and a list of node types. + +## Last Synchronization + +When a connection is created, Graph Explorer will perform a scan of the graph to +provide summary data. To re-synchronize after data has changed on your graph, +select a connection, and then click the "refresh" button next to "Last +Synchronization" text. + +## Data Explorer UI + +Under a listed node type, you can click on the '>' arrow to get to the "Data +Explorer" view. This allows you to see a sample list of nodes under this type +and choose one or more nodes to "Send to Explorer" for getting started quickly +if you are new to the data. diff --git a/additionaldocs/features/data-explorer.md b/additionaldocs/features/data-explorer.md new file mode 100644 index 000000000..cee93e401 --- /dev/null +++ b/additionaldocs/features/data-explorer.md @@ -0,0 +1,11 @@ +# Data Explorer UI + +You can use the Data Explorer UI to view the data for the selected node type. +You can open the Data Explorer by clicking the node type row in the connection +details pane. + +## Features + +- View tabular data for the selected node type +- Set the node type display name and description attributes +- Send a specific node to the graph view diff --git a/additionaldocs/features/graph-explorer.md b/additionaldocs/features/graph-explorer.md new file mode 100644 index 000000000..58948c99e --- /dev/null +++ b/additionaldocs/features/graph-explorer.md @@ -0,0 +1,129 @@ +# Graph Explorer UI + +You can search, browse, expand, customize views of your graph data using Graph +Explorer, which is the main UI of this application. Once you create a +connection, you can click "Open Graph Explorer" on the top-right to navigate +here. There are several key features on this UI: + +## Top Bar UI + +- **Toggles:** You can toggle to show/hide the Graph View and/or Table View for + screen real-estate management. +- **Open Connections:** This takes the user back to Connections UI. + +## Graph View UI + +The graph visualization canvas that you can interact with. Double-click to +expand the first-order neighbors of a node. + +- **Layout drop-down & reset:** You can display graph data using standard graph + layouts in the Graph View. You can use the circular arrow to reset the physics + of a layout. +- **Screenshot:** Download a picture of the current window in Graph View. +- **Save Graph:** Save the current rendered graph as a JSON file that can be + shared with others having the same connection or reloaded at a later time. +- **Load Graph:** Load a previously saved graph from a JSON file. +- **Zoom In/Out & Clear:** To help users quickly zoom in/out or clear the whole + canvas in the Graph View. +- **Legend (i):** This displays an informational list of icons, colors, and + display names available. + +## Sidebar Panel UI + +The panel on the right of the graph provides various actions, configuration, and +details about the open graph. + +- [**Search panel**](#search-panel) allows you to search for specific nodes by + filtering on node types & attributes or executing a database query then adding + nodes & edges to the graph panel. +- [**Details panel**](#details-panel) shows details about a selected node/edge + such as properties etc. +- [**Entities filter panel**](#entities-filter-panel) is used to control the + display of nodes and edges that are already expanded in the Graph View; click + to hide or show nodes/edges. +- [**Expand panel**](#expand-panel) provides controls and filters to help focus + large neighbor expansions. +- [**Node styling panel**](#node-styling-panel) of node display options (e.g., + color, icon, the property to use for the displayed name). +- [**Edge styling panel**](#edge-styling-panel) of edge display options (e.g., + color, icon, the property to use for the displayed name). +- [**Namespaces panel (RDF only)**](#namespace-panel) allows you to shorten the + display of Resource URIs within the app based on auto-generated prefixes, + commonly-used prefix libraries, or custom prefixes set by the user. Order of + priority is set to Custom > Common > Auto-generated. + +### Search Panel + +Graph Explorer Search UI provides two powerful ways to search and interact with +your graph database: + +#### Filter Search + +- Enables faceted filtering of nodes based on: + - Node labels (or rdf:type for RDF databases) + - Node attribute values +- Supports partial text matching +- Search results can be added to the graph individually or all at once +- Supports cancellation of long-running queries + +#### Query Search + +- Available for Gremlin and openCypher connections +- Allows execution of any valid database query, including mutations +- When adding an edge, its connected nodes are automatically included +- Displays scalar values in results (though these cannot be added to the graph) +- Paginates large result sets +- Results can be added to the graph individually or all at once +- Supports cancellation of long-running queries + +### Details Panel + +- Displays attributes and values for node or edge selections +- Displays neighbor counts by label for node selections +- Displays relationship information for edge selections + +### Expand Panel + +Provides fine grained control over neighbor expansions + +- Filter by node label (or rdf:type for RDF databases) +- Filter by attribute value +- Limit results to a maximum size + +### Entities Filter Panel + +Provides the ability to filter nodes or edges from the visualization by label +(or rdf:type for RDF databases) + +### Node Styling Panel + +Each node type can be customized in a variety of ways. + +- **Display label** allows you to change how the node label (or rdf:type) is + represented +- **Display name attribute** allows you to choose the attribute on the node that + is used to uniquely label the node in the graph visualization and search +- **Display description attribute** allows you to choose the attribute on the + node that is used to describe the node in search +- **Custom symbol** can be uploaded in the form of an SVG icon +- **Colors and borders** can be customized to visually distinguish from other + node types + +### Edge Styling Panel + +Each edge type can be customized in a variety of ways. + +- **Display label** allows you to change how the edge label (or predicate in RDF + databases) is represented +- **Display name attribute** allows you to choose the attribute on the edge that + is used to uniquely label the edge in the graph visualization and search +- **Arrow symbol** can be chosen for both source and target variations +- **Colors and borders** can be customized for the edge label and the line +- **Line style** can be solid, dotted, or dashed + +### Namespace Panel + +- Only visible in RDF connections +- Displays any automatically generated namespace prefixes for the connection +- Displays all the common prefixes that are built-in +- Allows creation and management of any custom namespace prefixes diff --git a/additionaldocs/features/settings.md b/additionaldocs/features/settings.md new file mode 100644 index 000000000..dcdb97262 --- /dev/null +++ b/additionaldocs/features/settings.md @@ -0,0 +1,22 @@ +# Settings UI + +## General Settings + +- **Default Neighbor Expansion Limit:** This setting will allow you to enable or + disable the default limit applied during neighbor expansion. This applies to + both double click expansion and the expand sidebar. This setting can be + overridden by a similar setting on the connection itself. +- **Save Configuration:** This action will export all the configuration data + within the Graph Explorer local database. This will not store any data from + the connected graph databases. However, the export may contain the shape of + the schema for your databases and the connection URL. +- **Load Configuration:** This action will replace all the Graph Explorer + configuration data you currently have with the data in the provided + configuration file. This is a destructive act and can not be undone. It is + **strongly** suggested that you perform a **Save Configuration** action before + performing a **Load Configuration** action to preserve any existing + configuration data. + +## About + +In the _About_ page you can see the version number and submit any feedback. diff --git a/additionaldocs/features/table-view.md b/additionaldocs/features/table-view.md new file mode 100644 index 000000000..bef890c7e --- /dev/null +++ b/additionaldocs/features/table-view.md @@ -0,0 +1,32 @@ +# Table View UI + +This collapsible view shows a row-column display of the data in the Graph View. +You can use filters in the Table to show/hide elements in the Graph View, and +you can export the table view into a CSV or JSON file. + +## Available Columns + +The following columns are available for filtering on property graphs (RDF graphs +in parentheses): + +- Node ID (Resource URI) +- Node Type (Class) +- Edge Type (Predicate) +- Source ID (Source URI) +- Source Type (Source Class) +- Target ID (Target URI) +- Target Type (Target Class) +- Display Name - Set in the Node/Edge Styling panes +- Display Description - Set in the Node/Edge Styling panes +- Total Neighbors - Enter an integer to be used as the >= limit + +## Additional Table View UI Features + +- **Visibility** - manually show or hide nodes or edges +- **All Nodes / All Edges (or All Resources / All Predicates) dropdown** - + allows you to display a list of either nodes or edges and control + display/filter on them +- **Download** - You can download the current Table View as a CSV or JSON file + with additional customization options +- **Default columns** - You can set which columns you want to display +- Paging of rows From 58a6bc244ad004c0fe8c5166362a414ff356d5a9 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Thu, 11 Sep 2025 09:16:12 -0400 Subject: [PATCH 16/37] Move features in to user-guide --- Changelog.md | 2 +- README.md | 2 +- additionaldocs/README.md | 1 - additionaldocs/features/README.md | 37 ---------- additionaldocs/features/connections.md | 59 ---------------- additionaldocs/user-guide/README.md | 12 ++-- additionaldocs/user-guide/connections.md | 69 ++++++++++++++++++- .../{features => user-guide}/data-explorer.md | 0 .../graph-explorer.md | 0 .../{features => user-guide}/settings.md | 0 .../{features => user-guide}/table-view.md | 0 11 files changed, 77 insertions(+), 105 deletions(-) delete mode 100644 additionaldocs/features/README.md delete mode 100644 additionaldocs/features/connections.md rename additionaldocs/{features => user-guide}/data-explorer.md (100%) rename additionaldocs/{features => user-guide}/graph-explorer.md (100%) rename additionaldocs/{features => user-guide}/settings.md (100%) rename additionaldocs/{features => user-guide}/table-view.md (100%) diff --git a/Changelog.md b/Changelog.md index 6a686ce92..30d63b6c5 100644 --- a/Changelog.md +++ b/Changelog.md @@ -163,7 +163,7 @@ ensuring that users can enforce read-only operations. Graph Explorer v2.0 marks a significant milestone with the introduction of the new -[query editor for Gremlin connections](./additionaldocs/features/README.md#query-search). +[query editor for Gremlin connections](./additionaldocs/user-guide/graph-explorer.md#query-search). This powerful feature allows users to enter any valid Gremlin query and visualize the returned nodes, edges, and scalar values directly from the database. You can review the results in the sidebar and choose to add all nodes diff --git a/README.md b/README.md index c1e686960..55fe94e5a 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ databases: view For complete documentation on all features and functionality, please see our -[detailed features guide](./additionaldocs/features/README.md). +[detailed user guide](./additionaldocs/user-guide/). If you're interested in our future development plans, check out our [roadmap](./ROADMAP.md) and participate in the discussions. diff --git a/additionaldocs/README.md b/additionaldocs/README.md index b5199df13..de8a97ba7 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -2,7 +2,6 @@ - [Getting Started](./getting-started) - [User Guide](./user-guide) -- [Features](./features) - [Deployment](./deployment) - [Development](./development) - [Troubleshooting](./troubleshooting/) diff --git a/additionaldocs/features/README.md b/additionaldocs/features/README.md deleted file mode 100644 index 6140d490e..000000000 --- a/additionaldocs/features/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# Features - -This section provides detailed documentation on all Graph Explorer features and -functionality. - -If you are interested in where Graph Explorer is headed in the future then check -out our [roadmap](../../ROADMAP.md) and participate in the discussions. - -## Files in this section - -1. [Settings](settings.md) - Application settings and configuration management -2. [Connections](connections.md) - Creating and managing database connections -3. [Graph Explorer](graph-explorer.md) - Main graph visualization interface -4. [Table View](table-view.md) - Tabular data view and export functionality -5. [Data Explorer](data-explorer.md) - Node type data exploration - -## Prerequisites - -- Graph Explorer installed and running -- At least one database connection configured -- Basic familiarity with graph databases - -## Getting Started with Features - -1. Start by setting up your [connections](connections.md) to your graph - databases -2. Explore the main [Graph Explorer](graph-explorer.md) interface for - visualization -3. Use the [Table View](table-view.md) for data analysis and export -4. Configure [settings](settings.md) to customize your experience -5. Use the [Data Explorer](data-explorer.md) to examine specific node types - -## Next Steps - -After familiarizing yourself with the features, see the -[User Guide](../user-guide/) for specific usage scenarios and the -[Troubleshooting](../troubleshooting/) section if you encounter any issues. diff --git a/additionaldocs/features/connections.md b/additionaldocs/features/connections.md deleted file mode 100644 index d4cc9407b..000000000 --- a/additionaldocs/features/connections.md +++ /dev/null @@ -1,59 +0,0 @@ -# Connections UI - -You can create and manage connections to graph databases using this feature. -Connections is accessible as the first screen after deploying the application, -when you click `Open Connections` on the top-right. Click `+` on the top-right -to add a new connection. You can also edit and delete connections. - -## Add a new connection - -- **Name:** Enter a name for your connection (e.g., `MyNeptuneCluster`). -- **Graph Type:** Choose a graph data model that corresponds to your graph - database. -- **Public or proxy endpoint:** Provide the publicly accessible endpoint URL for - a graph database, e.g., Gremlin Server. If connecting to Amazon Neptune, then - provide a proxy endpoint URL that is accessible from outside the VPC, e.g., - EC2. - - **Note:** For connecting to Amazon Neptune, ensure that the graph connection - URL is in the format `https://[NEPTUNE_ENDPOINT]:8182`, and that the proxy - endpoint URL is either `https://[EC2_PUBLIC_HOSTNAME]:443` or - `http://[EC2_PUBLIC_HOSTNAME]:80`, depending on the protocol used. Ensure - that you don't end either of the URLs with `/`. -- **Using proxy server:** Check this box if using a proxy endpoint. -- **Graph connection URL:** Provide the endpoint for the graph database -- **AWS IAM Auth Enabled:** Check this box if connecting to Amazon Neptune using - IAM Auth and SigV4 signed requests -- **Service Type:** Choose the service type -- **AWS Region:** Specify the AWS region where the Neptune cluster is hosted - (e.g., us-east-1) -- **Fetch Timeout:** Specify the timeout for the fetch request -- **Neighbor Expansion Limit:** Specify the default limit for neighbor - expansion. This will override the app setting for neighbor expansion. - -## Available Connections - -Once a connection is created, this section will appear as a left-hand pane. When -you create more than one connection to a graph database, you can only connect to -and visualize from one graph database endpoint at a time. To select the active -database, toggle the "Active" switch. - -## Connection Details - -Once a connection is created, this section will appear as a right-hand -information pane for a selected connection. It shows details such as the -connection name, graph data model type, endpoint and a summary of the graph -data, such as the count of nodes, edges, and a list of node types. - -## Last Synchronization - -When a connection is created, Graph Explorer will perform a scan of the graph to -provide summary data. To re-synchronize after data has changed on your graph, -select a connection, and then click the "refresh" button next to "Last -Synchronization" text. - -## Data Explorer UI - -Under a listed node type, you can click on the '>' arrow to get to the "Data -Explorer" view. This allows you to see a sample list of nodes under this type -and choose one or more nodes to "Send to Explorer" for getting started quickly -if you are new to the data. diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 9af14df9a..992d3f59d 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -5,8 +5,12 @@ features and connect to different graph databases. ## Files in this section -1. [Connections](connections.md) - Connecting to different graph database - engines +1. [Connections](connections.md) - Database configuration and connection + management +2. [Settings](settings.md) - Application settings and configuration management +3. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +4. [Table View](table-view.md) - Tabular data view and export functionality +5. [Data Explorer](data-explorer.md) - Node type data exploration ## Prerequisites @@ -16,5 +20,5 @@ features and connect to different graph databases. ## Next Steps -After connecting to your database, see the [Features](../features/) guide for -detailed information on using Graph Explorer's capabilities. +After connecting to your database, explore the other guides in this section to +learn about Graph Explorer's visualization and data exploration capabilities. diff --git a/additionaldocs/user-guide/connections.md b/additionaldocs/user-guide/connections.md index 28580fd92..c7a68da19 100644 --- a/additionaldocs/user-guide/connections.md +++ b/additionaldocs/user-guide/connections.md @@ -1,4 +1,9 @@ -## Connections +# Connections + +This guide covers both how to configure Graph Explorer with different graph +database engines and how to manage connections within the application. + +## Database Configuration This section contains detailed instructions that help when configuring Graph Explorer with different graph database engines. @@ -43,7 +48,7 @@ If you have a version of Gremlin Server prior to 3.7, you will need to make the following changes: - **Enable property returns** - Remove - “.withStrategies(ReferenceElementStrategy)” from + ".withStrategies(ReferenceElementStrategy)" from `/scripts/generate-modern.groovy` so that properties are returned. - **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to @@ -57,3 +62,63 @@ following changes: - If using Docker, ensure that the container running the workbench can properly access the container running BlazeGraph. You can find documentation on how to connect containers via [Docker networks](https://docs.docker.com/network/). + +## Connections UI + +You can create and manage connections to graph databases using this feature. +Connections is accessible as the first screen after deploying the application, +when you click `Open Connections` on the top-right. Click `+` on the top-right +to add a new connection. You can also edit and delete connections. + +### Add a new connection + +- **Name:** Enter a name for your connection (e.g., `MyNeptuneCluster`). +- **Graph Type:** Choose a graph data model that corresponds to your graph + database. +- **Public or proxy endpoint:** Provide the publicly accessible endpoint URL for + a graph database, e.g., Gremlin Server. If connecting to Amazon Neptune, then + provide a proxy endpoint URL that is accessible from outside the VPC, e.g., + EC2. + - **Note:** For connecting to Amazon Neptune, ensure that the graph connection + URL is in the format `https://[NEPTUNE_ENDPOINT]:8182`, and that the proxy + endpoint URL is either `https://[EC2_PUBLIC_HOSTNAME]:443` or + `http://[EC2_PUBLIC_HOSTNAME]:80`, depending on the protocol used. Ensure + that you don't end either of the URLs with `/`. +- **Using proxy server:** Check this box if using a proxy endpoint. +- **Graph connection URL:** Provide the endpoint for the graph database +- **AWS IAM Auth Enabled:** Check this box if connecting to Amazon Neptune using + IAM Auth and SigV4 signed requests +- **Service Type:** Choose the service type +- **AWS Region:** Specify the AWS region where the Neptune cluster is hosted + (e.g., us-east-1) +- **Fetch Timeout:** Specify the timeout for the fetch request +- **Neighbor Expansion Limit:** Specify the default limit for neighbor + expansion. This will override the app setting for neighbor expansion. + +### Available Connections + +Once a connection is created, this section will appear as a left-hand pane. When +you create more than one connection to a graph database, you can only connect to +and visualize from one graph database endpoint at a time. To select the active +database, toggle the "Active" switch. + +### Connection Details + +Once a connection is created, this section will appear as a right-hand +information pane for a selected connection. It shows details such as the +connection name, graph data model type, endpoint and a summary of the graph +data, such as the count of nodes, edges, and a list of node types. + +### Last Synchronization + +When a connection is created, Graph Explorer will perform a scan of the graph to +provide summary data. To re-synchronize after data has changed on your graph, +select a connection, and then click the "refresh" button next to "Last +Synchronization" text. + +### Data Explorer UI + +Under a listed node type, you can click on the '>' arrow to get to the "Data +Explorer" view. This allows you to see a sample list of nodes under this type +and choose one or more nodes to "Send to Explorer" for getting started quickly +if you are new to the data. diff --git a/additionaldocs/features/data-explorer.md b/additionaldocs/user-guide/data-explorer.md similarity index 100% rename from additionaldocs/features/data-explorer.md rename to additionaldocs/user-guide/data-explorer.md diff --git a/additionaldocs/features/graph-explorer.md b/additionaldocs/user-guide/graph-explorer.md similarity index 100% rename from additionaldocs/features/graph-explorer.md rename to additionaldocs/user-guide/graph-explorer.md diff --git a/additionaldocs/features/settings.md b/additionaldocs/user-guide/settings.md similarity index 100% rename from additionaldocs/features/settings.md rename to additionaldocs/user-guide/settings.md diff --git a/additionaldocs/features/table-view.md b/additionaldocs/user-guide/table-view.md similarity index 100% rename from additionaldocs/features/table-view.md rename to additionaldocs/user-guide/table-view.md From 8f09de742c658c8be3ce23507e4082196066afa5 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Thu, 11 Sep 2025 11:06:36 -0400 Subject: [PATCH 17/37] Move database connection info to getting-started --- additionaldocs/getting-started/README.md | 29 +++++--- .../getting-started/first-connection.md | 61 ++++++++++++++++ additionaldocs/user-guide/README.md | 3 +- additionaldocs/user-guide/connections.md | 69 ++----------------- 4 files changed, 87 insertions(+), 75 deletions(-) create mode 100644 additionaldocs/getting-started/first-connection.md diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 7e37edc32..29c985301 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -1,15 +1,28 @@ # Getting Started -This project contains the code needed to create a Docker image of the Graph -Explorer. The image will create the Graph Explorer application and proxy server -that will be served over the standard HTTP or HTTPS ports (HTTPS by default). +This section helps new users install and configure Graph Explorer for the first +time. -The proxy server will be created automatically, but will only be necessary if -you are connecting to Neptune. Gremlin-Server and BlazeGraph can be connected to -directly. Additionally, the image will create a self-signed certificate that can -be optionally used. +## Files in this section -## Examples +1. [First Connection](first-connection.md) - Connecting to your first database + +## Prerequisites + +- Graph Explorer installed and running (see [Deployment](../deployment/) guides) +- Access to a graph database endpoint +- Basic familiarity with graph databases + +## Quick Start Steps + +1. **Deploy Graph Explorer** - Choose a deployment method from the + [Deployment](../deployment/) section +2. **Configure your database** - Follow the + [First Connection](first-connection.md) guide for your database type +3. **Create a connection** - Use the + [Connections UI](../user-guide/connections.md) to set up your connection +4. **Start exploring** - Begin using Graph Explorer with the + [User Guide](../user-guide/) ## Troubleshooting diff --git a/additionaldocs/getting-started/first-connection.md b/additionaldocs/getting-started/first-connection.md new file mode 100644 index 000000000..58bf7844f --- /dev/null +++ b/additionaldocs/getting-started/first-connection.md @@ -0,0 +1,61 @@ +# First Connection + +This guide contains detailed instructions that help when configuring Graph +Explorer with different graph database engines for the first time. After setting +up your database, see the [Connections UI](../user-guide/connections.md) guide +to learn how to create and manage connections within Graph Explorer. + +## Connecting to Neptune + +- Ensure that Graph Explorer has access to the Neptune instance by being in the + same VPC or VPC peering. +- If authentication is enabled, read query privileges are needed (See + [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). + +## Connecting to Gremlin-Server + +If you are using the default Gremlin Server docker image, you can get the server +running with the following commands: + +``` +docker pull tinkerpop/gremlin-server:latest +docker run -p 8182:8182 \ + tinkerpop/gremlin-server:latest \ + conf/gremlin-server-rest-modern.yaml +``` + +### Enable REST + +Graph Explorer only supports HTTP(S) connections. When connecting to +Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) +(i.e. +[Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). + + +> [!TIP] +> The Gremlin Server configuration can be usually found at: +> +> ``` +> /conf/gremlin-server.yaml +> ``` + +### Versions Prior to 3.7 + +If you have a version of Gremlin Server prior to 3.7, you will need to make the +following changes: + +- **Enable property returns** - Remove + ".withStrategies(ReferenceElementStrategy)" from + `/scripts/generate-modern.groovy` so that properties are returned. +- **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and + `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to + support string ids. You can use `ANY`. +- Build and run the Docker container as normal. + +## Connecting to BlazeGraph + +- Build and run the Docker container as normal and connect the proxy-server to + BlazeGraph and your workbench to the proxy-server. +- If using Docker, ensure that the container running the workbench can properly + access the container running BlazeGraph. You can find documentation on how to + connect containers via [Docker networks](https://docs.docker.com/network/). diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 992d3f59d..3ddd2fef3 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -5,8 +5,7 @@ features and connect to different graph databases. ## Files in this section -1. [Connections](connections.md) - Database configuration and connection - management +1. [Connections](connections.md) - Managing database connections in the UI 2. [Settings](settings.md) - Application settings and configuration management 3. [Graph Explorer](graph-explorer.md) - Main graph visualization interface 4. [Table View](table-view.md) - Tabular data view and export functionality diff --git a/additionaldocs/user-guide/connections.md b/additionaldocs/user-guide/connections.md index c7a68da19..1d7fec9a9 100644 --- a/additionaldocs/user-guide/connections.md +++ b/additionaldocs/user-guide/connections.md @@ -1,69 +1,8 @@ -# Connections +# Connections UI -This guide covers both how to configure Graph Explorer with different graph -database engines and how to manage connections within the application. - -## Database Configuration - -This section contains detailed instructions that help when configuring Graph -Explorer with different graph database engines. - -### Connecting to Neptune - -- Ensure that Graph Explorer has access to the Neptune instance by being in the - same VPC or VPC peering. -- If authentication is enabled, read query privileges are needed (See - [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). - -### Connecting to Gremlin-Server - -If you are using the default Gremlin Server docker image, you can get the server -running with the following commands: - -``` -docker pull tinkerpop/gremlin-server:latest -docker run -p 8182:8182 \ - tinkerpop/gremlin-server:latest \ - conf/gremlin-server-rest-modern.yaml -``` - -#### Enable REST - -Graph Explorer only supports HTTP(S) connections. When connecting to -Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) -(i.e. -[Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). - - -> [!TIP] -> The Gremlin Server configuration can be usually found at: -> -> ``` -> /conf/gremlin-server.yaml -> ``` - -#### Versions Prior to 3.7 - -If you have a version of Gremlin Server prior to 3.7, you will need to make the -following changes: - -- **Enable property returns** - Remove - ".withStrategies(ReferenceElementStrategy)" from - `/scripts/generate-modern.groovy` so that properties are returned. -- **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and - `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to - support string ids. You can use `ANY`. -- Build and run the Docker container as normal. - -### Connecting to BlazeGraph - -- Build and run the Docker container as normal and connect the proxy-server to - BlazeGraph and your workbench to the proxy-server. -- If using Docker, ensure that the container running the workbench can properly - access the container running BlazeGraph. You can find documentation on how to - connect containers via [Docker networks](https://docs.docker.com/network/). - -## Connections UI +This guide covers how to manage connections within the Graph Explorer +application. For information on configuring different graph database engines, +see the [First Connection](../getting-started/first-connection.md) guide. You can create and manage connections to graph databases using this feature. Connections is accessible as the first screen after deploying the application, From b2d825fd13275cbdb915abf6d6e6d3e2379ef550 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 11:25:21 -0400 Subject: [PATCH 18/37] Update sterring to include summary --- .kiro/steering/documentation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.kiro/steering/documentation.md b/.kiro/steering/documentation.md index 1ddc32047..62b6fb4d4 100644 --- a/.kiro/steering/documentation.md +++ b/.kiro/steering/documentation.md @@ -98,6 +98,7 @@ Each documentation folder should include a `README.md` file that serves as a table of contents for that folder: - **Purpose**: Explain what the folder contains and who it's for +- **Summary**: Briefly describe the folder's purpose and content - **File Listing**: List all files in the folder with brief descriptions - **Reading Order**: Suggest the recommended order for reading files - **Prerequisites**: Note any required knowledge or setup before starting From 292cf3898a50fcce2866ca879b768198d4fb26bc Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 11:42:03 -0400 Subject: [PATCH 19/37] Move connection info from root readme --- README.md | 101 ---------------- .../getting-started/first-connection.md | 114 ++++++++++++++++-- 2 files changed, 105 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 55fe94e5a..cd8b86192 100644 --- a/README.md +++ b/README.md @@ -71,107 +71,6 @@ For complete documentation on all features and functionality, please see our If you're interested in our future development plans, check out our [roadmap](./ROADMAP.md) and participate in the discussions. -## Connections - -Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. -You can connect to Amazon Neptune or you can also connect to open graph -databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 -protocol, such as Blazegraph. For additional details on connecting to different -graph databases, see [Connections](./additionaldocs/user-guide/connections.md). - -### Providing a Default Connection - -To provide a default connection such that initial loads of Graph Explorer always -result with the same starting connection, modify the `docker run ...` command to -either take in a JSON configuration or runtime environment variables. If you -provide both a JSON configuration and environmental variables, the JSON will be -prioritized. - -#### Environment Variables - -These are the valid environment variables used for the default connection, their -defaults, and their descriptions. - -- Required: - - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See - [Add a New Connection](#connections-ui) -- Optional - - `GRAPH_TYPE` - `None` - If not specified, multiple connections will be - created for every available graph type / query language. See - [Add a New Connection](#connections-ui) - - `USING_PROXY_SERVER` - `False` - See [Add a New Connection](#connections-ui) - - `IAM` - `False` - See [Add a New Connection](#connections-ui) - - `GRAPH_EXP_HTTPS_CONNECTION` - `True` - Controls whether Graph Explorer uses - SSL or not - - `PROXY_SERVER_HTTPS_CONNECTION` - `True` - Controls whether the server uses - SSL or not - - `GRAPH_EXP_FETCH_REQUEST_TIMEOUT` - `240000` - Controls the timeout for the - fetch request. Measured in milliseconds (i.e. 240000 is 240 seconds or 4 - minutes). - - `GRAPH_EXP_NODE_EXPANSION_LIMIT` - `None` - Controls the limit for node - counts and expansion queries. -- Conditionally Required: - - Required if `USING_PROXY_SERVER=True` - - `GRAPH_CONNECTION_URL` - `None` - See - [Add a New Connection](#connections-ui) - - Required if `USING_PROXY_SERVER=True` and `IAM=True` - - `AWS_REGION` - `None` - See [Add a New Connection](#connections-ui) - - `SERVICE_TYPE` - `neptune-db`, Set this as `neptune-db` for Neptune - database or `neptune-graph` for Neptune Analytics. - -#### JSON Configuration Approach - -First, create a `config.json` file containing values for the connection -attributes: - -```js -{ - "PUBLIC_OR_PROXY_ENDPOINT": "https://public-endpoint", - "GRAPH_CONNECTION_URL": "https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182", - "USING_PROXY_SERVER": true, - "IAM": true, - "SERVICE_TYPE": "neptune-db", - "AWS_REGION": "us-west-2", - // Possible Values are "gremlin", "sparql", "openCypher" - "GRAPH_TYPE": "gremlin", - "GRAPH_EXP_HTTPS_CONNECTION": true, - "PROXY_SERVER_HTTPS_CONNECTION": true, - // Measured in milliseconds (i.e. 240000 is 240 seconds or 4 minutes) - "GRAPH_EXP_FETCH_REQUEST_TIMEOUT": 240000, - "GRAPH_EXP_NODE_EXPANSION_LIMIT": 500, -} -``` - -Pass the `config.json` file path to the `docker run` command. - -```bash -docker run -p 80:80 -p 443:443 \ - --env HOST={hostname-or-ip-address} \ - -v /path/to/config.json:/graph-explorer/config.json \ - public.ecr.aws/neptune/graph-explorer -``` - -#### Environment Variable Approach - -Provide the desired connection variables directly to the `docker run` command, -as follows: - -```bash -docker run -p 80:80 -p 443:443 \ - --env HOST={hostname-or-ip-address} \ - --env PUBLIC_OR_PROXY_ENDPOINT=https://public-endpoint \ - --env GRAPH_TYPE=gremlin \ - --env USING_PROXY_SERVER=true \ - --env IAM=false \ - --env GRAPH_CONNECTION_URL=https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182 \ - --env AWS_REGION=us-west-2 \ - --env SERVICE_TYPE=neptune-db \ - --env PROXY_SERVER_HTTPS_CONNECTION=true \ - --env GRAPH_EXP_FETCH_REQUEST_TIMEOUT=240000 \ - --env GRAPH_EXP_NODE_EXPANSION_LIMIT=500 \ - public.ecr.aws/neptune/graph-explorer -``` - ## Development For development guidance, see [Development](./additionaldocs/development/). diff --git a/additionaldocs/getting-started/first-connection.md b/additionaldocs/getting-started/first-connection.md index 58bf7844f..e83035b56 100644 --- a/additionaldocs/getting-started/first-connection.md +++ b/additionaldocs/getting-started/first-connection.md @@ -1,18 +1,114 @@ # First Connection -This guide contains detailed instructions that help when configuring Graph -Explorer with different graph database engines for the first time. After setting -up your database, see the [Connections UI](../user-guide/connections.md) guide -to learn how to create and manage connections within Graph Explorer. +Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. +You can connect to Amazon Neptune or you can also connect to open graph +databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 +protocol, such as Blazegraph. For additional details on connecting to different +graph databases, see [Connections](../user-guide/connections.md). -## Connecting to Neptune +## Providing a Default Connection + +To provide a default connection such that initial loads of Graph Explorer always +result with the same starting connection, modify the `docker run ...` command to +either take in a JSON configuration or runtime environment variables. If you +provide both a JSON configuration and environmental variables, the JSON will be +prioritized. + +### Environment Variables + +These are the valid environment variables used for the default connection, their +defaults, and their descriptions. + +- Required: + - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See + [Add a New Connection](#connections-ui) +- Optional + - `GRAPH_TYPE` - `None` - If not specified, multiple connections will be + created for every available graph type / query language. See + [Add a New Connection](#connections-ui) + - `USING_PROXY_SERVER` - `False` - See [Add a New Connection](#connections-ui) + - `IAM` - `False` - See [Add a New Connection](#connections-ui) + - `GRAPH_EXP_HTTPS_CONNECTION` - `True` - Controls whether Graph Explorer uses + SSL or not + - `PROXY_SERVER_HTTPS_CONNECTION` - `True` - Controls whether the server uses + SSL or not + - `GRAPH_EXP_FETCH_REQUEST_TIMEOUT` - `240000` - Controls the timeout for the + fetch request. Measured in milliseconds (i.e. 240000 is 240 seconds or 4 + minutes). + - `GRAPH_EXP_NODE_EXPANSION_LIMIT` - `None` - Controls the limit for node + counts and expansion queries. +- Conditionally Required: + - Required if `USING_PROXY_SERVER=True` + - `GRAPH_CONNECTION_URL` - `None` - See + [Add a New Connection](#connections-ui) + - Required if `USING_PROXY_SERVER=True` and `IAM=True` + - `AWS_REGION` - `None` - See [Add a New Connection](#connections-ui) + - `SERVICE_TYPE` - `neptune-db`, Set this as `neptune-db` for Neptune + database or `neptune-graph` for Neptune Analytics. + +### JSON Configuration Approach + +First, create a `config.json` file containing values for the connection +attributes: + +```js +{ + "PUBLIC_OR_PROXY_ENDPOINT": "https://public-endpoint", + "GRAPH_CONNECTION_URL": "https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182", + "USING_PROXY_SERVER": true, + "IAM": true, + "SERVICE_TYPE": "neptune-db", + "AWS_REGION": "us-west-2", + // Possible Values are "gremlin", "sparql", "openCypher" + "GRAPH_TYPE": "gremlin", + "GRAPH_EXP_HTTPS_CONNECTION": true, + "PROXY_SERVER_HTTPS_CONNECTION": true, + // Measured in milliseconds (i.e. 240000 is 240 seconds or 4 minutes) + "GRAPH_EXP_FETCH_REQUEST_TIMEOUT": 240000, + "GRAPH_EXP_NODE_EXPANSION_LIMIT": 500, +} +``` + +Pass the `config.json` file path to the `docker run` command. + +```bash +docker run -p 80:80 -p 443:443 \ + --env HOST={hostname-or-ip-address} \ + -v /path/to/config.json:/graph-explorer/config.json \ + public.ecr.aws/neptune/graph-explorer +``` + +### Environment Variable Approach + +Provide the desired connection variables directly to the `docker run` command, +as follows: + +```bash +docker run -p 80:80 -p 443:443 \ + --env HOST={hostname-or-ip-address} \ + --env PUBLIC_OR_PROXY_ENDPOINT=https://public-endpoint \ + --env GRAPH_TYPE=gremlin \ + --env USING_PROXY_SERVER=true \ + --env IAM=false \ + --env GRAPH_CONNECTION_URL=https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182 \ + --env AWS_REGION=us-west-2 \ + --env SERVICE_TYPE=neptune-db \ + --env PROXY_SERVER_HTTPS_CONNECTION=true \ + --env GRAPH_EXP_FETCH_REQUEST_TIMEOUT=240000 \ + --env GRAPH_EXP_NODE_EXPANSION_LIMIT=500 \ + public.ecr.aws/neptune/graph-explorer +``` + +## Database Configuration + +### Connecting to Neptune - Ensure that Graph Explorer has access to the Neptune instance by being in the same VPC or VPC peering. - If authentication is enabled, read query privileges are needed (See [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). -## Connecting to Gremlin-Server +### Connecting to Gremlin-Server If you are using the default Gremlin Server docker image, you can get the server running with the following commands: @@ -24,7 +120,7 @@ docker run -p 8182:8182 \ conf/gremlin-server-rest-modern.yaml ``` -### Enable REST +#### Enable REST Graph Explorer only supports HTTP(S) connections. When connecting to Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) @@ -39,7 +135,7 @@ Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) > /conf/gremlin-server.yaml > ``` -### Versions Prior to 3.7 +#### Versions Prior to 3.7 If you have a version of Gremlin Server prior to 3.7, you will need to make the following changes: @@ -52,7 +148,7 @@ following changes: support string ids. You can use `ANY`. - Build and run the Docker container as normal. -## Connecting to BlazeGraph +### Connecting to BlazeGraph - Build and run the Docker container as normal and connect the proxy-server to BlazeGraph and your workbench to the proxy-server. From 0fa03f133562440f3c449ceb3c42fd0064f44606 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 11:42:17 -0400 Subject: [PATCH 20/37] Move requirements in to getting started --- README.md | 12 ------------ additionaldocs/getting-started/README.md | 14 +++++++++----- additionaldocs/getting-started/requirements.md | 16 ++++++++++++++++ 3 files changed, 25 insertions(+), 17 deletions(-) create mode 100644 additionaldocs/getting-started/requirements.md diff --git a/README.md b/README.md index cd8b86192..298496219 100644 --- a/README.md +++ b/README.md @@ -33,18 +33,6 @@ databases and Graph Explorer, we recommend that you check out the - [Samples](./samples) - A collection of Docker Compose files that show various ways to configure and use Graph Explorer. -### Minimum Recommended Versions - -Graph Explorer does not block any particular versions of graph databases, but -the queries used may or may not succeed based on the version of the query -engine. - -For Neptune databases, we recommend -[version 1.2.1.0](https://docs.aws.amazon.com/neptune/latest/userguide/engine-releases-1.2.1.0.html) -or above, which include the summary API and TinkerPop 3.6.2. - -For non-Neptune databases, we recommend at least TinkerPop 3.6. - ## Features Overview Graph Explorer offers a comprehensive set of tools for interacting with graph diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 29c985301..c36b97d0a 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -5,7 +5,9 @@ time. ## Files in this section -1. [First Connection](first-connection.md) - Connecting to your first database +1. [Requirements](requirements.md) - System requirements and minimum recommended + versions +2. [First Connection](first-connection.md) - Connecting to your first database ## Prerequisites @@ -15,13 +17,15 @@ time. ## Quick Start Steps -1. **Deploy Graph Explorer** - Choose a deployment method from the +1. **Check requirements** - Review the [Requirements](requirements.md) to ensure + compatibility +2. **Deploy Graph Explorer** - Choose a deployment method from the [Deployment](../deployment/) section -2. **Configure your database** - Follow the +3. **Configure your database** - Follow the [First Connection](first-connection.md) guide for your database type -3. **Create a connection** - Use the +4. **Create a connection** - Use the [Connections UI](../user-guide/connections.md) to set up your connection -4. **Start exploring** - Begin using Graph Explorer with the +5. **Start exploring** - Begin using Graph Explorer with the [User Guide](../user-guide/) ## Troubleshooting diff --git a/additionaldocs/getting-started/requirements.md b/additionaldocs/getting-started/requirements.md new file mode 100644 index 000000000..890771d75 --- /dev/null +++ b/additionaldocs/getting-started/requirements.md @@ -0,0 +1,16 @@ +# Requirements + +This guide outlines the system requirements and minimum recommended versions for +Graph Explorer and supported graph databases. + +## Minimum Recommended Versions + +Graph Explorer does not block any particular versions of graph databases, but +the queries used may or may not succeed based on the version of the query +engine. + +For Neptune databases, we recommend +[version 1.2.1.0](https://docs.aws.amazon.com/neptune/latest/userguide/engine-releases-1.2.1.0.html) +or above, which include the summary API and TinkerPop 3.6.2. + +For non-Neptune databases, we recommend at least TinkerPop 3.6. From 049c669347ebcbbee90c325e9589e28d545570c2 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 11:56:12 -0400 Subject: [PATCH 21/37] Move security stuff to file --- Changelog.md | 4 +- README.md | 77 ------------------------- additionaldocs/user-guide/README.md | 10 ++-- additionaldocs/user-guide/security.md | 81 +++++++++++++++++++++++++++ 4 files changed, 89 insertions(+), 83 deletions(-) create mode 100644 additionaldocs/user-guide/security.md diff --git a/Changelog.md b/Changelog.md index 30d63b6c5..99b444e6e 100644 --- a/Changelog.md +++ b/Changelog.md @@ -137,7 +137,7 @@ editor with Neptune Analytics for the first time. As before, if you are a Neptune user concerned about data integrity, check out the -[instructions on configuring IAM permissions to restrict mutations](./README.md#permissions), +[instructions on configuring IAM permissions to restrict mutations](./additionaldocs/user-guide/security.md#permissions), ensuring that users can enforce read-only operations. ### New features & major changes @@ -171,7 +171,7 @@ database. You can review the results in the sidebar and choose to add all nodes For Neptune users concerned about data integrity, [the README](./README.md) now includes -[instructions on configuring IAM permissions to restrict mutations](./README.md#permissions), +[instructions on configuring IAM permissions to restrict mutations](./additionaldocs/user-guide/security.md#permissions), ensuring users can enforce read-only operations. The release also changes the default strategy for representing node & edge diff --git a/README.md b/README.md index 298496219..0f25ea303 100644 --- a/README.md +++ b/README.md @@ -63,83 +63,6 @@ If you're interested in our future development plans, check out our For development guidance, see [Development](./additionaldocs/development/). -## Security - -You can use Graph Explorer to connect to a publicly accessible graph database -endpoint, or connect to a proxy endpoint that redirects to a private graph -database endpoint. - -Graph Explorer supports the HTTPS protocol by default and provides a self-signed -certificate as part of the Docker image. You can choose to use HTTP instead by -changing the -[environment variable default settings](./additionaldocs/deployment/configuration.md). - -### HTTPS Connections - -If either Graph Explorer or the proxy-server are served over an HTTPS connection -(which it is by default), you will have to bypass the warning message from the -browser due to the included certificate being a self-signed certificate. You can -bypass by manually ignoring them from the browser or downloading the correct -certificate and configuring them to be trusted. Alternatively, you can provide -your own certificate. The following instructions can be used as an example to -bypass the warnings for Chrome, but note that different browsers and operating -systems will have slightly different steps. - -1. Download the certificate directly from the browser. For example, if using - Google Chrome, click the “Not Secure” section on the left of the URL bar and - select “Certificate is not valid” to show the certificate. Then click Details - tab and click Export at the bottom. -2. Once you have the certificate, you will need to trust it on your machine. For - MacOS, you can open the Keychain Access app. Select System under System - Keychains. Then go to File > Import Items... and import the certificate you - downloaded in the previous step. -3. Once imported, select the certificate and right-click to select "Get Info". - Expand the Trust section, and change the value of "When using this - certificate" to "Always Trust". -4. You should now refresh the browser and see that you can proceed to open the - application. For Chrome, the application will remain “Not Secure” due to the - fact that this is a self-signed certificate. If you have trouble accessing - Graph Explorer after completing the previous step and reloading the browser, - consider running a docker restart command and refreshing the browser again. - - -> [!TIP] -> -> To get rid of the “Not Secure” warning, see -[Using self-signed certificates on Chrome](./additionaldocs/development/#using-self-signed-certificates-on-chrome). - -## Permissions - -Graph Explorer does not provide any mechanisms for controlling user permissions. -If you are using Graph Explorer with AWS, Neptune permissions can be controlled -through IAM roles. - -For information about what permissions Graph Explorer requires check out the -documentation on -[SageMaker configuration](./additionaldocs/deployment/aws-sagemaker.md#minimum-database-permissions). - - -> [!CAUTION] -> -> By default, a Neptune Notebook will have full read & write access to Neptune data. - -## Authentication - -Authentication for Amazon Neptune connections is enabled using the -[SigV4 signing protocol](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). - -To use AWS IAM authentication, you must run requests through a proxy endpoint, -such as an EC2 instance, where credentials are resolved and where requests are -signed. - -To set up a connection in Graph Explorer UI with AWS IAM auth enabled on -Neptune, check Using Proxy-Server, then check AWS IAM Auth Enabled and type in -the AWS Region where the Neptune cluster is hosted (e.g., us-east-1). - -For further information on how AWS credentials are resolved in Graph Explorer, -refer to this -[documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html). - ## Health Check Status The `graph-explorer-proxy-server` provides a `/status` endpoint for monitoring diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 3ddd2fef3..1d4d96ff6 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -6,10 +6,12 @@ features and connect to different graph databases. ## Files in this section 1. [Connections](connections.md) - Managing database connections in the UI -2. [Settings](settings.md) - Application settings and configuration management -3. [Graph Explorer](graph-explorer.md) - Main graph visualization interface -4. [Table View](table-view.md) - Tabular data view and export functionality -5. [Data Explorer](data-explorer.md) - Node type data exploration +2. [Security](security.md) - Security considerations, authentication, and + permissions +3. [Settings](settings.md) - Application settings and configuration management +4. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +5. [Table View](table-view.md) - Tabular data view and export functionality +6. [Data Explorer](data-explorer.md) - Node type data exploration ## Prerequisites diff --git a/additionaldocs/user-guide/security.md b/additionaldocs/user-guide/security.md new file mode 100644 index 000000000..079415c8b --- /dev/null +++ b/additionaldocs/user-guide/security.md @@ -0,0 +1,81 @@ +# Security + +This guide covers security considerations, authentication methods, and +permissions when using Graph Explorer with graph databases. + +## Security + +You can use Graph Explorer to connect to a publicly accessible graph database +endpoint, or connect to a proxy endpoint that redirects to a private graph +database endpoint. + +Graph Explorer supports the HTTPS protocol by default and provides a self-signed +certificate as part of the Docker image. You can choose to use HTTP instead by +changing the +[environment variable default settings](../deployment/configuration.md). + +### HTTPS Connections + +If either Graph Explorer or the proxy-server are served over an HTTPS connection +(which it is by default), you will have to bypass the warning message from the +browser due to the included certificate being a self-signed certificate. You can +bypass by manually ignoring them from the browser or downloading the correct +certificate and configuring them to be trusted. Alternatively, you can provide +your own certificate. The following instructions can be used as an example to +bypass the warnings for Chrome, but note that different browsers and operating +systems will have slightly different steps. + +1. Download the certificate directly from the browser. For example, if using + Google Chrome, click the "Not Secure" section on the left of the URL bar and + select "Certificate is not valid" to show the certificate. Then click Details + tab and click Export at the bottom. +2. Once you have the certificate, you will need to trust it on your machine. For + MacOS, you can open the Keychain Access app. Select System under System + Keychains. Then go to File > Import Items... and import the certificate you + downloaded in the previous step. +3. Once imported, select the certificate and right-click to select "Get Info". + Expand the Trust section, and change the value of "When using this + certificate" to "Always Trust". +4. You should now refresh the browser and see that you can proceed to open the + application. For Chrome, the application will remain "Not Secure" due to the + fact that this is a self-signed certificate. If you have trouble accessing + Graph Explorer after completing the previous step and reloading the browser, + consider running a docker restart command and refreshing the browser again. + + +> [!TIP] +> +> To get rid of the "Not Secure" warning, see +[Using self-signed certificates on Chrome](../development/#using-self-signed-certificates-on-chrome). + +## Permissions + +Graph Explorer does not provide any mechanisms for controlling user permissions. +If you are using Graph Explorer with AWS, Neptune permissions can be controlled +through IAM roles. + +For information about what permissions Graph Explorer requires check out the +documentation on +[SageMaker configuration](../deployment/aws-sagemaker.md#minimum-database-permissions). + + +> [!CAUTION] +> +> By default, a Neptune Notebook will have full read & write access to Neptune data. + +## Authentication + +Authentication for Amazon Neptune connections is enabled using the +[SigV4 signing protocol](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). + +To use AWS IAM authentication, you must run requests through a proxy endpoint, +such as an EC2 instance, where credentials are resolved and where requests are +signed. + +To set up a connection in Graph Explorer UI with AWS IAM auth enabled on +Neptune, check Using Proxy-Server, then check AWS IAM Auth Enabled and type in +the AWS Region where the Neptune cluster is hosted (e.g., us-east-1). + +For further information on how AWS credentials are resolved in Graph Explorer, +refer to this +[documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html). From a51c6173d362b66f98d3cd4d653d4957b00de449 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 13:21:04 -0400 Subject: [PATCH 22/37] Move health check and logging to file --- README.md | 46 ----------------------- additionaldocs/user-guide/README.md | 10 +++-- additionaldocs/user-guide/monitoring.md | 50 +++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 50 deletions(-) create mode 100644 additionaldocs/user-guide/monitoring.md diff --git a/README.md b/README.md index 0f25ea303..1399e57f1 100644 --- a/README.md +++ b/README.md @@ -63,52 +63,6 @@ If you're interested in our future development plans, check out our For development guidance, see [Development](./additionaldocs/development/). -## Health Check Status - -The `graph-explorer-proxy-server` provides a `/status` endpoint for monitoring -its health and readiness. This endpoint is crucial for ensuring reliable service -operation and can be utilized in various deployment scenarios. - -**Key Features:** - -- **Health Check:** The `/status` endpoint serves as a basic health check, - confirming that the Express server is running and responding. This is - essential for load balancers (like AWS ALB) to determine if the server is - operational and should receive traffic. -- **Readiness Probe:** It also functions as a readiness probe in container - orchestration systems (like Kubernetes). This allows the orchestrator to know - when the server is ready to accept requests, preventing traffic from being - routed to instances that are still starting up or experiencing issues. -- **Expected Response:** A successful health check or readiness probe will - result in an HTTP `200 OK` response with the body containing `OK`. - -## Logging - -Logs are, by default, sent to the console and will be visible as output to the -docker logs. If you want to access the full set of logs, you can run -`docker logs {container name or id}`. - -The log level will be set via the `LOG_LEVEL` env variable at -`/packages/graph-explorer/.env` where the possible options, from highest to -lowest, are `error`, `warn`, `info`, `debug`, and `trace` such that `error` is -the highest level and will only include logs labeled as errors and `trace` the -lowest and will include any type of log. - -By default, the log level is set to `info` and the only type of logs generated -are those of `error`, `info`, or `debug`. If you need more detailed logs, you -can change the log level from `info` in the default .env file to `debug` and the -logs will begin printing the error's stack trace. - -Within node-server.js, you'll notice three things. - -1. A `proxyLogger` object - This is responsible for actually recording the logs. -2. An `errorHandler` - This automatically sends errors to the `proxyLogger` and - can log extra information by adding wanted text to the error object at a key - called `extraInfo`. -3. An endpoint called `/logger` - This is how you would log things from the - browser. It needs a log level and message header passed and you can then - expect to see the message logged at the provided log level. - ## Contributing Guidelines See [CONTRIBUTING](./CONTRIBUTING.md) for more information. diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 1d4d96ff6..0c4bc9e78 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -8,10 +8,12 @@ features and connect to different graph databases. 1. [Connections](connections.md) - Managing database connections in the UI 2. [Security](security.md) - Security considerations, authentication, and permissions -3. [Settings](settings.md) - Application settings and configuration management -4. [Graph Explorer](graph-explorer.md) - Main graph visualization interface -5. [Table View](table-view.md) - Tabular data view and export functionality -6. [Data Explorer](data-explorer.md) - Node type data exploration +3. [Monitoring](monitoring.md) - Health checks, logging, and monitoring + capabilities +4. [Settings](settings.md) - Application settings and configuration management +5. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +6. [Table View](table-view.md) - Tabular data view and export functionality +7. [Data Explorer](data-explorer.md) - Node type data exploration ## Prerequisites diff --git a/additionaldocs/user-guide/monitoring.md b/additionaldocs/user-guide/monitoring.md new file mode 100644 index 000000000..02edccb93 --- /dev/null +++ b/additionaldocs/user-guide/monitoring.md @@ -0,0 +1,50 @@ +# Monitoring + +This guide covers monitoring capabilities, health checks, and logging +configuration for Graph Explorer. + +## Health Check Status + +The `graph-explorer-proxy-server` provides a `/status` endpoint for monitoring +its health and readiness. This endpoint is crucial for ensuring reliable service +operation and can be utilized in various deployment scenarios. + +**Key Features:** + +- **Health Check:** The `/status` endpoint serves as a basic health check, + confirming that the Express server is running and responding. This is + essential for load balancers (like AWS ALB) to determine if the server is + operational and should receive traffic. +- **Readiness Probe:** It also functions as a readiness probe in container + orchestration systems (like Kubernetes). This allows the orchestrator to know + when the server is ready to accept requests, preventing traffic from being + routed to instances that are still starting up or experiencing issues. +- **Expected Response:** A successful health check or readiness probe will + result in an HTTP `200 OK` response with the body containing `OK`. + +## Logging + +Logs are, by default, sent to the console and will be visible as output to the +docker logs. If you want to access the full set of logs, you can run +`docker logs {container name or id}`. + +The log level will be set via the `LOG_LEVEL` env variable at +`/packages/graph-explorer/.env` where the possible options, from highest to +lowest, are `error`, `warn`, `info`, `debug`, and `trace` such that `error` is +the highest level and will only include logs labeled as errors and `trace` the +lowest and will include any type of log. + +By default, the log level is set to `info` and the only type of logs generated +are those of `error`, `info`, or `debug`. If you need more detailed logs, you +can change the log level from `info` in the default .env file to `debug` and the +logs will begin printing the error's stack trace. + +Within node-server.js, you'll notice three things. + +1. A `proxyLogger` object - This is responsible for actually recording the logs. +2. An `errorHandler` - This automatically sends errors to the `proxyLogger` and + can log extra information by adding wanted text to the error object at a key + called `extraInfo`. +3. An endpoint called `/logger` - This is how you would log things from the + browser. It needs a log level and message header passed and you can then + expect to see the message logged at the provided log level. From 2f72b48b6f4b5fcdbc7c099131289d729341152f Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 13:24:18 -0400 Subject: [PATCH 23/37] Move default connection to its own file --- additionaldocs/deployment/aws-ecs-fargate.md | 4 +- additionaldocs/getting-started/README.md | 9 +- .../getting-started/default-connection.md | 98 +++++++++++++++++++ .../getting-started/first-connection.md | 98 +------------------ 4 files changed, 112 insertions(+), 97 deletions(-) create mode 100644 additionaldocs/getting-started/default-connection.md diff --git a/additionaldocs/deployment/aws-ecs-fargate.md b/additionaldocs/deployment/aws-ecs-fargate.md index f9ffe4a50..47c620404 100644 --- a/additionaldocs/deployment/aws-ecs-fargate.md +++ b/additionaldocs/deployment/aws-ecs-fargate.md @@ -195,8 +195,8 @@ the specified domain names. - `taskRoleArn` and `executionRoleArn`: The ARN of the IAM role created in step "Create a new IAM role and permission policies". - `environment` variables section (see - [Default Connections](https://github.com/aws/graph-explorer#providing-a-default-connection) - for more details): + [Default Connections](../getting-started/default-connection.md) for more + details): - `AWS_REGION`: The AWS region in which your Neptune cluster is located. - `GRAPH_TYPE`: The query language for your initial connection. - `IAM`: Set this to `true` to use SigV4 signed requests, if your Neptune diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index c36b97d0a..1a3a17a83 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -8,6 +8,8 @@ time. 1. [Requirements](requirements.md) - System requirements and minimum recommended versions 2. [First Connection](first-connection.md) - Connecting to your first database +3. [Default Connection](default-connection.md) - Configuring automatic default + connections ## Prerequisites @@ -23,9 +25,12 @@ time. [Deployment](../deployment/) section 3. **Configure your database** - Follow the [First Connection](first-connection.md) guide for your database type -4. **Create a connection** - Use the +4. **Set up default connection (optional)** - Use the + [Default Connection](default-connection.md) guide to configure automatic + connections +5. **Create a connection** - Use the [Connections UI](../user-guide/connections.md) to set up your connection -5. **Start exploring** - Begin using Graph Explorer with the +6. **Start exploring** - Begin using Graph Explorer with the [User Guide](../user-guide/) ## Troubleshooting diff --git a/additionaldocs/getting-started/default-connection.md b/additionaldocs/getting-started/default-connection.md new file mode 100644 index 000000000..288921771 --- /dev/null +++ b/additionaldocs/getting-started/default-connection.md @@ -0,0 +1,98 @@ +# Default Connection + +This guide explains how to configure Graph Explorer with a default connection +that loads automatically when the application starts. + +## Providing a Default Connection + +To provide a default connection such that initial loads of Graph Explorer always +result with the same starting connection, modify the `docker run ...` command to +either take in a JSON configuration or runtime environment variables. If you +provide both a JSON configuration and environmental variables, the JSON will be +prioritized. + +### Environment Variables + +These are the valid environment variables used for the default connection, their +defaults, and their descriptions. + +- Required: + - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See + [Connections UI](../user-guide/connections.md) +- Optional + - `GRAPH_TYPE` - `None` - If not specified, multiple connections will be + created for every available graph type / query language. See + [Connections UI](../user-guide/connections.md) + - `USING_PROXY_SERVER` - `False` - See + [Connections UI](../user-guide/connections.md) + - `IAM` - `False` - See [Connections UI](../user-guide/connections.md) + - `GRAPH_EXP_HTTPS_CONNECTION` - `True` - Controls whether Graph Explorer uses + SSL or not + - `PROXY_SERVER_HTTPS_CONNECTION` - `True` - Controls whether the server uses + SSL or not + - `GRAPH_EXP_FETCH_REQUEST_TIMEOUT` - `240000` - Controls the timeout for the + fetch request. Measured in milliseconds (i.e. 240000 is 240 seconds or 4 + minutes). + - `GRAPH_EXP_NODE_EXPANSION_LIMIT` - `None` - Controls the limit for node + counts and expansion queries. +- Conditionally Required: + - Required if `USING_PROXY_SERVER=True` + - `GRAPH_CONNECTION_URL` - `None` - See + [Connections UI](../user-guide/connections.md) + - Required if `USING_PROXY_SERVER=True` and `IAM=True` + - `AWS_REGION` - `None` - See [Connections UI](../user-guide/connections.md) + - `SERVICE_TYPE` - `neptune-db`, Set this as `neptune-db` for Neptune + database or `neptune-graph` for Neptune Analytics. + +### JSON Configuration Approach + +First, create a `config.json` file containing values for the connection +attributes: + +```js +{ + "PUBLIC_OR_PROXY_ENDPOINT": "https://public-endpoint", + "GRAPH_CONNECTION_URL": "https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182", + "USING_PROXY_SERVER": true, + "IAM": true, + "SERVICE_TYPE": "neptune-db", + "AWS_REGION": "us-west-2", + // Possible Values are "gremlin", "sparql", "openCypher" + "GRAPH_TYPE": "gremlin", + "GRAPH_EXP_HTTPS_CONNECTION": true, + "PROXY_SERVER_HTTPS_CONNECTION": true, + // Measured in milliseconds (i.e. 240000 is 240 seconds or 4 minutes) + "GRAPH_EXP_FETCH_REQUEST_TIMEOUT": 240000, + "GRAPH_EXP_NODE_EXPANSION_LIMIT": 500, +} +``` + +Pass the `config.json` file path to the `docker run` command. + +```bash +docker run -p 80:80 -p 443:443 \ + --env HOST={hostname-or-ip-address} \ + -v /path/to/config.json:/graph-explorer/config.json \ + public.ecr.aws/neptune/graph-explorer +``` + +### Environment Variable Approach + +Provide the desired connection variables directly to the `docker run` command, +as follows: + +```bash +docker run -p 80:80 -p 443:443 \ + --env HOST={hostname-or-ip-address} \ + --env PUBLIC_OR_PROXY_ENDPOINT=https://public-endpoint \ + --env GRAPH_TYPE=gremlin \ + --env USING_PROXY_SERVER=true \ + --env IAM=false \ + --env GRAPH_CONNECTION_URL=https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182 \ + --env AWS_REGION=us-west-2 \ + --env SERVICE_TYPE=neptune-db \ + --env PROXY_SERVER_HTTPS_CONNECTION=true \ + --env GRAPH_EXP_FETCH_REQUEST_TIMEOUT=240000 \ + --env GRAPH_EXP_NODE_EXPANSION_LIMIT=500 \ + public.ecr.aws/neptune/graph-explorer +``` diff --git a/additionaldocs/getting-started/first-connection.md b/additionaldocs/getting-started/first-connection.md index e83035b56..e1e1050c9 100644 --- a/additionaldocs/getting-started/first-connection.md +++ b/additionaldocs/getting-started/first-connection.md @@ -1,104 +1,16 @@ # First Connection +This guide contains detailed instructions that help when configuring Graph +Explorer with different graph database engines for the first time. After setting +up your database, see the [Connections UI](../user-guide/connections.md) guide +to learn how to create and manage connections within Graph Explorer. + Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. You can connect to Amazon Neptune or you can also connect to open graph databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 protocol, such as Blazegraph. For additional details on connecting to different graph databases, see [Connections](../user-guide/connections.md). -## Providing a Default Connection - -To provide a default connection such that initial loads of Graph Explorer always -result with the same starting connection, modify the `docker run ...` command to -either take in a JSON configuration or runtime environment variables. If you -provide both a JSON configuration and environmental variables, the JSON will be -prioritized. - -### Environment Variables - -These are the valid environment variables used for the default connection, their -defaults, and their descriptions. - -- Required: - - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See - [Add a New Connection](#connections-ui) -- Optional - - `GRAPH_TYPE` - `None` - If not specified, multiple connections will be - created for every available graph type / query language. See - [Add a New Connection](#connections-ui) - - `USING_PROXY_SERVER` - `False` - See [Add a New Connection](#connections-ui) - - `IAM` - `False` - See [Add a New Connection](#connections-ui) - - `GRAPH_EXP_HTTPS_CONNECTION` - `True` - Controls whether Graph Explorer uses - SSL or not - - `PROXY_SERVER_HTTPS_CONNECTION` - `True` - Controls whether the server uses - SSL or not - - `GRAPH_EXP_FETCH_REQUEST_TIMEOUT` - `240000` - Controls the timeout for the - fetch request. Measured in milliseconds (i.e. 240000 is 240 seconds or 4 - minutes). - - `GRAPH_EXP_NODE_EXPANSION_LIMIT` - `None` - Controls the limit for node - counts and expansion queries. -- Conditionally Required: - - Required if `USING_PROXY_SERVER=True` - - `GRAPH_CONNECTION_URL` - `None` - See - [Add a New Connection](#connections-ui) - - Required if `USING_PROXY_SERVER=True` and `IAM=True` - - `AWS_REGION` - `None` - See [Add a New Connection](#connections-ui) - - `SERVICE_TYPE` - `neptune-db`, Set this as `neptune-db` for Neptune - database or `neptune-graph` for Neptune Analytics. - -### JSON Configuration Approach - -First, create a `config.json` file containing values for the connection -attributes: - -```js -{ - "PUBLIC_OR_PROXY_ENDPOINT": "https://public-endpoint", - "GRAPH_CONNECTION_URL": "https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182", - "USING_PROXY_SERVER": true, - "IAM": true, - "SERVICE_TYPE": "neptune-db", - "AWS_REGION": "us-west-2", - // Possible Values are "gremlin", "sparql", "openCypher" - "GRAPH_TYPE": "gremlin", - "GRAPH_EXP_HTTPS_CONNECTION": true, - "PROXY_SERVER_HTTPS_CONNECTION": true, - // Measured in milliseconds (i.e. 240000 is 240 seconds or 4 minutes) - "GRAPH_EXP_FETCH_REQUEST_TIMEOUT": 240000, - "GRAPH_EXP_NODE_EXPANSION_LIMIT": 500, -} -``` - -Pass the `config.json` file path to the `docker run` command. - -```bash -docker run -p 80:80 -p 443:443 \ - --env HOST={hostname-or-ip-address} \ - -v /path/to/config.json:/graph-explorer/config.json \ - public.ecr.aws/neptune/graph-explorer -``` - -### Environment Variable Approach - -Provide the desired connection variables directly to the `docker run` command, -as follows: - -```bash -docker run -p 80:80 -p 443:443 \ - --env HOST={hostname-or-ip-address} \ - --env PUBLIC_OR_PROXY_ENDPOINT=https://public-endpoint \ - --env GRAPH_TYPE=gremlin \ - --env USING_PROXY_SERVER=true \ - --env IAM=false \ - --env GRAPH_CONNECTION_URL=https://cluster-cqmizgqgrsbf.us-west-2.neptune.amazonaws.com:8182 \ - --env AWS_REGION=us-west-2 \ - --env SERVICE_TYPE=neptune-db \ - --env PROXY_SERVER_HTTPS_CONNECTION=true \ - --env GRAPH_EXP_FETCH_REQUEST_TIMEOUT=240000 \ - --env GRAPH_EXP_NODE_EXPANSION_LIMIT=500 \ - public.ecr.aws/neptune/graph-explorer -``` - ## Database Configuration ### Connecting to Neptune From 72cb406270801ed3ec6ea9a19a574c6d9ffefb12 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 13:24:38 -0400 Subject: [PATCH 24/37] Fix links --- additionaldocs/development/development-setup.md | 2 +- additionaldocs/user-guide/security.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/additionaldocs/development/development-setup.md b/additionaldocs/development/development-setup.md index da65a3ebd..65744ea6c 100644 --- a/additionaldocs/development/development-setup.md +++ b/additionaldocs/development/development-setup.md @@ -149,7 +149,7 @@ You can build the Docker image locally by following the steps below. ## Using Self-signed certificates on Chrome For browsers like Safari and Firefox, -[trusting the certificate from the browser](../../README.md#https-connections) +[trusting the certificate from the browser](../user-guide/security.md#https-connections) is enough to bypass the "Not Secure" warning. However, Chrome treats self-signed certificates differently. If you want to use a self-signed certificate on Chrome **without** the "Not Secure" warning and you do not have your own certificate, diff --git a/additionaldocs/user-guide/security.md b/additionaldocs/user-guide/security.md index 079415c8b..83ee0fc09 100644 --- a/additionaldocs/user-guide/security.md +++ b/additionaldocs/user-guide/security.md @@ -46,7 +46,7 @@ systems will have slightly different steps. > [!TIP] > > To get rid of the "Not Secure" warning, see -[Using self-signed certificates on Chrome](../development/#using-self-signed-certificates-on-chrome). +[Using self-signed certificates on Chrome](../development/development-setup.md#using-self-signed-certificates-on-chrome). ## Permissions From 21cb085b3ef0b9ca0850cdb49abaa5daaea5854d Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 13:32:04 -0400 Subject: [PATCH 25/37] Move default-connection and update requirements --- additionaldocs/deployment/aws-ecs-fargate.md | 2 +- additionaldocs/getting-started/README.md | 24 +++---- .../getting-started/first-connection.md | 69 ------------------- .../getting-started/requirements.md | 68 ++++++++++++++++++ additionaldocs/user-guide/README.md | 14 ++-- additionaldocs/user-guide/connections.md | 3 +- .../default-connection.md | 15 ++-- 7 files changed, 95 insertions(+), 100 deletions(-) delete mode 100644 additionaldocs/getting-started/first-connection.md rename additionaldocs/{getting-started => user-guide}/default-connection.md (86%) diff --git a/additionaldocs/deployment/aws-ecs-fargate.md b/additionaldocs/deployment/aws-ecs-fargate.md index 47c620404..cf2d39eba 100644 --- a/additionaldocs/deployment/aws-ecs-fargate.md +++ b/additionaldocs/deployment/aws-ecs-fargate.md @@ -195,7 +195,7 @@ the specified domain names. - `taskRoleArn` and `executionRoleArn`: The ARN of the IAM role created in step "Create a new IAM role and permission policies". - `environment` variables section (see - [Default Connections](../getting-started/default-connection.md) for more + [Default Connections](../user-guide/default-connection.md) for more details): - `AWS_REGION`: The AWS region in which your Neptune cluster is located. - `GRAPH_TYPE`: The query language for your initial connection. diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 1a3a17a83..688813bf2 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -5,11 +5,8 @@ time. ## Files in this section -1. [Requirements](requirements.md) - System requirements and minimum recommended - versions -2. [First Connection](first-connection.md) - Connecting to your first database -3. [Default Connection](default-connection.md) - Configuring automatic default - connections +1. [Requirements](requirements.md) - System requirements, minimum recommended + versions, and database configuration ## Prerequisites @@ -19,18 +16,17 @@ time. ## Quick Start Steps -1. **Check requirements** - Review the [Requirements](requirements.md) to ensure - compatibility +1. **Check requirements and configure database** - Review the + [Requirements](requirements.md) to ensure compatibility and follow the + database configuration instructions 2. **Deploy Graph Explorer** - Choose a deployment method from the [Deployment](../deployment/) section -3. **Configure your database** - Follow the - [First Connection](first-connection.md) guide for your database type -4. **Set up default connection (optional)** - Use the - [Default Connection](default-connection.md) guide to configure automatic - connections -5. **Create a connection** - Use the +3. **Set up default connection (optional)** - Use the + [Default Connection](../user-guide/default-connection.md) guide to configure + automatic connections +4. **Create a connection** - Use the [Connections UI](../user-guide/connections.md) to set up your connection -6. **Start exploring** - Begin using Graph Explorer with the +5. **Start exploring** - Begin using Graph Explorer with the [User Guide](../user-guide/) ## Troubleshooting diff --git a/additionaldocs/getting-started/first-connection.md b/additionaldocs/getting-started/first-connection.md deleted file mode 100644 index e1e1050c9..000000000 --- a/additionaldocs/getting-started/first-connection.md +++ /dev/null @@ -1,69 +0,0 @@ -# First Connection - -This guide contains detailed instructions that help when configuring Graph -Explorer with different graph database engines for the first time. After setting -up your database, see the [Connections UI](../user-guide/connections.md) guide -to learn how to create and manage connections within Graph Explorer. - -Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. -You can connect to Amazon Neptune or you can also connect to open graph -databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 -protocol, such as Blazegraph. For additional details on connecting to different -graph databases, see [Connections](../user-guide/connections.md). - -## Database Configuration - -### Connecting to Neptune - -- Ensure that Graph Explorer has access to the Neptune instance by being in the - same VPC or VPC peering. -- If authentication is enabled, read query privileges are needed (See - [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). - -### Connecting to Gremlin-Server - -If you are using the default Gremlin Server docker image, you can get the server -running with the following commands: - -``` -docker pull tinkerpop/gremlin-server:latest -docker run -p 8182:8182 \ - tinkerpop/gremlin-server:latest \ - conf/gremlin-server-rest-modern.yaml -``` - -#### Enable REST - -Graph Explorer only supports HTTP(S) connections. When connecting to -Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) -(i.e. -[Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). - - -> [!TIP] -> The Gremlin Server configuration can be usually found at: -> -> ``` -> /conf/gremlin-server.yaml -> ``` - -#### Versions Prior to 3.7 - -If you have a version of Gremlin Server prior to 3.7, you will need to make the -following changes: - -- **Enable property returns** - Remove - ".withStrategies(ReferenceElementStrategy)" from - `/scripts/generate-modern.groovy` so that properties are returned. -- **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and - `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to - support string ids. You can use `ANY`. -- Build and run the Docker container as normal. - -### Connecting to BlazeGraph - -- Build and run the Docker container as normal and connect the proxy-server to - BlazeGraph and your workbench to the proxy-server. -- If using Docker, ensure that the container running the workbench can properly - access the container running BlazeGraph. You can find documentation on how to - connect containers via [Docker networks](https://docs.docker.com/network/). diff --git a/additionaldocs/getting-started/requirements.md b/additionaldocs/getting-started/requirements.md index 890771d75..af95405a9 100644 --- a/additionaldocs/getting-started/requirements.md +++ b/additionaldocs/getting-started/requirements.md @@ -14,3 +14,71 @@ For Neptune databases, we recommend or above, which include the summary API and TinkerPop 3.6.2. For non-Neptune databases, we recommend at least TinkerPop 3.6. + +## Database Configuration + +This section contains detailed instructions that help when configuring Graph +Explorer with different graph database engines for the first time. After setting +up your database, see the [Connections UI](../user-guide/connections.md) guide +to learn how to create and manage connections within Graph Explorer. + +Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. +You can connect to Amazon Neptune or you can also connect to open graph +databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 +protocol, such as Blazegraph. For additional details on connecting to different +graph databases, see [Connections](../user-guide/connections.md). + +### Connecting to Neptune + +- Ensure that Graph Explorer has access to the Neptune instance by being in the + same VPC or VPC peering. +- If authentication is enabled, read query privileges are needed (See + [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). + +### Connecting to Gremlin-Server + +If you are using the default Gremlin Server docker image, you can get the server +running with the following commands: + +``` +docker pull tinkerpop/gremlin-server:latest +docker run -p 8182:8182 \ + tinkerpop/gremlin-server:latest \ + conf/gremlin-server-rest-modern.yaml +``` + +#### Enable REST + +Graph Explorer only supports HTTP(S) connections. When connecting to +Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) +(i.e. +[Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). + + +> [!TIP] +> The Gremlin Server configuration can be usually found at: +> +> ``` +> /conf/gremlin-server.yaml +> ``` + +#### Versions Prior to 3.7 + +If you have a version of Gremlin Server prior to 3.7, you will need to make the +following changes: + +- **Enable property returns** - Remove + ".withStrategies(ReferenceElementStrategy)" from + `/scripts/generate-modern.groovy` so that properties are returned. +- **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and + `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to + support string ids. You can use `ANY`. +- Build and run the Docker container as normal. + +### Connecting to BlazeGraph + +- Build and run the Docker container as normal and connect the proxy-server to + BlazeGraph and your workbench to the proxy-server. +- If using Docker, ensure that the container running the workbench can properly + access the container running BlazeGraph. You can find documentation on how to + connect containers via [Docker networks](https://docs.docker.com/network/). diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 0c4bc9e78..fa2ed5a1e 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -6,14 +6,16 @@ features and connect to different graph databases. ## Files in this section 1. [Connections](connections.md) - Managing database connections in the UI -2. [Security](security.md) - Security considerations, authentication, and +2. [Default Connection](default-connection.md) - Configuring automatic default + connections +3. [Security](security.md) - Security considerations, authentication, and permissions -3. [Monitoring](monitoring.md) - Health checks, logging, and monitoring +4. [Monitoring](monitoring.md) - Health checks, logging, and monitoring capabilities -4. [Settings](settings.md) - Application settings and configuration management -5. [Graph Explorer](graph-explorer.md) - Main graph visualization interface -6. [Table View](table-view.md) - Tabular data view and export functionality -7. [Data Explorer](data-explorer.md) - Node type data exploration +5. [Settings](settings.md) - Application settings and configuration management +6. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +7. [Table View](table-view.md) - Tabular data view and export functionality +8. [Data Explorer](data-explorer.md) - Node type data exploration ## Prerequisites diff --git a/additionaldocs/user-guide/connections.md b/additionaldocs/user-guide/connections.md index 1d7fec9a9..39b398c0f 100644 --- a/additionaldocs/user-guide/connections.md +++ b/additionaldocs/user-guide/connections.md @@ -2,7 +2,8 @@ This guide covers how to manage connections within the Graph Explorer application. For information on configuring different graph database engines, -see the [First Connection](../getting-started/first-connection.md) guide. +see the +[Requirements](../getting-started/requirements.md#database-configuration) guide. You can create and manage connections to graph databases using this feature. Connections is accessible as the first screen after deploying the application, diff --git a/additionaldocs/getting-started/default-connection.md b/additionaldocs/user-guide/default-connection.md similarity index 86% rename from additionaldocs/getting-started/default-connection.md rename to additionaldocs/user-guide/default-connection.md index 288921771..09ab1aef4 100644 --- a/additionaldocs/getting-started/default-connection.md +++ b/additionaldocs/user-guide/default-connection.md @@ -17,15 +17,13 @@ These are the valid environment variables used for the default connection, their defaults, and their descriptions. - Required: - - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See - [Connections UI](../user-guide/connections.md) + - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See [Connections UI](connections.md) - Optional - `GRAPH_TYPE` - `None` - If not specified, multiple connections will be created for every available graph type / query language. See - [Connections UI](../user-guide/connections.md) - - `USING_PROXY_SERVER` - `False` - See - [Connections UI](../user-guide/connections.md) - - `IAM` - `False` - See [Connections UI](../user-guide/connections.md) + [Connections UI](connections.md) + - `USING_PROXY_SERVER` - `False` - See [Connections UI](connections.md) + - `IAM` - `False` - See [Connections UI](connections.md) - `GRAPH_EXP_HTTPS_CONNECTION` - `True` - Controls whether Graph Explorer uses SSL or not - `PROXY_SERVER_HTTPS_CONNECTION` - `True` - Controls whether the server uses @@ -37,10 +35,9 @@ defaults, and their descriptions. counts and expansion queries. - Conditionally Required: - Required if `USING_PROXY_SERVER=True` - - `GRAPH_CONNECTION_URL` - `None` - See - [Connections UI](../user-guide/connections.md) + - `GRAPH_CONNECTION_URL` - `None` - See [Connections UI](connections.md) - Required if `USING_PROXY_SERVER=True` and `IAM=True` - - `AWS_REGION` - `None` - See [Connections UI](../user-guide/connections.md) + - `AWS_REGION` - `None` - See [Connections UI](connections.md) - `SERVICE_TYPE` - `neptune-db`, Set this as `neptune-db` for Neptune database or `neptune-graph` for Neptune Analytics. From d2f2c7bc4aa4d728e239f24458db1c30d42e0c38 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 13:54:34 -0400 Subject: [PATCH 26/37] Move monitoring to administration --- additionaldocs/README.md | 1 + additionaldocs/administration/README.md | 30 +++++++++++++++++++ .../monitoring.md | 0 additionaldocs/user-guide/README.md | 10 +++---- 4 files changed, 35 insertions(+), 6 deletions(-) create mode 100644 additionaldocs/administration/README.md rename additionaldocs/{user-guide => administration}/monitoring.md (100%) diff --git a/additionaldocs/README.md b/additionaldocs/README.md index de8a97ba7..a7449aaef 100644 --- a/additionaldocs/README.md +++ b/additionaldocs/README.md @@ -3,5 +3,6 @@ - [Getting Started](./getting-started) - [User Guide](./user-guide) - [Deployment](./deployment) +- [Administration](./administration) - [Development](./development) - [Troubleshooting](./troubleshooting/) diff --git a/additionaldocs/administration/README.md b/additionaldocs/administration/README.md new file mode 100644 index 000000000..ada16455f --- /dev/null +++ b/additionaldocs/administration/README.md @@ -0,0 +1,30 @@ +# Administration + +This section contains guides for administrators and operators who need to +manage, monitor, and maintain Graph Explorer deployments. + +## Files in this section + +1. [Monitoring](monitoring.md) - Health checks, logging, and monitoring + capabilities + +## Prerequisites + +- Graph Explorer deployed and running +- Administrative access to the deployment environment +- Basic familiarity with system administration and monitoring concepts + +## Overview + +Administration tasks typically include: + +- **Monitoring**: Setting up health checks and log monitoring +- **Maintenance**: Regular operational tasks and updates +- **Security**: Operational security considerations +- **Backup & Recovery**: Protecting configuration and ensuring business + continuity + +## Next Steps + +After setting up monitoring, consider implementing backup procedures and +establishing maintenance schedules for your Graph Explorer deployment. diff --git a/additionaldocs/user-guide/monitoring.md b/additionaldocs/administration/monitoring.md similarity index 100% rename from additionaldocs/user-guide/monitoring.md rename to additionaldocs/administration/monitoring.md diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index fa2ed5a1e..83d69fb0a 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -10,12 +10,10 @@ features and connect to different graph databases. connections 3. [Security](security.md) - Security considerations, authentication, and permissions -4. [Monitoring](monitoring.md) - Health checks, logging, and monitoring - capabilities -5. [Settings](settings.md) - Application settings and configuration management -6. [Graph Explorer](graph-explorer.md) - Main graph visualization interface -7. [Table View](table-view.md) - Tabular data view and export functionality -8. [Data Explorer](data-explorer.md) - Node type data exploration +4. [Settings](settings.md) - Application settings and configuration management +5. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +6. [Table View](table-view.md) - Tabular data view and export functionality +7. [Data Explorer](data-explorer.md) - Node type data exploration ## Prerequisites From 1df941b3b72322bc4421b67e1ea76fa19da8f3bd Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 13:58:00 -0400 Subject: [PATCH 27/37] Move backup-restore --- additionaldocs/administration/README.md | 6 ++++-- .../{troubleshooting => administration}/backup-restore.md | 0 additionaldocs/troubleshooting/README.md | 4 +--- 3 files changed, 5 insertions(+), 5 deletions(-) rename additionaldocs/{troubleshooting => administration}/backup-restore.md (100%) diff --git a/additionaldocs/administration/README.md b/additionaldocs/administration/README.md index ada16455f..29018b69c 100644 --- a/additionaldocs/administration/README.md +++ b/additionaldocs/administration/README.md @@ -7,6 +7,8 @@ manage, monitor, and maintain Graph Explorer deployments. 1. [Monitoring](monitoring.md) - Health checks, logging, and monitoring capabilities +2. [Backup and Restore](backup-restore.md) - Backing up and restoring Graph + Explorer configuration ## Prerequisites @@ -19,10 +21,10 @@ manage, monitor, and maintain Graph Explorer deployments. Administration tasks typically include: - **Monitoring**: Setting up health checks and log monitoring -- **Maintenance**: Regular operational tasks and updates -- **Security**: Operational security considerations - **Backup & Recovery**: Protecting configuration and ensuring business continuity +- **Maintenance**: Regular operational tasks and updates +- **Security**: Operational security considerations ## Next Steps diff --git a/additionaldocs/troubleshooting/backup-restore.md b/additionaldocs/administration/backup-restore.md similarity index 100% rename from additionaldocs/troubleshooting/backup-restore.md rename to additionaldocs/administration/backup-restore.md diff --git a/additionaldocs/troubleshooting/README.md b/additionaldocs/troubleshooting/README.md index 514d40c75..87f4a15c5 100644 --- a/additionaldocs/troubleshooting/README.md +++ b/additionaldocs/troubleshooting/README.md @@ -9,9 +9,7 @@ diagnose problems with Graph Explorer. certificate issues 2. [Schema Sync](schema-sync.md) - Schema synchronization failures and connection problems -3. [Backup and Restore](backup-restore.md) - Backing up and restoring Graph - Explorer configuration -4. [SageMaker Logs](sagemaker-logs.md) - Gathering logs when running on Amazon +3. [SageMaker Logs](sagemaker-logs.md) - Gathering logs when running on Amazon SageMaker ## General Troubleshooting Tips From d72ed7a696d38c8bfbce37447d62494799f1ff34 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:02:53 -0400 Subject: [PATCH 28/37] Move logging docs --- additionaldocs/administration/monitoring.md | 29 +++++++++++++- additionaldocs/troubleshooting/README.md | 4 +- .../troubleshooting/sagemaker-issues.md | 17 ++++++++ .../troubleshooting/sagemaker-logs.md | 40 ------------------- 4 files changed, 47 insertions(+), 43 deletions(-) create mode 100644 additionaldocs/troubleshooting/sagemaker-issues.md delete mode 100644 additionaldocs/troubleshooting/sagemaker-logs.md diff --git a/additionaldocs/administration/monitoring.md b/additionaldocs/administration/monitoring.md index 02edccb93..bc66d1f61 100644 --- a/additionaldocs/administration/monitoring.md +++ b/additionaldocs/administration/monitoring.md @@ -1,7 +1,7 @@ # Monitoring This guide covers monitoring capabilities, health checks, and logging -configuration for Graph Explorer. +configuration for Graph Explorer across different deployment environments. ## Health Check Status @@ -48,3 +48,30 @@ Within node-server.js, you'll notice three things. 3. An endpoint called `/logger` - This is how you would log things from the browser. It needs a log level and message header passed and you can then expect to see the message logged at the provided log level. + +## Gathering SageMaker Logs + +The Graph Explorer proxy server outputs log statements to standard out. By +default, these logs will be forwarded to CloudWatch if the Notebook has the +proper permissions. + +To gather these logs: + +1. Open the AWS Console +2. Navigate to the Neptune page +3. Select "Notebook" from the sidebar +4. Find the Notebook hosting Graph Explorer +5. Open the details screen for that Notebook +6. In the "Actions" menu, choose "View Details in SageMaker" +7. Press the "View Logs" link in the SageMaker details screen under the field + titled "Lifecycle configuration" +8. Scroll down to the "Log Streams" panel in the CloudWatch details where you + should find multiple log streams +9. For each log stream related to Graph Explorer (LifecycleConfigOnStart.log, + graph-explorer.log) + 1. Open the log stream + 2. In the "Actions" menu, choose "Download search results (CSV)" + +If you encounter issues with missing log streams, see the +[SageMaker Issues](../troubleshooting/sagemaker-issues.md) troubleshooting +guide. diff --git a/additionaldocs/troubleshooting/README.md b/additionaldocs/troubleshooting/README.md index 87f4a15c5..4d53f65b7 100644 --- a/additionaldocs/troubleshooting/README.md +++ b/additionaldocs/troubleshooting/README.md @@ -9,8 +9,8 @@ diagnose problems with Graph Explorer. certificate issues 2. [Schema Sync](schema-sync.md) - Schema synchronization failures and connection problems -3. [SageMaker Logs](sagemaker-logs.md) - Gathering logs when running on Amazon - SageMaker +3. [SageMaker Issues](sagemaker-issues.md) - Common issues when running on + Amazon SageMaker ## General Troubleshooting Tips diff --git a/additionaldocs/troubleshooting/sagemaker-issues.md b/additionaldocs/troubleshooting/sagemaker-issues.md new file mode 100644 index 000000000..3c49431f4 --- /dev/null +++ b/additionaldocs/troubleshooting/sagemaker-issues.md @@ -0,0 +1,17 @@ +# SageMaker Issues + +This guide covers common issues and troubleshooting steps when running Graph +Explorer on Amazon SageMaker. + +## Graph Explorer Log Stream Does Not Exist + +New Neptune Notebooks automatically apply the correct IAM permissions to write +to CloudWatch. If your Notebook does not automatically create a +graph-explorer.log in the CloudWatch Log Streams, then it is possible that the +Neptune Notebook was created before those IAM permissions were added. You'll +need to add those permissions manually. + +Below are examples of which IAM permissions you need for Graph Explorer. + +- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) +- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) diff --git a/additionaldocs/troubleshooting/sagemaker-logs.md b/additionaldocs/troubleshooting/sagemaker-logs.md deleted file mode 100644 index be77fd2f9..000000000 --- a/additionaldocs/troubleshooting/sagemaker-logs.md +++ /dev/null @@ -1,40 +0,0 @@ -# SageMaker Logs - -This guide covers how to gather and troubleshoot logs when running Graph -Explorer on Amazon SageMaker. - -## Gathering SageMaker Logs - -The Graph Explorer proxy server outputs log statements to standard out. By -default, these logs will be forwarded to CloudWatch if the Notebook has the -proper permissions. - -To gather these logs: - -1. Open the AWS Console -2. Navigate to the Neptune page -3. Select "Notebook" from the sidebar -4. Find the Notebook hosting Graph Explorer -5. Open the details screen for that Notebook -6. In the "Actions" menu, choose "View Details in SageMaker" -7. Press the "View Logs" link in the SageMaker details screen under the field - titled "Lifecycle configuration" -8. Scroll down to the "Log Streams" panel in the CloudWatch details where you - should find multiple log streams -9. For each log stream related to Graph Explorer (LifecycleConfigOnStart.log, - graph-explorer.log) - 1. Open the log stream - 2. In the "Actions" menu, choose "Download search results (CSV)" - -## Graph Explorer Log Stream Does Not Exist - -New Neptune Notebooks automatically apply the correct IAM permissions to write -to CloudWatch. If your Notebook does not automatically create a -graph-explorer.log in the CloudWatch Log Streams, then it is possible that the -Neptune Notebook was created before those IAM permissions were added. You'll -need to add those permissions manually. - -Below are examples of which IAM permissions you need for Graph Explorer. - -- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) -- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) From fbe6fc88e83529b2c688be720d06628bf2e799d1 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:13:30 -0400 Subject: [PATCH 29/37] Move database setup --- additionaldocs/deployment/README.md | 12 ++-- additionaldocs/deployment/database-setup.md | 71 +++++++++++++++++++ additionaldocs/getting-started/README.md | 20 +++--- .../getting-started/requirements.md | 69 +----------------- additionaldocs/user-guide/connections.md | 3 +- 5 files changed, 92 insertions(+), 83 deletions(-) create mode 100644 additionaldocs/deployment/database-setup.md diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index f59ef6f76..7d0725b6e 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -5,13 +5,15 @@ environments. ## Files in this section -1. [Docker](docker.md) - Deploy Graph Explorer locally using Docker -2. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances -3. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS +1. [Database Setup](database-setup.md) - Configure different graph database + engines +2. [Docker](docker.md) - Deploy Graph Explorer locally using Docker +3. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances +4. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS using Fargate -4. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker +5. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks -5. [Configuration](configuration.md) - Environment variables and settings +6. [Configuration](configuration.md) - Environment variables and settings ## Prerequisites diff --git a/additionaldocs/deployment/database-setup.md b/additionaldocs/deployment/database-setup.md new file mode 100644 index 000000000..4fe02182d --- /dev/null +++ b/additionaldocs/deployment/database-setup.md @@ -0,0 +1,71 @@ +# Database Setup + +This guide contains detailed instructions for configuring different graph +database engines to work with Graph Explorer. + +## Overview + +Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. +You can connect to Amazon Neptune or you can also connect to open graph +databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 +protocol, such as Blazegraph. For additional details on connecting to different +graph databases, see [Connections](../user-guide/connections.md). + +After setting up your database, see the +[Connections UI](../user-guide/connections.md) guide to learn how to create and +manage connections within Graph Explorer. + +## Connecting to Neptune + +- Ensure that Graph Explorer has access to the Neptune instance by being in the + same VPC or VPC peering. +- If authentication is enabled, read query privileges are needed (See + [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). + +## Connecting to Gremlin-Server + +If you are using the default Gremlin Server docker image, you can get the server +running with the following commands: + +``` +docker pull tinkerpop/gremlin-server:latest +docker run -p 8182:8182 \ + tinkerpop/gremlin-server:latest \ + conf/gremlin-server-rest-modern.yaml +``` + +### Enable REST + +Graph Explorer only supports HTTP(S) connections. When connecting to +Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) +(i.e. +[Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). + + +> [!TIP] +> The Gremlin Server configuration can be usually found at: +> +> ``` +> /conf/gremlin-server.yaml +> ``` + +### Versions Prior to 3.7 + +If you have a version of Gremlin Server prior to 3.7, you will need to make the +following changes: + +- **Enable property returns** - Remove + ".withStrategies(ReferenceElementStrategy)" from + `/scripts/generate-modern.groovy` so that properties are returned. +- **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and + `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to + support string ids. You can use `ANY`. +- Build and run the Docker container as normal. + +## Connecting to BlazeGraph + +- Build and run the Docker container as normal and connect the proxy-server to + BlazeGraph and your workbench to the proxy-server. +- If using Docker, ensure that the container running the workbench can properly + access the container running BlazeGraph. You can find documentation on how to + connect containers via [Docker networks](https://docs.docker.com/network/). diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 688813bf2..f9dac1d55 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -5,8 +5,8 @@ time. ## Files in this section -1. [Requirements](requirements.md) - System requirements, minimum recommended - versions, and database configuration +1. [Requirements](requirements.md) - System requirements and minimum recommended + versions ## Prerequisites @@ -16,17 +16,19 @@ time. ## Quick Start Steps -1. **Check requirements and configure database** - Review the - [Requirements](requirements.md) to ensure compatibility and follow the - database configuration instructions -2. **Deploy Graph Explorer** - Choose a deployment method from the +1. **Check requirements** - Review the [Requirements](requirements.md) to ensure + system compatibility +2. **Set up your database** - Follow the + [Database Setup](../deployment/database-setup.md) guide to configure your + graph database +3. **Deploy Graph Explorer** - Choose a deployment method from the [Deployment](../deployment/) section -3. **Set up default connection (optional)** - Use the +4. **Set up default connection (optional)** - Use the [Default Connection](../user-guide/default-connection.md) guide to configure automatic connections -4. **Create a connection** - Use the +5. **Create a connection** - Use the [Connections UI](../user-guide/connections.md) to set up your connection -5. **Start exploring** - Begin using Graph Explorer with the +6. **Start exploring** - Begin using Graph Explorer with the [User Guide](../user-guide/) ## Troubleshooting diff --git a/additionaldocs/getting-started/requirements.md b/additionaldocs/getting-started/requirements.md index af95405a9..216199594 100644 --- a/additionaldocs/getting-started/requirements.md +++ b/additionaldocs/getting-started/requirements.md @@ -15,70 +15,5 @@ or above, which include the summary API and TinkerPop 3.6.2. For non-Neptune databases, we recommend at least TinkerPop 3.6. -## Database Configuration - -This section contains detailed instructions that help when configuring Graph -Explorer with different graph database engines for the first time. After setting -up your database, see the [Connections UI](../user-guide/connections.md) guide -to learn how to create and manage connections within Graph Explorer. - -Graph Explorer supports visualizing both **property graphs** and **RDF graphs**. -You can connect to Amazon Neptune or you can also connect to open graph -databases that implement an Apache TinkerPop Gremlin endpoint or the SPARQL 1.1 -protocol, such as Blazegraph. For additional details on connecting to different -graph databases, see [Connections](../user-guide/connections.md). - -### Connecting to Neptune - -- Ensure that Graph Explorer has access to the Neptune instance by being in the - same VPC or VPC peering. -- If authentication is enabled, read query privileges are needed (See - [ReadDataViaQuery managed policy](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query)). - -### Connecting to Gremlin-Server - -If you are using the default Gremlin Server docker image, you can get the server -running with the following commands: - -``` -docker pull tinkerpop/gremlin-server:latest -docker run -p 8182:8182 \ - tinkerpop/gremlin-server:latest \ - conf/gremlin-server-rest-modern.yaml -``` - -#### Enable REST - -Graph Explorer only supports HTTP(S) connections. When connecting to -Gremlin-Server, ensure it is configured with a channelizer that supports HTTP(S) -(i.e. -[Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). - - -> [!TIP] -> The Gremlin Server configuration can be usually found at: -> -> ``` -> /conf/gremlin-server.yaml -> ``` - -#### Versions Prior to 3.7 - -If you have a version of Gremlin Server prior to 3.7, you will need to make the -following changes: - -- **Enable property returns** - Remove - ".withStrategies(ReferenceElementStrategy)" from - `/scripts/generate-modern.groovy` so that properties are returned. -- **Enable string IDs** - Change `gremlin.tinkergraph.vertexIdManager` and - `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to - support string ids. You can use `ANY`. -- Build and run the Docker container as normal. - -### Connecting to BlazeGraph - -- Build and run the Docker container as normal and connect the proxy-server to - BlazeGraph and your workbench to the proxy-server. -- If using Docker, ensure that the container running the workbench can properly - access the container running BlazeGraph. You can find documentation on how to - connect containers via [Docker networks](https://docs.docker.com/network/). +For detailed database configuration instructions, see the +[Database Setup](../deployment/database-setup.md) guide. diff --git a/additionaldocs/user-guide/connections.md b/additionaldocs/user-guide/connections.md index 39b398c0f..2614a8a69 100644 --- a/additionaldocs/user-guide/connections.md +++ b/additionaldocs/user-guide/connections.md @@ -2,8 +2,7 @@ This guide covers how to manage connections within the Graph Explorer application. For information on configuring different graph database engines, -see the -[Requirements](../getting-started/requirements.md#database-configuration) guide. +see the [Database Setup](../deployment/database-setup.md) guide. You can create and manage connections to graph databases using this feature. Connections is accessible as the first screen after deploying the application, From 1712f87533b62b80f110cce0dbce24807a0f68fb Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:18:38 -0400 Subject: [PATCH 30/37] Moved default-connection.md to deployment --- additionaldocs/deployment/README.md | 12 +++++++----- additionaldocs/deployment/aws-ecs-fargate.md | 3 +-- .../default-connection.md | 15 +++++++++------ additionaldocs/getting-started/README.md | 2 +- additionaldocs/user-guide/README.md | 12 +++++------- 5 files changed, 23 insertions(+), 21 deletions(-) rename additionaldocs/{user-guide => deployment}/default-connection.md (86%) diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index 7d0725b6e..dcd122db1 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -7,13 +7,15 @@ environments. 1. [Database Setup](database-setup.md) - Configure different graph database engines -2. [Docker](docker.md) - Deploy Graph Explorer locally using Docker -3. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances -4. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS +2. [Default Connection](default-connection.md) - Configure automatic default + connections +3. [Docker](docker.md) - Deploy Graph Explorer locally using Docker +4. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances +5. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS using Fargate -5. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker +6. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks -6. [Configuration](configuration.md) - Environment variables and settings +7. [Configuration](configuration.md) - Environment variables and settings ## Prerequisites diff --git a/additionaldocs/deployment/aws-ecs-fargate.md b/additionaldocs/deployment/aws-ecs-fargate.md index cf2d39eba..9bab00f5b 100644 --- a/additionaldocs/deployment/aws-ecs-fargate.md +++ b/additionaldocs/deployment/aws-ecs-fargate.md @@ -195,8 +195,7 @@ the specified domain names. - `taskRoleArn` and `executionRoleArn`: The ARN of the IAM role created in step "Create a new IAM role and permission policies". - `environment` variables section (see - [Default Connections](../user-guide/default-connection.md) for more - details): + [Default Connections](default-connection.md) for more details): - `AWS_REGION`: The AWS region in which your Neptune cluster is located. - `GRAPH_TYPE`: The query language for your initial connection. - `IAM`: Set this to `true` to use SigV4 signed requests, if your Neptune diff --git a/additionaldocs/user-guide/default-connection.md b/additionaldocs/deployment/default-connection.md similarity index 86% rename from additionaldocs/user-guide/default-connection.md rename to additionaldocs/deployment/default-connection.md index 09ab1aef4..288921771 100644 --- a/additionaldocs/user-guide/default-connection.md +++ b/additionaldocs/deployment/default-connection.md @@ -17,13 +17,15 @@ These are the valid environment variables used for the default connection, their defaults, and their descriptions. - Required: - - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See [Connections UI](connections.md) + - `PUBLIC_OR_PROXY_ENDPOINT` - `None` - See + [Connections UI](../user-guide/connections.md) - Optional - `GRAPH_TYPE` - `None` - If not specified, multiple connections will be created for every available graph type / query language. See - [Connections UI](connections.md) - - `USING_PROXY_SERVER` - `False` - See [Connections UI](connections.md) - - `IAM` - `False` - See [Connections UI](connections.md) + [Connections UI](../user-guide/connections.md) + - `USING_PROXY_SERVER` - `False` - See + [Connections UI](../user-guide/connections.md) + - `IAM` - `False` - See [Connections UI](../user-guide/connections.md) - `GRAPH_EXP_HTTPS_CONNECTION` - `True` - Controls whether Graph Explorer uses SSL or not - `PROXY_SERVER_HTTPS_CONNECTION` - `True` - Controls whether the server uses @@ -35,9 +37,10 @@ defaults, and their descriptions. counts and expansion queries. - Conditionally Required: - Required if `USING_PROXY_SERVER=True` - - `GRAPH_CONNECTION_URL` - `None` - See [Connections UI](connections.md) + - `GRAPH_CONNECTION_URL` - `None` - See + [Connections UI](../user-guide/connections.md) - Required if `USING_PROXY_SERVER=True` and `IAM=True` - - `AWS_REGION` - `None` - See [Connections UI](connections.md) + - `AWS_REGION` - `None` - See [Connections UI](../user-guide/connections.md) - `SERVICE_TYPE` - `neptune-db`, Set this as `neptune-db` for Neptune database or `neptune-graph` for Neptune Analytics. diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index f9dac1d55..450bc87e2 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -24,7 +24,7 @@ time. 3. **Deploy Graph Explorer** - Choose a deployment method from the [Deployment](../deployment/) section 4. **Set up default connection (optional)** - Use the - [Default Connection](../user-guide/default-connection.md) guide to configure + [Default Connection](../deployment/default-connection.md) guide to configure automatic connections 5. **Create a connection** - Use the [Connections UI](../user-guide/connections.md) to set up your connection diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 83d69fb0a..1d4d96ff6 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -6,14 +6,12 @@ features and connect to different graph databases. ## Files in this section 1. [Connections](connections.md) - Managing database connections in the UI -2. [Default Connection](default-connection.md) - Configuring automatic default - connections -3. [Security](security.md) - Security considerations, authentication, and +2. [Security](security.md) - Security considerations, authentication, and permissions -4. [Settings](settings.md) - Application settings and configuration management -5. [Graph Explorer](graph-explorer.md) - Main graph visualization interface -6. [Table View](table-view.md) - Tabular data view and export functionality -7. [Data Explorer](data-explorer.md) - Node type data exploration +3. [Settings](settings.md) - Application settings and configuration management +4. [Graph Explorer](graph-explorer.md) - Main graph visualization interface +5. [Table View](table-view.md) - Tabular data view and export functionality +6. [Data Explorer](data-explorer.md) - Node type data exploration ## Prerequisites From 71d124209e308449f10c71d420be81cc4e1d2e75 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:31:26 -0400 Subject: [PATCH 31/37] Move https config --- additionaldocs/deployment/README.md | 12 +++-- additionaldocs/deployment/aws-ec2.md | 3 +- additionaldocs/deployment/docker.md | 3 +- additionaldocs/deployment/https-setup.md | 44 ++++++++++++++++ .../development/development-setup.md | 2 +- additionaldocs/user-guide/security.md | 50 ++----------------- 6 files changed, 58 insertions(+), 56 deletions(-) create mode 100644 additionaldocs/deployment/https-setup.md diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index dcd122db1..e2259f0e5 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -9,13 +9,15 @@ environments. engines 2. [Default Connection](default-connection.md) - Configure automatic default connections -3. [Docker](docker.md) - Deploy Graph Explorer locally using Docker -4. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances -5. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS +3. [HTTPS Setup](https-setup.md) - HTTPS configuration and certificate + management +4. [Docker](docker.md) - Deploy Graph Explorer locally using Docker +5. [AWS EC2](aws-ec2.md) - Deploy Graph Explorer on Amazon EC2 instances +6. [AWS ECS Fargate](aws-ecs-fargate.md) - Deploy Graph Explorer on AWS ECS using Fargate -6. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker +7. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks -7. [Configuration](configuration.md) - Environment variables and settings +8. [Configuration](configuration.md) - Environment variables and settings ## Prerequisites diff --git a/additionaldocs/deployment/aws-ec2.md b/additionaldocs/deployment/aws-ec2.md index e2881fadc..a3f02de25 100644 --- a/additionaldocs/deployment/aws-ec2.md +++ b/additionaldocs/deployment/aws-ec2.md @@ -63,7 +63,6 @@ These steps describe how to install Graph Explorer on your Amazon EC2 instance. 6. Since the application is set to use HTTPS by default and contains a self-signed certificate, you will need to add the Graph Explorer certificates to the trusted certificates directory and manually trust them. See the - [HTTPS Connections](../troubleshooting/docker-issues.md#https-connections) - section. + [HTTPS Connections](https-setup.md#https-connections) section. 7. After completing the trusted certification step and refreshing the browser, you should now see the Connections UI. diff --git a/additionaldocs/deployment/docker.md b/additionaldocs/deployment/docker.md index 84b6fa517..a0ec86e36 100644 --- a/additionaldocs/deployment/docker.md +++ b/additionaldocs/deployment/docker.md @@ -53,8 +53,7 @@ Docker image. You can find the latest version of the image on the application is set to use HTTPS by default and contains a self-signed certificate, you will need to add the Graph Explorer certificates to the trusted certificates directory and manually trust them. See the - [HTTPS Connections](../troubleshooting/docker-issues.md#https-connections) - section. + [HTTPS Connections](https-setup.md#https-connections) section. 6. After completing the trusted certification step and refreshing the browser, you should now see the Connections UI. See below description on Connections UI to configure your first connection to Amazon Neptune. diff --git a/additionaldocs/deployment/https-setup.md b/additionaldocs/deployment/https-setup.md new file mode 100644 index 000000000..1e8742907 --- /dev/null +++ b/additionaldocs/deployment/https-setup.md @@ -0,0 +1,44 @@ +# HTTPS Setup + +This guide covers HTTPS configuration and certificate management for Graph +Explorer deployments. + +## HTTPS Configuration + +Graph Explorer supports the HTTPS protocol by default and provides a self-signed +certificate as part of the Docker image. You can choose to use HTTP instead by +changing the [environment variable default settings](configuration.md). + +## HTTPS Connections + +If either Graph Explorer or the proxy-server are served over an HTTPS connection +(which it is by default), you will have to bypass the warning message from the +browser due to the included certificate being a self-signed certificate. You can +bypass by manually ignoring them from the browser or downloading the correct +certificate and configuring them to be trusted. Alternatively, you can provide +your own certificate. The following instructions can be used as an example to +bypass the warnings for Chrome, but note that different browsers and operating +systems will have slightly different steps. + +1. Download the certificate directly from the browser. For example, if using + Google Chrome, click the "Not Secure" section on the left of the URL bar and + select "Certificate is not valid" to show the certificate. Then click Details + tab and click Export at the bottom. +2. Once you have the certificate, you will need to trust it on your machine. For + MacOS, you can open the Keychain Access app. Select System under System + Keychains. Then go to File > Import Items... and import the certificate you + downloaded in the previous step. +3. Once imported, select the certificate and right-click to select "Get Info". + Expand the Trust section, and change the value of "When using this + certificate" to "Always Trust". +4. You should now refresh the browser and see that you can proceed to open the + application. For Chrome, the application will remain "Not Secure" due to the + fact that this is a self-signed certificate. If you have trouble accessing + Graph Explorer after completing the previous step and reloading the browser, + consider running a docker restart command and refreshing the browser again. + + +> [!TIP] +> +> To get rid of the "Not Secure" warning, see +[Using self-signed certificates on Chrome](../development/development-setup.md#using-self-signed-certificates-on-chrome). diff --git a/additionaldocs/development/development-setup.md b/additionaldocs/development/development-setup.md index 65744ea6c..c3c02dc83 100644 --- a/additionaldocs/development/development-setup.md +++ b/additionaldocs/development/development-setup.md @@ -149,7 +149,7 @@ You can build the Docker image locally by following the steps below. ## Using Self-signed certificates on Chrome For browsers like Safari and Firefox, -[trusting the certificate from the browser](../user-guide/security.md#https-connections) +[trusting the certificate from the browser](../deployment/https-setup.md#https-connections) is enough to bypass the "Not Secure" warning. However, Chrome treats self-signed certificates differently. If you want to use a self-signed certificate on Chrome **without** the "Not Secure" warning and you do not have your own certificate, diff --git a/additionaldocs/user-guide/security.md b/additionaldocs/user-guide/security.md index 83ee0fc09..64553007b 100644 --- a/additionaldocs/user-guide/security.md +++ b/additionaldocs/user-guide/security.md @@ -1,52 +1,10 @@ # Security -This guide covers security considerations, authentication methods, and -permissions when using Graph Explorer with graph databases. +This guide covers authentication methods and permissions when using Graph +Explorer with graph databases. -## Security - -You can use Graph Explorer to connect to a publicly accessible graph database -endpoint, or connect to a proxy endpoint that redirects to a private graph -database endpoint. - -Graph Explorer supports the HTTPS protocol by default and provides a self-signed -certificate as part of the Docker image. You can choose to use HTTP instead by -changing the -[environment variable default settings](../deployment/configuration.md). - -### HTTPS Connections - -If either Graph Explorer or the proxy-server are served over an HTTPS connection -(which it is by default), you will have to bypass the warning message from the -browser due to the included certificate being a self-signed certificate. You can -bypass by manually ignoring them from the browser or downloading the correct -certificate and configuring them to be trusted. Alternatively, you can provide -your own certificate. The following instructions can be used as an example to -bypass the warnings for Chrome, but note that different browsers and operating -systems will have slightly different steps. - -1. Download the certificate directly from the browser. For example, if using - Google Chrome, click the "Not Secure" section on the left of the URL bar and - select "Certificate is not valid" to show the certificate. Then click Details - tab and click Export at the bottom. -2. Once you have the certificate, you will need to trust it on your machine. For - MacOS, you can open the Keychain Access app. Select System under System - Keychains. Then go to File > Import Items... and import the certificate you - downloaded in the previous step. -3. Once imported, select the certificate and right-click to select "Get Info". - Expand the Trust section, and change the value of "When using this - certificate" to "Always Trust". -4. You should now refresh the browser and see that you can proceed to open the - application. For Chrome, the application will remain "Not Secure" due to the - fact that this is a self-signed certificate. If you have trouble accessing - Graph Explorer after completing the previous step and reloading the browser, - consider running a docker restart command and refreshing the browser again. - - -> [!TIP] -> -> To get rid of the "Not Secure" warning, see -[Using self-signed certificates on Chrome](../development/development-setup.md#using-self-signed-certificates-on-chrome). +For HTTPS configuration and certificate setup, see the +[HTTPS Setup](../deployment/https-setup.md) guide. ## Permissions From aab8182a30eb9d1387bee99b801e55fbda7e3f5e Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:35:21 -0400 Subject: [PATCH 32/37] Move platform-specific troubleshooting to deployment guides --- additionaldocs/administration/monitoring.md | 4 +- additionaldocs/deployment/aws-sagemaker.md | 19 ++++ additionaldocs/deployment/docker.md | 91 ++++++++++++++++++ additionaldocs/troubleshooting/README.md | 6 +- .../troubleshooting/docker-issues.md | 92 ------------------- .../troubleshooting/sagemaker-issues.md | 17 ---- 6 files changed, 113 insertions(+), 116 deletions(-) delete mode 100644 additionaldocs/troubleshooting/docker-issues.md delete mode 100644 additionaldocs/troubleshooting/sagemaker-issues.md diff --git a/additionaldocs/administration/monitoring.md b/additionaldocs/administration/monitoring.md index bc66d1f61..b84d68286 100644 --- a/additionaldocs/administration/monitoring.md +++ b/additionaldocs/administration/monitoring.md @@ -73,5 +73,5 @@ To gather these logs: 2. In the "Actions" menu, choose "Download search results (CSV)" If you encounter issues with missing log streams, see the -[SageMaker Issues](../troubleshooting/sagemaker-issues.md) troubleshooting -guide. +[SageMaker troubleshooting](../deployment/aws-sagemaker.md#troubleshooting) +section. diff --git a/additionaldocs/deployment/aws-sagemaker.md b/additionaldocs/deployment/aws-sagemaker.md index a2c0cf104..19f8f94d3 100644 --- a/additionaldocs/deployment/aws-sagemaker.md +++ b/additionaldocs/deployment/aws-sagemaker.md @@ -82,3 +82,22 @@ that request. ] } ``` + +## Troubleshooting + +### Graph Explorer Log Stream Does Not Exist + +New Neptune Notebooks automatically apply the correct IAM permissions to write +to CloudWatch. If your Notebook does not automatically create a +graph-explorer.log in the CloudWatch Log Streams, then it is possible that the +Neptune Notebook was created before those IAM permissions were added. You'll +need to add those permissions manually. + +Below are examples of which IAM permissions you need for Graph Explorer. + +- [IAM permissions for Neptune DB](aws-sagemaker/graph-explorer-neptune-db-policy.json) +- [IAM permissions for Neptune Analytics](aws-sagemaker/graph-explorer-neptune-analytics-policy.json) + +``` + +``` diff --git a/additionaldocs/deployment/docker.md b/additionaldocs/deployment/docker.md index a0ec86e36..b41efc055 100644 --- a/additionaldocs/deployment/docker.md +++ b/additionaldocs/deployment/docker.md @@ -82,3 +82,94 @@ It comes with a very small graph dataset. - Public or Proxy Endpoint: `https://localhost` - Using Proxy Server: `true` - Graph Connection URL: `http://localhost:8182` + +## Troubleshooting + +### Container Startup Issues + +1. If the container does not start, or immediately stops, use + `docker logs graph-explorer` to check the container console logs for any + related error messages that might provide guidance on why graph-explorer did + not start. +2. If you are having issues connecting graph-explorer to your graph database, + use your browser's Developer Tools feature to monitor both the browser + console and network calls to determine if here are any errors related to + connectivity. + +### Ports in Use + +If the default ports of 80 and 443 are already in use, you can use the `-p` flag +to change the ports to something else. The host machine ports are the first of +the two numbers. You can change those to whatever you want. + +For example, if you want to use port 8080 and 4431, you can use the following +command: + +``` +docker run -p 8080:80 -p 4431:443 \ + --name graph-explorer \ + --env HOST=localhost \ + public.ecr.aws/neptune/graph-explorer +``` + +Which will result in the following URLs: + +- HTTPS: `https://localhost:4431/explorer` +- HTTP: `http://localhost:8080/explorer` + +### HTTP Only + +If you do not want to use SSL and HTTPS, you can disable it by setting the +following [environment variables](configuration.md): + +``` +PROXY_SERVER_HTTPS_CONNECTION=false +GRAPH_EXP_HTTPS_CONNECTION=false +``` + +These can be passed when creating the Docker container like so: + +``` +docker run -p 80:80 \ + --name graph-explorer \ + --env PROXY_SERVER_HTTPS_CONNECTION=false \ + --env GRAPH_EXP_HTTPS_CONNECTION=false \ + public.ecr.aws/neptune/graph-explorer +``` + +### HTTPS Connections + +If either of the Graph Explorer or the proxy-server are served over an HTTPS +connection (which it is by default), you will have to bypass the warning message +from the browser due to the included certificate being a self-signed +certificate. + +You can bypass by manually ignoring them from the browser or downloading the +correct certificate and configuring them to be trusted. Alternatively, you can +provide your own certificate. + +The following instructions can be used as an example to bypass the warnings for +Chrome, but note that different browsers and operating systems will have +slightly different steps. + +1. Download the certificate directly from the browser. For example, if using + Google Chrome, click the "Not Secure" section on the left of the URL bar and + select "Certificate is not valid" to show the certificate. Then click Details + tab and click Export at the bottom. +2. Once you have the certificate, you will need to trust it on your machine. For + MacOS, you can open the Keychain Access app. Select System under System + Keychains. Then go to File > Import Items... and import the certificate you + downloaded in the previous step. +3. Once imported, select the certificate and right-click to select "Get Info". + Expand the Trust section, and change the value of "When using this + certificate" to "Always Trust". +4. You should now refresh the browser and see that you can proceed to open the + application. For Chrome, the application will remain "Not Secure" due to the + fact that this is a self-signed certificate. If you have trouble accessing + Graph Explorer after completing the previous step and reloading the browser, + consider running a docker restart command and refreshing the browser again. + + +> [!TIP] +> To get rid of the "Not Secure" warning, see +[Using self-signed certificates on Chrome](../development/development-setup.md#using-self-signed-certificates-on-chrome). diff --git a/additionaldocs/troubleshooting/README.md b/additionaldocs/troubleshooting/README.md index 4d53f65b7..7ba7f4e26 100644 --- a/additionaldocs/troubleshooting/README.md +++ b/additionaldocs/troubleshooting/README.md @@ -5,12 +5,8 @@ diagnose problems with Graph Explorer. ## Files in this section -1. [Docker Issues](docker-issues.md) - Container startup, ports, and HTTPS - certificate issues -2. [Schema Sync](schema-sync.md) - Schema synchronization failures and +1. [Schema Sync](schema-sync.md) - Schema synchronization failures and connection problems -3. [SageMaker Issues](sagemaker-issues.md) - Common issues when running on - Amazon SageMaker ## General Troubleshooting Tips diff --git a/additionaldocs/troubleshooting/docker-issues.md b/additionaldocs/troubleshooting/docker-issues.md deleted file mode 100644 index 496aab2c8..000000000 --- a/additionaldocs/troubleshooting/docker-issues.md +++ /dev/null @@ -1,92 +0,0 @@ -# Docker Container Issues - -This guide covers common Docker-related issues when running Graph Explorer. - -## Container Startup Issues - -1. If the container does not start, or immediately stops, use - `docker logs graph-explorer` to check the container console logs for any - related error messages that might provide guidance on why graph-explorer did - not start. -2. If you are having issues connecting graph-explorer to your graph database, - use your browser's Developer Tools feature to monitor both the browser - console and network calls to determine if here are any errors related to - connectivity. - -## Ports in Use - -If the default ports of 80 and 443 are already in use, you can use the `-p` flag -to change the ports to something else. The host machine ports are the first of -the two numbers. You can change those to whatever you want. - -For example, if you want to use port 8080 and 4431, you can use the following -command: - -``` -docker run -p 8080:80 -p 4431:443 \ - --name graph-explorer \ - --env HOST=localhost \ - public.ecr.aws/neptune/graph-explorer -``` - -Which will result in the following URLs: - -- HTTPS: `https://localhost:4431/explorer` -- HTTP: `http://localhost:8080/explorer` - -## HTTP Only - -If you do not want to use SSL and HTTPS, you can disable it by setting the -following [environment variables](../deployment/configuration.md): - -``` -PROXY_SERVER_HTTPS_CONNECTION=false -GRAPH_EXP_HTTPS_CONNECTION=false -``` - -These can be passed when creating the Docker container like so: - -``` -docker run -p 80:80 \ - --name graph-explorer \ - --env PROXY_SERVER_HTTPS_CONNECTION=false \ - --env GRAPH_EXP_HTTPS_CONNECTION=false \ - public.ecr.aws/neptune/graph-explorer -``` - -## HTTPS Connections - -If either of the Graph Explorer or the proxy-server are served over an HTTPS -connection (which it is by default), you will have to bypass the warning message -from the browser due to the included certificate being a self-signed -certificate. - -You can bypass by manually ignoring them from the browser or downloading the -correct certificate and configuring them to be trusted. Alternatively, you can -provide your own certificate. - -The following instructions can be used as an example to bypass the warnings for -Chrome, but note that different browsers and operating systems will have -slightly different steps. - -1. Download the certificate directly from the browser. For example, if using - Google Chrome, click the "Not Secure" section on the left of the URL bar and - select "Certificate is not valid" to show the certificate. Then click Details - tab and click Export at the bottom. -2. Once you have the certificate, you will need to trust it on your machine. For - MacOS, you can open the Keychain Access app. Select System under System - Keychains. Then go to File > Import Items... and import the certificate you - downloaded in the previous step. -3. Once imported, select the certificate and right-click to select "Get Info". - Expand the Trust section, and change the value of "When using this - certificate" to "Always Trust". -4. You should now refresh the browser and see that you can proceed to open the - application. For Chrome, the application will remain "Not Secure" due to the - fact that this is a self-signed certificate. If you have trouble accessing - Graph Explorer after completing the previous step and reloading the browser, - consider running a docker restart command and refreshing the browser again. - - -> [!TIP] -> To get rid of the "Not Secure" warning, see -[Using self-signed certificates on Chrome](../development/development-setup.md#using-self-signed-certificates-on-chrome). diff --git a/additionaldocs/troubleshooting/sagemaker-issues.md b/additionaldocs/troubleshooting/sagemaker-issues.md deleted file mode 100644 index 3c49431f4..000000000 --- a/additionaldocs/troubleshooting/sagemaker-issues.md +++ /dev/null @@ -1,17 +0,0 @@ -# SageMaker Issues - -This guide covers common issues and troubleshooting steps when running Graph -Explorer on Amazon SageMaker. - -## Graph Explorer Log Stream Does Not Exist - -New Neptune Notebooks automatically apply the correct IAM permissions to write -to CloudWatch. If your Notebook does not automatically create a -graph-explorer.log in the CloudWatch Log Streams, then it is possible that the -Neptune Notebook was created before those IAM permissions were added. You'll -need to add those permissions manually. - -Below are examples of which IAM permissions you need for Graph Explorer. - -- [IAM permissions for Neptune DB](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) -- [IAM permissions for Neptune Analytics](https://raw.githubusercontent.com/aws/graph-explorer/main/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) From 3cb5a357c03993405bd28af0adbf242233108133 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:42:41 -0400 Subject: [PATCH 33/37] Remove extra content in readmes --- additionaldocs/administration/README.md | 21 ----------------- additionaldocs/deployment/README.md | 11 --------- additionaldocs/development/README.md | 13 ----------- additionaldocs/getting-started/README.md | 29 ------------------------ additionaldocs/troubleshooting/README.md | 17 -------------- additionaldocs/user-guide/README.md | 11 --------- 6 files changed, 102 deletions(-) diff --git a/additionaldocs/administration/README.md b/additionaldocs/administration/README.md index 29018b69c..eba4054e5 100644 --- a/additionaldocs/administration/README.md +++ b/additionaldocs/administration/README.md @@ -9,24 +9,3 @@ manage, monitor, and maintain Graph Explorer deployments. capabilities 2. [Backup and Restore](backup-restore.md) - Backing up and restoring Graph Explorer configuration - -## Prerequisites - -- Graph Explorer deployed and running -- Administrative access to the deployment environment -- Basic familiarity with system administration and monitoring concepts - -## Overview - -Administration tasks typically include: - -- **Monitoring**: Setting up health checks and log monitoring -- **Backup & Recovery**: Protecting configuration and ensuring business - continuity -- **Maintenance**: Regular operational tasks and updates -- **Security**: Operational security considerations - -## Next Steps - -After setting up monitoring, consider implementing backup procedures and -establishing maintenance schedules for your Graph Explorer deployment. diff --git a/additionaldocs/deployment/README.md b/additionaldocs/deployment/README.md index e2259f0e5..659aa4d45 100644 --- a/additionaldocs/deployment/README.md +++ b/additionaldocs/deployment/README.md @@ -18,14 +18,3 @@ environments. 7. [AWS SageMaker](aws-sagemaker.md) - Deploy Graph Explorer on Amazon SageMaker Notebooks 8. [Configuration](configuration.md) - Environment variables and settings - -## Prerequisites - -- Basic familiarity with containerized deployments -- Access to your chosen deployment platform -- Graph database endpoint accessible from your deployment environment - -## Next Steps - -After completing deployment, see the [Getting Started](../getting-started/) -guide for connecting to your first database and basic usage. diff --git a/additionaldocs/development/README.md b/additionaldocs/development/README.md index 183d25877..8f5c5692a 100644 --- a/additionaldocs/development/README.md +++ b/additionaldocs/development/README.md @@ -11,16 +11,3 @@ Explorer or set up a local development environment. versions 3. [Troubleshooting](troubleshooting.md) - Common development issues and solutions - -## Prerequisites - -- Node.js >=24.4.0 -- pnpm >=10.12.1 -- Basic familiarity with React and TypeScript -- Docker (for containerized development) - -## Next Steps - -After setting up your development environment, see the -[Contributing Guidelines](../../CONTRIBUTING.md) for information on how to -contribute to the project. diff --git a/additionaldocs/getting-started/README.md b/additionaldocs/getting-started/README.md index 450bc87e2..13f2e4044 100644 --- a/additionaldocs/getting-started/README.md +++ b/additionaldocs/getting-started/README.md @@ -7,32 +7,3 @@ time. 1. [Requirements](requirements.md) - System requirements and minimum recommended versions - -## Prerequisites - -- Graph Explorer installed and running (see [Deployment](../deployment/) guides) -- Access to a graph database endpoint -- Basic familiarity with graph databases - -## Quick Start Steps - -1. **Check requirements** - Review the [Requirements](requirements.md) to ensure - system compatibility -2. **Set up your database** - Follow the - [Database Setup](../deployment/database-setup.md) guide to configure your - graph database -3. **Deploy Graph Explorer** - Choose a deployment method from the - [Deployment](../deployment/) section -4. **Set up default connection (optional)** - Use the - [Default Connection](../deployment/default-connection.md) guide to configure - automatic connections -5. **Create a connection** - Use the - [Connections UI](../user-guide/connections.md) to set up your connection -6. **Start exploring** - Begin using Graph Explorer with the - [User Guide](../user-guide/) - -## Troubleshooting - -If the instructions above do not work for you, please see the -[Troubleshooting](../troubleshooting/) page for more information. It contains -workarounds for common issues and information on how to diagnose other issues. diff --git a/additionaldocs/troubleshooting/README.md b/additionaldocs/troubleshooting/README.md index 7ba7f4e26..ce6528a03 100644 --- a/additionaldocs/troubleshooting/README.md +++ b/additionaldocs/troubleshooting/README.md @@ -7,20 +7,3 @@ diagnose problems with Graph Explorer. 1. [Schema Sync](schema-sync.md) - Schema synchronization failures and connection problems - -## General Troubleshooting Tips - -- Use your browser's Developer Tools to monitor console errors and network - requests -- Check container logs with `docker logs graph-explorer` for Docker deployments -- Verify network connectivity between Graph Explorer and your graph database -- Ensure proper IAM permissions when using AWS services - -## Getting Help - -If you encounter issues not covered in these guides, please: - -1. Check the [GitHub Issues](https://github.com/aws/graph-explorer/issues) for - similar problems -2. [File a new issue](https://github.com/aws/graph-explorer/issues/new/choose) - with detailed information about your setup and the problem diff --git a/additionaldocs/user-guide/README.md b/additionaldocs/user-guide/README.md index 1d4d96ff6..9c91f1d43 100644 --- a/additionaldocs/user-guide/README.md +++ b/additionaldocs/user-guide/README.md @@ -12,14 +12,3 @@ features and connect to different graph databases. 4. [Graph Explorer](graph-explorer.md) - Main graph visualization interface 5. [Table View](table-view.md) - Tabular data view and export functionality 6. [Data Explorer](data-explorer.md) - Node type data exploration - -## Prerequisites - -- Graph Explorer installed and running -- Access to a graph database endpoint -- Basic familiarity with graph databases - -## Next Steps - -After connecting to your database, explore the other guides in this section to -learn about Graph Explorer's visualization and data exploration capabilities. From 86cd2eec2f95924b194f0023c5367b317b2d20b9 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 14:47:29 -0400 Subject: [PATCH 34/37] =?UTF-8?q?Remove=20git=20stuff=20that=20didn?= =?UTF-8?q?=E2=80=99t=20work?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .kiro/steering/documentation.md | 59 --------------------------------- 1 file changed, 59 deletions(-) diff --git a/.kiro/steering/documentation.md b/.kiro/steering/documentation.md index 62b6fb4d4..770957176 100644 --- a/.kiro/steering/documentation.md +++ b/.kiro/steering/documentation.md @@ -223,65 +223,6 @@ feature documentation. - Use Git history for version tracking - Clearly mark deprecated features or methods -### Git Workflow for Documentation Changes - -When making documentation updates, commit changes in logical, isolated stages to -maintain a clean history and enable easier reviews: - -#### Commit Stages - -1. **File Structure Changes** (commit separately) - - Creating new folders or moving files - - Renaming files or folders - - Deleting obsolete documentation - - Link updates and corrections - -2. **Content Reorganization** (commit separately) - - Moving sections between files - - Restructuring existing content - - Breaking large files into smaller ones - - Link updates and corrections - -3. **Content Updates** (commit by logical grouping) - - New feature documentation - - Updated installation instructions - - Revised examples or code snippets - - Link updates and corrections - -4. **Formatting and Style** (commit separately) - - Markdown formatting fixes - - Style consistency improvements - - Non-functional formatting changes - - Link updates and corrections - -#### Example Commit Messages - -```bash -# Structure changes -git commit -m "docs: create user-guide folder structure" -git commit -m "docs: move authentication content to user-guide/" - -# Content reorganization -git commit -m "docs: split installation.md into docker and local setup" -git commit -m "docs: move troubleshooting sections to dedicated files" - -# Content updates -git commit -m "docs: add React 19 migration guide" -git commit -m "docs: update Neptune connection examples" - -# Formatting -git commit -m "docs: fix broken links in getting-started section" -git commit -m "docs: standardize code block formatting" -``` - -#### Benefits of Staged Commits - -- **Easier Reviews**: Reviewers can focus on specific types of changes -- **Safer Reverts**: Roll back specific changes without losing other work -- **Clear History**: Git log shows the evolution of documentation clearly -- **Conflict Resolution**: Merge conflicts are easier to resolve with focused - commits - ## Example Structure ### Good README Introduction From 0db929eba0d062c64414d405e7d6c624c0cd8b31 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 15:38:15 -0400 Subject: [PATCH 35/37] Rename additionaldocs to docs --- .dockerignore | 2 +- .kiro/steering/documentation.md | 4 ++-- .kiro/steering/structure.md | 2 +- Changelog.md | 12 +++++----- README.md | 24 +++++++++---------- {additionaldocs => docs}/README.md | 0 .../administration/README.md | 0 .../administration/backup-restore.md | 0 .../administration/monitoring.md | 0 {additionaldocs => docs}/deployment/README.md | 0 .../deployment/aws-ec2.md | 0 .../deployment/aws-ecs-fargate.md | 0 .../deployment/aws-sagemaker.md | 0 ...aph-explorer-neptune-analytics-policy.json | 0 .../graph-explorer-neptune-db-policy.json | 0 .../install-graph-explorer-lc.sh | 0 .../deployment/configuration.md | 0 .../deployment/database-setup.md | 0 .../deployment/default-connection.md | 0 {additionaldocs => docs}/deployment/docker.md | 0 .../deployment/https-setup.md | 0 .../development/README.md | 0 .../development/development-setup.md | 0 .../development/release.md | 0 .../development/troubleshooting.md | 0 .../getting-started/README.md | 0 .../getting-started/requirements.md | 0 .../troubleshooting/README.md | 0 .../troubleshooting/schema-sync.md | 0 {additionaldocs => docs}/user-guide/README.md | 0 .../user-guide/connections.md | 0 .../user-guide/data-explorer.md | 0 .../user-guide/graph-explorer.md | 0 .../user-guide/security.md | 0 .../user-guide/settings.md | 0 .../user-guide/table-view.md | 0 36 files changed, 22 insertions(+), 22 deletions(-) rename {additionaldocs => docs}/README.md (100%) rename {additionaldocs => docs}/administration/README.md (100%) rename {additionaldocs => docs}/administration/backup-restore.md (100%) rename {additionaldocs => docs}/administration/monitoring.md (100%) rename {additionaldocs => docs}/deployment/README.md (100%) rename {additionaldocs => docs}/deployment/aws-ec2.md (100%) rename {additionaldocs => docs}/deployment/aws-ecs-fargate.md (100%) rename {additionaldocs => docs}/deployment/aws-sagemaker.md (100%) rename {additionaldocs => docs}/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json (100%) rename {additionaldocs => docs}/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json (100%) rename {additionaldocs => docs}/deployment/aws-sagemaker/install-graph-explorer-lc.sh (100%) rename {additionaldocs => docs}/deployment/configuration.md (100%) rename {additionaldocs => docs}/deployment/database-setup.md (100%) rename {additionaldocs => docs}/deployment/default-connection.md (100%) rename {additionaldocs => docs}/deployment/docker.md (100%) rename {additionaldocs => docs}/deployment/https-setup.md (100%) rename {additionaldocs => docs}/development/README.md (100%) rename {additionaldocs => docs}/development/development-setup.md (100%) rename {additionaldocs => docs}/development/release.md (100%) rename {additionaldocs => docs}/development/troubleshooting.md (100%) rename {additionaldocs => docs}/getting-started/README.md (100%) rename {additionaldocs => docs}/getting-started/requirements.md (100%) rename {additionaldocs => docs}/troubleshooting/README.md (100%) rename {additionaldocs => docs}/troubleshooting/schema-sync.md (100%) rename {additionaldocs => docs}/user-guide/README.md (100%) rename {additionaldocs => docs}/user-guide/connections.md (100%) rename {additionaldocs => docs}/user-guide/data-explorer.md (100%) rename {additionaldocs => docs}/user-guide/graph-explorer.md (100%) rename {additionaldocs => docs}/user-guide/security.md (100%) rename {additionaldocs => docs}/user-guide/settings.md (100%) rename {additionaldocs => docs}/user-guide/table-view.md (100%) diff --git a/.dockerignore b/.dockerignore index 0c6d25db4..bd235c830 100644 --- a/.dockerignore +++ b/.dockerignore @@ -10,6 +10,6 @@ node_modules coverage # Ignore documentation related files -additionaldocs +docs images *.md diff --git a/.kiro/steering/documentation.md b/.kiro/steering/documentation.md index 770957176..f0c6b0079 100644 --- a/.kiro/steering/documentation.md +++ b/.kiro/steering/documentation.md @@ -25,7 +25,7 @@ ### Documentation Hierarchy - **README.md**: Project overview and quick start -- **additionaldocs/**: Detailed guides organized by user journey +- **docs/**: Detailed guides organized by user journey - `getting-started/`: Installation, first connection, basic usage - `user-guide/`: Feature documentation for end users - `deployment/`: Production deployment guides @@ -62,7 +62,7 @@ ``` README.md # Project overview and quick start -additionaldocs/ +docs/ ├── getting-started/ │ ├── installation.md # Local and Docker setup │ ├── first-connection.md # Connecting to your first database diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md index ecae787e8..ad4e16764 100644 --- a/.kiro/steering/structure.md +++ b/.kiro/steering/structure.md @@ -14,7 +14,7 @@ graph-explorer/ │ ├── graph-explorer/ # React frontend application │ ├── graph-explorer-proxy-server/ # Express.js backend server │ └── shared/ # Shared types and utilities -├── additionaldocs/ # Documentation +├── docs/ # Documentation ├── samples/ # Example configurations └── [root config files] # Workspace-level configuration ``` diff --git a/Changelog.md b/Changelog.md index 99b444e6e..bb33dcf4e 100644 --- a/Changelog.md +++ b/Changelog.md @@ -137,7 +137,7 @@ editor with Neptune Analytics for the first time. As before, if you are a Neptune user concerned about data integrity, check out the -[instructions on configuring IAM permissions to restrict mutations](./additionaldocs/user-guide/security.md#permissions), +[instructions on configuring IAM permissions to restrict mutations](./docs/user-guide/security.md#permissions), ensuring that users can enforce read-only operations. ### New features & major changes @@ -163,7 +163,7 @@ ensuring that users can enforce read-only operations. Graph Explorer v2.0 marks a significant milestone with the introduction of the new -[query editor for Gremlin connections](./additionaldocs/user-guide/graph-explorer.md#query-search). +[query editor for Gremlin connections](./docs/user-guide/graph-explorer.md#query-search). This powerful feature allows users to enter any valid Gremlin query and visualize the returned nodes, edges, and scalar values directly from the database. You can review the results in the sidebar and choose to add all nodes @@ -171,7 +171,7 @@ database. You can review the results in the sidebar and choose to add all nodes For Neptune users concerned about data integrity, [the README](./README.md) now includes -[instructions on configuring IAM permissions to restrict mutations](./additionaldocs/user-guide/security.md#permissions), +[instructions on configuring IAM permissions to restrict mutations](./docs/user-guide/security.md#permissions), ensuring users can enforce read-only operations. The release also changes the default strategy for representing node & edge @@ -662,11 +662,11 @@ a more pleasant experience, especially for users with larger databases. - **Improved** diagnostic logging in Neptune Notebooks by adding CloudWatch logs ([#517](https://github.com/aws/graph-explorer/pull/517)) - Check out the example - [lifecycle script](additionaldocs/deployment/aws-sagemaker/install-graph-explorer-lc.sh) + [lifecycle script](docs/deployment/aws-sagemaker/install-graph-explorer-lc.sh) and IAM policies for - [Neptune](additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) + [Neptune](docs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json) and - [Neptune Analytics](additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) + [Neptune Analytics](docs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json) **Bug Fixes and Minor Changes** diff --git a/README.md b/README.md index 1399e57f1..6b8016181 100644 --- a/README.md +++ b/README.md @@ -20,16 +20,16 @@ like [Amazon ECS](https://aws.amazon.com/ecs/). There are many ways to deploy and run Graph Explorer. If you are new to graph databases and Graph Explorer, we recommend that you check out the -[Getting Started](./additionaldocs/getting-started/README.md) guide. - -- [Local Docker Setup](./additionaldocs/deployment/docker.md) - A quick start - guide to deploying Graph Explorer locally using the official Docker image. -- [Amazon EC2 Setup](./additionaldocs/deployment/aws-ec2.md) - A quick start - guide to setting up Graph Explorer on Amazon EC2 with Neptune. -- [Local Development](./additionaldocs/development/development-setup.md) - A - quick start guide building the Docker image from source code. -- [Troubleshooting](./additionaldocs/troubleshooting/) - A collection of helpful - tips if you run in to issues while setting up Graph Explorer. +[Getting Started](./docs/getting-started/README.md) guide. + +- [Local Docker Setup](./docs/deployment/docker.md) - A quick start guide to + deploying Graph Explorer locally using the official Docker image. +- [Amazon EC2 Setup](./docs/deployment/aws-ec2.md) - A quick start guide to + setting up Graph Explorer on Amazon EC2 with Neptune. +- [Local Development](./docs/development/development-setup.md) - A quick start + guide building the Docker image from source code. +- [Troubleshooting](./docs/troubleshooting/) - A collection of helpful tips if + you run in to issues while setting up Graph Explorer. - [Samples](./samples) - A collection of Docker Compose files that show various ways to configure and use Graph Explorer. @@ -54,14 +54,14 @@ databases: view For complete documentation on all features and functionality, please see our -[detailed user guide](./additionaldocs/user-guide/). +[detailed user guide](./docs/user-guide/). If you're interested in our future development plans, check out our [roadmap](./ROADMAP.md) and participate in the discussions. ## Development -For development guidance, see [Development](./additionaldocs/development/). +For development guidance, see [Development](./docs/development/). ## Contributing Guidelines diff --git a/additionaldocs/README.md b/docs/README.md similarity index 100% rename from additionaldocs/README.md rename to docs/README.md diff --git a/additionaldocs/administration/README.md b/docs/administration/README.md similarity index 100% rename from additionaldocs/administration/README.md rename to docs/administration/README.md diff --git a/additionaldocs/administration/backup-restore.md b/docs/administration/backup-restore.md similarity index 100% rename from additionaldocs/administration/backup-restore.md rename to docs/administration/backup-restore.md diff --git a/additionaldocs/administration/monitoring.md b/docs/administration/monitoring.md similarity index 100% rename from additionaldocs/administration/monitoring.md rename to docs/administration/monitoring.md diff --git a/additionaldocs/deployment/README.md b/docs/deployment/README.md similarity index 100% rename from additionaldocs/deployment/README.md rename to docs/deployment/README.md diff --git a/additionaldocs/deployment/aws-ec2.md b/docs/deployment/aws-ec2.md similarity index 100% rename from additionaldocs/deployment/aws-ec2.md rename to docs/deployment/aws-ec2.md diff --git a/additionaldocs/deployment/aws-ecs-fargate.md b/docs/deployment/aws-ecs-fargate.md similarity index 100% rename from additionaldocs/deployment/aws-ecs-fargate.md rename to docs/deployment/aws-ecs-fargate.md diff --git a/additionaldocs/deployment/aws-sagemaker.md b/docs/deployment/aws-sagemaker.md similarity index 100% rename from additionaldocs/deployment/aws-sagemaker.md rename to docs/deployment/aws-sagemaker.md diff --git a/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json b/docs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json similarity index 100% rename from additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json rename to docs/deployment/aws-sagemaker/graph-explorer-neptune-analytics-policy.json diff --git a/additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json b/docs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json similarity index 100% rename from additionaldocs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json rename to docs/deployment/aws-sagemaker/graph-explorer-neptune-db-policy.json diff --git a/additionaldocs/deployment/aws-sagemaker/install-graph-explorer-lc.sh b/docs/deployment/aws-sagemaker/install-graph-explorer-lc.sh similarity index 100% rename from additionaldocs/deployment/aws-sagemaker/install-graph-explorer-lc.sh rename to docs/deployment/aws-sagemaker/install-graph-explorer-lc.sh diff --git a/additionaldocs/deployment/configuration.md b/docs/deployment/configuration.md similarity index 100% rename from additionaldocs/deployment/configuration.md rename to docs/deployment/configuration.md diff --git a/additionaldocs/deployment/database-setup.md b/docs/deployment/database-setup.md similarity index 100% rename from additionaldocs/deployment/database-setup.md rename to docs/deployment/database-setup.md diff --git a/additionaldocs/deployment/default-connection.md b/docs/deployment/default-connection.md similarity index 100% rename from additionaldocs/deployment/default-connection.md rename to docs/deployment/default-connection.md diff --git a/additionaldocs/deployment/docker.md b/docs/deployment/docker.md similarity index 100% rename from additionaldocs/deployment/docker.md rename to docs/deployment/docker.md diff --git a/additionaldocs/deployment/https-setup.md b/docs/deployment/https-setup.md similarity index 100% rename from additionaldocs/deployment/https-setup.md rename to docs/deployment/https-setup.md diff --git a/additionaldocs/development/README.md b/docs/development/README.md similarity index 100% rename from additionaldocs/development/README.md rename to docs/development/README.md diff --git a/additionaldocs/development/development-setup.md b/docs/development/development-setup.md similarity index 100% rename from additionaldocs/development/development-setup.md rename to docs/development/development-setup.md diff --git a/additionaldocs/development/release.md b/docs/development/release.md similarity index 100% rename from additionaldocs/development/release.md rename to docs/development/release.md diff --git a/additionaldocs/development/troubleshooting.md b/docs/development/troubleshooting.md similarity index 100% rename from additionaldocs/development/troubleshooting.md rename to docs/development/troubleshooting.md diff --git a/additionaldocs/getting-started/README.md b/docs/getting-started/README.md similarity index 100% rename from additionaldocs/getting-started/README.md rename to docs/getting-started/README.md diff --git a/additionaldocs/getting-started/requirements.md b/docs/getting-started/requirements.md similarity index 100% rename from additionaldocs/getting-started/requirements.md rename to docs/getting-started/requirements.md diff --git a/additionaldocs/troubleshooting/README.md b/docs/troubleshooting/README.md similarity index 100% rename from additionaldocs/troubleshooting/README.md rename to docs/troubleshooting/README.md diff --git a/additionaldocs/troubleshooting/schema-sync.md b/docs/troubleshooting/schema-sync.md similarity index 100% rename from additionaldocs/troubleshooting/schema-sync.md rename to docs/troubleshooting/schema-sync.md diff --git a/additionaldocs/user-guide/README.md b/docs/user-guide/README.md similarity index 100% rename from additionaldocs/user-guide/README.md rename to docs/user-guide/README.md diff --git a/additionaldocs/user-guide/connections.md b/docs/user-guide/connections.md similarity index 100% rename from additionaldocs/user-guide/connections.md rename to docs/user-guide/connections.md diff --git a/additionaldocs/user-guide/data-explorer.md b/docs/user-guide/data-explorer.md similarity index 100% rename from additionaldocs/user-guide/data-explorer.md rename to docs/user-guide/data-explorer.md diff --git a/additionaldocs/user-guide/graph-explorer.md b/docs/user-guide/graph-explorer.md similarity index 100% rename from additionaldocs/user-guide/graph-explorer.md rename to docs/user-guide/graph-explorer.md diff --git a/additionaldocs/user-guide/security.md b/docs/user-guide/security.md similarity index 100% rename from additionaldocs/user-guide/security.md rename to docs/user-guide/security.md diff --git a/additionaldocs/user-guide/settings.md b/docs/user-guide/settings.md similarity index 100% rename from additionaldocs/user-guide/settings.md rename to docs/user-guide/settings.md diff --git a/additionaldocs/user-guide/table-view.md b/docs/user-guide/table-view.md similarity index 100% rename from additionaldocs/user-guide/table-view.md rename to docs/user-guide/table-view.md From f520799dc39bf007f3eb514fb09ec42f7b9bddac Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 15:40:15 -0400 Subject: [PATCH 36/37] Remove extraneous code fence --- docs/deployment/aws-sagemaker.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/deployment/aws-sagemaker.md b/docs/deployment/aws-sagemaker.md index 19f8f94d3..969a3458b 100644 --- a/docs/deployment/aws-sagemaker.md +++ b/docs/deployment/aws-sagemaker.md @@ -97,7 +97,3 @@ Below are examples of which IAM permissions you need for Graph Explorer. - [IAM permissions for Neptune DB](aws-sagemaker/graph-explorer-neptune-db-policy.json) - [IAM permissions for Neptune Analytics](aws-sagemaker/graph-explorer-neptune-analytics-policy.json) - -``` - -``` From a43d3176b9dc355e650a21101f5842381a802b50 Mon Sep 17 00:00:00 2001 From: Kris McGinnes Date: Fri, 12 Sep 2025 15:41:51 -0400 Subject: [PATCH 37/37] Remove generated docs --- docs/development/development-setup.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/development/development-setup.md b/docs/development/development-setup.md index c3c02dc83..619a3d354 100644 --- a/docs/development/development-setup.md +++ b/docs/development/development-setup.md @@ -7,8 +7,6 @@ application, or for configuring advanced settings for development. - pnpm >=10.12.1 - node >=24.4.0 -- [Docker](https://docs.docker.com/get-docker/) installed on your machine -- [Git](https://git-scm.com/downloads) installed on your machine ### Node Version