Proxy UI Setup
The nx-neptune proxy is a local web UI and REST API for the Graph Over Data Lake workflow. It lets you browse your Athena tables, define a graph with SQL or a CREATE PROPERTY GRAPH statement, import it into Neptune Analytics, and manage the graph, without writing code. It runs the same Athena → S3 → Neptune Analytics pipeline as SessionManager.
The proxy runs on your machine and listens on 127.0.0.1 only. Graph Explorer can be started next to it as a container to visualize the graphs you create.
Prerequisites
Section titled “Prerequisites”- Python 3.11 or later
- Node.js and npm, to build the UI
- finch or Docker, only to run Graph Explorer (see Start Graph Explorer)
- AWS credentials and a region exported in your shell. Use short-lived credentials (for example from
aws sso loginoraws sts assume-role), not long-lived access keys - The IAM permissions listed in Prerequisites, including the Proxy UI section and the import role trust statement
- An S3 staging bucket with versioning enabled, in the same region as your graphs (see S3 import/export)
Start the proxy
Section titled “Start the proxy”-
Clone the repository and install the nx-neptune library from source:
Terminal window git clone https://github.com/awslabs/nx-neptune.gitcd nx-neptunepython3 -m venv .venvsource .venv/bin/activatepip install -e . -
Install the proxy and build the UI:
Terminal window cd proxymake installmake ui -
Export your AWS credentials and region, then start the proxy:
Terminal window export AWS_DEFAULT_REGION=us-west-2make dev -
make devopens the launch URL in your browser. It’s also printed on startup:Open the proxy UI (token valid for this run only):http://127.0.0.1:8080/?token=<token>
The token is generated each time the proxy starts and is required for every API call. Opening http://127.0.0.1:8080 without it loads the page, but the API calls fail. The UI stores the token in the browser’s local storage for http://127.0.0.1:8080, so page refreshes and new tabs keep working. After a restart (including an auto-reload by make dev), open the new launch URL from the proxy output.
Start Graph Explorer
Section titled “Start Graph Explorer”Graph Explorer is optional. Start it only when you want to visualize a graph. It runs in a container:
| Runtime | RUNTIME= |
One-time setup |
|---|---|---|
| finch (default) | finch |
finch vm init, then finch vm start after each restart |
| Docker | docker |
Docker Engine or Docker Desktop with Compose v2 (docker compose) |
Pass the same RUNTIME= value to every target, for example make up-ge RUNTIME=docker and make down RUNTIME=docker. Podman (RUNTIME=podman, with podman-compose) works with GE_PORT set to a port above 1024 (see below), because rootless podman can’t bind port 443.
Graph Explorer signs its requests to Neptune Analytics with the AWS credentials exported in your shell. It can’t read a profile or the aws sso login cache, so export the credentials as environment variables. In a second shell, run from proxy/:
aws sso login --profile <profile>eval "$(aws configure export-credentials --profile <profile> --format env)"export AWS_DEFAULT_REGION=<region-of-your-graphs>make up-geAWS_DEFAULT_REGION must be the region of your graphs. If it isn’t set, Graph Explorer uses us-west-2.
This starts only the Graph Explorer container, on https://localhost. It uses host port 443; to use another port, set GE_PORT (for example GE_PORT=8443). If your credentials expire, export new ones and run make up-ge again. To stop Graph Explorer, run make down.
The container publishes its ports on 127.0.0.1. With finch on macOS, the finch VM can still listen on all network interfaces.
The proxy UI links to Graph Explorer at https://localhost/explorer. If you set GE_PORT, or Graph Explorer runs at a different URL, set the link when you build the UI, for example VITE_GRAPH_EXPLORER_URL=https://localhost:8443/explorer make ui. make up sets it from GE_PORT for you.
For every Makefile target and configuration variable, see the proxy README.
Next: End-to-end walkthrough.