Skip to content

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.

  • 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 login or aws 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)
  1. Clone the repository and install the nx-neptune library from source:

    Terminal window
    git clone https://github.com/awslabs/nx-neptune.git
    cd nx-neptune
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -e .
  2. Install the proxy and build the UI:

    Terminal window
    cd proxy
    make install
    make ui
  3. Export your AWS credentials and region, then start the proxy:

    Terminal window
    export AWS_DEFAULT_REGION=us-west-2
    make dev
  4. make dev opens 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.

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/:

Terminal window
aws sso login --profile <profile>
eval "$(aws configure export-credentials --profile <profile> --format env)"
export AWS_DEFAULT_REGION=<region-of-your-graphs>
make up-ge

AWS_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.