aws · kmcginnes · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/docs/development.md b/docs/development.md
@@ -1,13 +1,13 @@
-## Development
+# 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
+## Requirements
 
 - pnpm >=10.28.1
 - node >=24.13.0
 
-#### Node Version
+### 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:
 
@@ -17,7 +17,7 @@ nvm use
 
 Otherwise, use whatever method you use to install [Node v24.13.0](https://nodejs.org/en/download).
 
-#### Node Corepack
+### Node Corepack
 
 [Corepack](https://nodejs.org/api/corepack.html) is used to ensure the package manager used for the project is consistent.
 
@@ -27,12 +27,12 @@ corepack enable
 
 If `corepack` is not found, install it first with `npm install -g corepack@latest`.
 
-### Supported Graph Data Models and Query Languages
+## Supported Graph Data Models and Query Languages
 
 - Labelled Property Graph (PG) using Gremlin or openCypher
 - Resource Description Framework (RDF) using SPARQL
 
-### Run in development mode
+## Run in development mode
 
 Install any missing or updated dependencies.
 
@@ -54,7 +54,7 @@ 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
+## Build for production
 
 Building Graph Explorer is simple.
 
@@ -76,7 +76,7 @@ The recommended way to serve Graph Explorer is using the proxy server.
 pnpm start
 ```
 
-### Build and run with Docker
+## Build and run with Docker
 
 You can also build and run Graph Explorer as a Docker image from source.
 
@@ -96,7 +96,7 @@ docker run -p 80:80 \
 
 Then open [http://localhost/explorer](http://localhost/explorer) in your browser.
 
-### Managing dependencies
+## Managing dependencies
 
 If you need to add, remove, or update a dependency you can easily do so from the root folder in the CLI:
 
@@ -108,18 +108,18 @@ pnpm add react --filter graph-explorer
 pnpm add -D vitest --filter graph-explorer-proxy-server
 ```
 
-#### Preparation of a release
+### Preparation of a release
 
-This repository is composed by 3 packages and a mono-repository structure itself. Then, you need to take into account 4 different `package.json` files:
+This repository is composed of 3 packages and a mono-repository structure itself. Then, you need to take into account 4 different `package.json` files:
 
 - `<root>/package.json` is intended to keep the dependencies for managing the repository. It has utilities like linter, code formatter, or git checks.
 - `<root>/packages/graph-explorer/package.json` is the package file that describes the UI client package.
 - `<root>/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.
 - `<root>/packages/shared/package.json` is the package file for shared code between the client and server packages.
 
-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 4 files. Regarding the version number displayed in the user interface, it is specifically extracted from the `<root>/packages/graph-explorer/package.json`. file
+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 4 files. Regarding the version number displayed in the user interface, it is specifically extracted from the `<root>/packages/graph-explorer/package.json` file.
 
-### Supply chain security
+## Supply chain security
 
 The `pnpm-workspace.yaml` file includes several settings that harden the project against supply chain attacks. These may cause `pnpm install` to fail when adding new dependencies, which is intentional.
 
@@ -130,7 +130,7 @@ The `pnpm-workspace.yaml` file includes several settings that harden the project
 
 If `pnpm install` fails due to one of these checks, evaluate whether the dependency is safe and update `pnpm-workspace.yaml` accordingly.
 
-### Local environment overrides
+## Local environment overrides
 
 Create a `.env.local` file in `packages/graph-explorer/` to override environment variables without modifying tracked files. This file is gitignored and will not be committed.
 
@@ -141,95 +141,15 @@ GRAPH_EXP_DEV_PORT=5174
 PROXY_SERVER_HTTP_PORT=8082
 ```
 
-### Environment variables
+## Environment variables
 
-For development-only variables like `GRAPH_EXP_DEV_PORT`, see [Development-only environment variables](#development-only-environment-variables).
+See the [Configuration Reference](./references/configuration.md) for all available environment variables including application settings and default connection options.
 
-#### `GRAPH_EXP_ENV_ROOT_FOLDER`
-
-Base path used to serve the `graph-explorer` front end application.
-
-Example: `/explorer`
-
-- Optional
-- Default: `/`
-- Type: `string`
-
-#### `HOST`
-
-The public hostname of the server. This is used to generate the self-signed SSL certificate at container startup.
-
-Example: `localhost`
-
-- Required when using HTTPS connections
-- Default is `localhost`
-- Type: `string`
-
-#### `GRAPH_EXP_HTTPS_CONNECTION`
-
-Uses the self-signed certificate to serve Graph Explorer over https if true. Only used in Docker via the entrypoint script.
-
-- Optional
-- Default `true` in Docker, not set otherwise
-- 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 `false` in code, `true` in Docker via the entrypoint script
-- Type: `boolean`
-
-#### `PROXY_SERVER_CORS_ORIGIN`
-
-Restricts which origins are allowed to make cross-origin requests to the proxy server. When set, only requests from these exact origins will receive CORS headers. When not set, all origins are allowed. Each origin must include the scheme and must not have a trailing slash or path.
-
-Example: `https://my-app.example.com` or `https://app-a.example.com,https://app-b.example.com`
-
-- Optional
-- Default: all origins allowed
-- Type: `string` (comma-separated for multiple origins)
-
-#### `LOG_STYLE`
-
-Controls the log output format.
-
-- Optional
-- Default: `default`
-- Type: `"cloudwatch" | "default"`
-- `cloudwatch` omits timestamps and hostname/pid (these are provided by CloudWatch)
-- `default` uses the standard log format
-
-#### `CONFIGURATION_FOLDER_PATH`
-
-Override path for the folder containing `.env` and `defaultConnection.json`. When set, replaces the default path entirely.
-
-- Optional
-- Default: `<client root>` (`packages/graph-explorer`)
-- Type: `string`
-
-### Development-only environment variables
+## Development-only environment variables
 
 These variables only affect the local development server (`pnpm dev`) and have no effect on production builds or Docker.
 
-#### `GRAPH_EXP_DEV_PORT`
+### `GRAPH_EXP_DEV_PORT`
 
 Sets a fixed port for the Vite development server. When set, `strictPort` is enabled — Vite will fail with an error if the port is already in use rather than silently selecting another port. This ensures the dev server runs on the exact port you intend.
 
@@ -239,18 +159,18 @@ Example: `5174`
 - Default: Vite's default behavior (auto-selects an available port starting at 5173)
 - Type: `number`
 
-### Using self-signed certificates with Docker
+## 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 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
+## Using self-signed certificates on Chrome
 
 See [Removing the "Not Secure" warning on Chrome](./references/security.md#removing-the-not-secure-warning-on-chrome) in the security reference.
 
-### Troubleshooting
+## 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`

diff --git a/docs/guides/deploy-to-ecs-fargate.md b/docs/guides/deploy-to-ecs-fargate.md
@@ -2,9 +2,9 @@
 
 # Running Graph Explorer on AWS Fargate + Amazon ECS
 
-The following steps will allow you set up Graph Explorer on AWS Fargate in Amazon ECS, and connect to a running Neptune database.
+The following steps will allow you to set up Graph Explorer on AWS Fargate in Amazon ECS, and connect to a running Neptune database.
 
-### Create a new IAM role and permission policies
+## Create a new IAM role and permission policies
 
 1. Open the IAM console at https://console.aws.amazon.com/iam/.
 2. In the navigation pane, click **Roles**, and then click **Create role**.
@@ -18,7 +18,7 @@ The following steps will allow you set up Graph Explorer on AWS Fargate in Amazo
 
 ![image](./deploy-to-ecs-fargate/iam-role.png)
 
-### Create an Amazon ECS Cluster
+## Create an Amazon ECS Cluster
 
 1. Open the ECS console at https://console.aws.amazon.com/ecs/v2.
 2. In the left hand navigation pane, click **Clusters**.
@@ -29,7 +29,7 @@ The following steps will allow you set up Graph Explorer on AWS Fargate in Amazo
 5. Under **Infrastructure**, select only **AWS Fargate**.
 6. (Optional) To turn on Container Insights, expand **Monitoring**, and then turn on **Use Container Insights**.
 7. (Optional) To help identify your cluster, expand **Tags**, and then configure your tags.
-   - [Add a tag] Choose **Add tag and** do the following:
+   - [Add a tag] Choose **Add tag** and do the following:
      - For **Key**, enter the key name.
      - For **Value**, enter the key value.
 8. Click **Create**.
@@ -38,7 +38,7 @@ After the cluster has finished creation, you can create task definitions for you
 
 ![image](./deploy-to-ecs-fargate/ecs-cluster.png)
 
-### Request an ACM Public Certificate
+## Request an ACM Public Certificate
 
 1. Open the ACM console at https://console.aws.amazon.com/acm/home.
 2. In the left hand navigation pane, click **Request certificate**.
@@ -59,7 +59,7 @@ After the cluster has finished creation, you can create task definitions for you
 
 After the request is processed, the console will return you to your certificate list, where information about the certificate will be displayed. The newly requested certificate will initially display the status `Pending validation`. Once the verification is successful, ACM will issue the SSL/TLS certificate for the specified domain names.
 
-### Creating an ECS Task Definition
+## Creating an ECS Task Definition
 
 1. Open the ECS console at https://console.aws.amazon.com/ecs/v2.
 2. In the left hand navigation pane, choose **Task definitions**.
@@ -159,7 +159,7 @@ After the request is processed, the console will return you to your certificate
    ```
 5. In the JSON template, update the following fields:
    - `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 Connection](../references/default-connection.md) for more details):
+   - `environment` variables section (see [Configuration](../references/configuration.md#default-connection) 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 cluster has IAM db authentication enabled.
@@ -168,7 +168,7 @@ After the request is processed, the console will return you to your certificate
      - `SERVICE_TYPE`: Set this as `neptune-db` for Neptune database or `neptune-graph` for Neptune Analytics.
 6. Click **Create**.
 
-### Create a Fargate Service
+## Create a Fargate Service
 
 1. Open the ECS console at https://console.aws.amazon.com/ecs/v2.
 2. In the left hand navigation pane, choose **Clusters**.
@@ -212,7 +212,7 @@ After few minutes, the Fargate service will be created and ready.
 
 <img alt="image" src="./deploy-to-ecs-fargate/fargate-service.png">
 
-### Create an Amazon Route53 Entry
+## Create an Amazon Route53 Entry
 
 1. Open the Route 53 console at https://console.aws.amazon.com/route53/.
 2. In the left hand navigation pane, click **Hosted zones**.
@@ -229,6 +229,6 @@ After few minutes, the Fargate service will be created and ready.
 
 Changes generally propagate to all Route 53 servers within 60 seconds. When propagation is done, you'll be able to route traffic to your load balancer by using the name of the alias record that you created in the above step.
 
-### Accessing Graph Explorer
+## Accessing Graph Explorer
 
 Enter the URL you created in the Route53 section into a browser to access the endpoint for Graph Explorer (ex.`https://graphexplorer.example.com/explorer`). You should now be connected.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
@@ -12,7 +12,7 @@ This page contains workarounds for common issues and information on how to diagn
 ## 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.
+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 there are any errors related to connectivity.
 
 ### Ports in Use
 
@@ -34,7 +34,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](../development.md#environment-variables):
+If you do not want to use SSL and HTTPS, you can disable it by setting the following [environment variables](../references/configuration.md#application-configuration):
 
 ```
 PROXY_SERVER_HTTPS_CONNECTION=false

diff --git a/docs/references/README.md b/docs/references/README.md
@@ -2,8 +2,8 @@
 
 Technical reference documentation for Graph Explorer covering configuration, security, and operational details.
 
+- [Configuration](./configuration.md) - Environment variables for application settings and default connections
 - [Minimum Requirements](./minimum-requirements.md) - Recommended database and query language versions
 - [Security](./security.md) - HTTPS connections, certificates, and permissions
 - [Health Check](./health-check.md) - Proxy server health and readiness endpoint
 - [Logging](./logging.md) - Log levels, output, and proxy server logging modules
-- [Default Connection](./default-connection.md) - Configure a default connection via environment variables or JSON