11/07 graph-explorer

Dockerfile

@@ -0,0 +1,14 @@
+# syntax=docker/dockerfile:1
+FROM amazonlinux:2
+WORKDIR /
+COPY . /graph-explorer/
+WORKDIR /graph-explorer
+RUN yum install -y curl
+RUN curl -sL https://rpm.nodesource.com/setup_16.x | bash -
+RUN yum install -y nodejs
+RUN npm install -g pnpm
+RUN pnpm install
+ENV HOME=/graph-explorer
+EXPOSE 5173
+EXPOSE 8182
+CMD ["pnpm", "dev"]

README.md

@@ -1,17 +1,81 @@
-## My Project
+# Graph Explorer
+Open source version for the Graph Explorer powered by Expero Connected.
 
-TODO: Fill this README out!
+## Development
 
-Be sure to:
+### Supported Graph Types
+- Labelled Property Graph (PG) using Gremlin
+- Resource Description Framework (RDF) using SPARQL
 
-* Change the title in this README
-* Edit your repository description on GitHub
+### Requirements
+- pnpm >=7.9.3
+- node >=16.15.1
 
-## Security
+### Run in development mode
+- `pnpm i`
+- `pnpm start`
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+### Build for production
+- `pnpm i`
+- `pnpm build:prod`
+- `dist` folder is created in the client directory.
+- Serve the static site using the method of your choice,
+for example, using `serve` npm package.
 
-## License
+### Environment variables
 
-This project is licensed under the Apache-2.0 License.
+#### Required
+- `REACT_APP_AWS_AUTH_REQUIRED`: Enable authenticated requests. By default, `false` (`boolean`).
+- `REACT_APP_AWS_CLUSTER_HOST`: Internal host to sign requests (`string`).
+
+#### Optional
+- `REACT_APP_ENV_ROOT_FOLDER`: Base folder for the public files. By default, `/` (`string`). 
+- `REACT_APP_CONNECTION_URL`: Default connection to instance. Blank by default (`string`).
+- `REACT_APP_STORE_ID`: IndexedDB store identifier, By default, `cge` (`string`).
+- `REACT_APP_STORE_NAME`: IndexedDB store name. By default, `default` (`string`).
+- `REACT_APP_STORE_VERSION`: IndexedDB store version. By default, `1.0` (`number`).
+- `REACT_APP_CONNECTION_ENGINE`: Default connection query engine work with the instance. By default, `gremlin` (`gremlin | sparql`).
+- `REACT_APP_AWS_REGION`: AWS region of your Neptune instance. By default `us-east-1` (`string`).
+- `REACT_APP_AWS_SERVICE`: AWS service name. By default `neptune-db` (`string`).
+- `PROXY_SERVER_CONNECTION_URL`: Proxy server url.
+
+### Docker Instructions
+- To build the image, `docker build -t graph-explorer .` from the root directory. Required.
+- To run the image in a container, run `docker run -dit -p 5173:5173 -p 8182:8182 --name {container_name} graph-explorer`. Optional, can be run as long as the image is there.
+
+## Connection
+
+### Connecting to Neptune
+- Ensure that your environment has access via being in the same VPC or VPC peering. 
+- If authentication is enabled, read query privileges are needed (See ReadDataViaQuery managed policy [here](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-access-examples.html#iam-auth-data-policy-example-read-query).
+
+### Connecting to Gremlin-Server
+- The Graph Explorer currently supports only HTTP(S) connections. When connecting to Gremlin-Server, ensure it is configured with a channelizer that support HTTP(S) (i.e. [Channelizer Documentation](https://tinkerpop.apache.org/javadocs/current/full/org/apache/tinkerpop/gremlin/server/Channelizer.html)). The Gremlin Server configuration can be usually found at: /conf/gremlin-server.yaml.
+- Remove “.withStrategies(ReferenceElementStrategy)” from `/scripts/generate-modern.groovy` so that properties are returned.
+- Change `gremlin.tinkergraph.vertexIdManager` and `gremlin.tinkergraph.edgeIdManager` in `/conf/tinkergraph-empty.properties` to support string ids.
+- Build and run the docker container as normal, substituting the url to access your gremlin-server in the `REACT_APP_CONNECTION_URL` env variable.
+
+### Connecting to BlazeGraph
+- Build and run the docker container as normal and connect to BlazeGraph through the proxy server.
 
+### Using the Proxy Server
+- Set `PROXY_SERVER_CONNECTION_URL` to the url that accesses your database. If needed you can change the port inside `node-server.js`.
+- Set `REACT_APP_CONNECTION_URL` to the url that accesses your proxy server.
+- For Neptune connections, the proxy server will check to make sure the url passed in for `PROXY_SERVER_CONNECTION_URL` is a reader endpoing. Beware that if you have a single-instance cluster, the reader endpoint will be registered as having a write role and the application will throw an error as a result. This check is only made for Neptune connections and if connecting to Neptune, please ensure that `REACT_APP_AWS_SERVICE` is set to `neptune-db`.
+
+## Authentication
+
+Authentication is enabled using the SigV4 signing process found [here](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
+
+### Use
+- To use auth, you must run requests through the proxy server. This is where credentials are resolved and the signing logic is.
+- For further information on how to properly have credentials resolved, refer to this [documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CredentialProviderChain.html)
+- To use the SharedIniFileCredentials or ProcessCredentials, place your `.aws` folder at the root of the project before creating the docker container.
+
+### Potential Errors
+- If the explorer crashes, you can recreate the container or run `pnpm start` inside of `/packages/client`.
+- If the proxy-server crashes, you can recreate the container or run `pnpm start` inside of `/packages/proxy-server`
+- If the proxy-server fails to start, check that you have a read-only endpoint, that it 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.
+
+## License
+This project is licensed under the Apache-2.0 License.

package.json

@@ -0,0 +1,42 @@
+{
+  "name": "graph-explorer",
+  "version": "1.0.0",
+  "description": "Graph Explorer",
+  "packageManager": "[email protected]",
+  "engines": {
+    "node": ">=16.15.1"
+  },
+  "scripts": {
+    "prepare": "husky install",
+    "precommit": "lint-staged && pnpm types:check",
+    "lint": "pnpm -F @graph-explorer/client lint",
+    "format": "pnpm -F @graph-explorer/client format",
+    "test": "pnpm -F @graph-explorer/client test",
+    "types:check": "pnpm -F @graph-explorer/client types:check",
+    "start": "pnpm -F @graph-explorer/client start",
+    "build:dev": "pnpm -F @graph-explorer/client build:dev",
+    "build:prod": "pnpm -F @graph-explorer/client build:prod",
+    "start:proxy-server": "pnpm -F @graph-explorer/proxy-server start",
+    "dev": "concurrently \"pnpm start:proxy-server\" \"pnpm start\""
+  },
+  "author": "amazon",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^5.40.0",
+    "@typescript-eslint/parser": "^5.41.0",
+    "concurrently": "^7.5.0",
+    "eslint": "^7.32.0",
+    "eslint-plugin-react": "^7.31.10",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "husky": "^8.0.0",
+    "lint-staged": "^13.0.3",
+    "prettier": "2.1.2",
+    "typescript": "^4.8.4"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

packages/client/.env.development

@@ -0,0 +1,9 @@
+REACT_APP_STORE_ID=graph-explorer
+REACT_APP_STORE_NAME=graph-explorer
+REACT_APP_STORE_VERSION=1.0
+REACT_APP_CONNECTION_URL=
+REACT_APP_AWS_AUTH_REQUIRED=false
+REACT_APP_AWS_REGION=us-east-1
+REACT_APP_AWS_SERVICE=neptune-db
+REACT_APP_AWS_CLUSTER_HOST=
+PROXY_SERVER_CONNECTION_URL=

packages/client/.env.production

@@ -0,0 +1,9 @@
+REACT_APP_STORE_ID=graph-explorer
+REACT_APP_STORE_NAME=graph-explorer
+REACT_APP_STORE_VERSION=1.0
+REACT_APP_CONNECTION_URL=
+REACT_APP_AWS_AUTH_REQUIRED=true
+REACT_APP_AWS_REGION=us-east-1
+REACT_APP_AWS_SERVICE=neptune-db
+REACT_APP_AWS_CLUSTER_HOST=
+PROXY_SERVER_CONNECTION_URL=

packages/client/.eslintrc

@@ -0,0 +1,43 @@
+/**
+ * About ESLint configuration:
+ * react-app extends from ESLint Recommended:
+ * https://github.com/eslint/eslint/blob/master/conf/eslint-recommended.js
+ * react-app definition: https://github.com/facebook/create-react-app/blob/master/.eslintrc.json
+ */
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:react/recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react-hooks/recommended",
+    "plugin:react/jsx-runtime"
+  ],
+  "overrides": [],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["react", "@typescript-eslint"],
+  "rules": {
+    "no-unused-vars": "off",
+    "@typescript-eslint/no-unused-vars": "error",
+    "react-hooks/exhaustive-deps": "error",
+    "react/react-in-jsx-scope": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "react/prop-types": "off",
+    "@typescript-eslint/no-empty-function": "off",
+    "react/display-name": "off",
+    "no-console": ["error", { "allow": ["warn", "error"] }]
+  },
+  "settings": {
+    "react": {
+      "version": "17"
+    }
+  }
+}

packages/client/.npmrc

@@ -0,0 +1,2 @@
+auto-install-peers=true
+engine-strict=true

packages/client/.nvmrc

@@ -0,0 +1 @@
+v16

packages/client/.pipelines.npmrc

@@ -0,0 +1,2 @@
+workspace-concurrency = 1
+child-concurrency = 2

packages/client/.prettierignore

@@ -0,0 +1,3 @@
+.DS_Store
+node_modules/
+dist/

packages/client/.prettierrc

@@ -0,0 +1,14 @@
+{
+  "arrowParens": "avoid",
+  "jsxBracketSameLine": false,
+  "jsxSingleQuote": false,
+  "proseWrap": "always",
+  "quoteProps": "as-needed",
+  "semi": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "useTabs": false,
+  "singleQuote": false,
+  "bracketSpacing": true,
+  "printWidth": 80
+}

packages/client/babel.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  presets: [
+    "@babel/preset-env",
+    ["@babel/preset-react", { runtime: "automatic" }],
+  ],
+};

packages/client/index.html

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" href="%REACT_APP_ENV_ROOT_FOLDER%/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <meta
+            name="description"
+            content="Graph Explorer powered by Expero Connected"
+    />
+    <link rel="apple-touch-icon" sizes="180x180" href="%REACT_APP_ENV_ROOT_FOLDER%/apple-touch-icon.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="%REACT_APP_ENV_ROOT_FOLDER%/favicon-32x32.png">
+    <link rel="icon" type="image/png" sizes="16x16" href="%REACT_APP_ENV_ROOT_FOLDER%/favicon-16x16.png">
+    <link rel="mask-icon" href="%PUBLIC_URL%/safari-pinned-tab.svg" color="#FFFFFF">
+    <meta name="theme-color" content="#ffffff">
+    <!--
+      manifest.json provides metadata used when your web app is installed on a
+      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
+    -->
+    <link rel="manifest" href="%REACT_APP_ENV_ROOT_FOLDER%/manifest.json" />
+    <!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+    <title>Graph Explorer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

packages/client/jest.config.ts

@@ -0,0 +1,9 @@
+import type { Config } from "jest";
+
+const config: Config = {
+  verbose: true,
+  preset: "ts-jest",
+  testEnvironment: "jsdom",
+};
+
+export default config;