Auto-load graph-explorer-config.json on startup

[jeremy-london]

Description

This PR implements automatic loading of graph-explorer-config.json on Graph Explorer startup, similar to how defaultConnection.json is currently auto-loaded. This enables infrastructure-as-code deployments and simplifies Docker-based setups by eliminating the need for manual configuration loading.

Key Changes:

1. Proxy Server (packages/graph-explorer-proxy-server/src/node-server.ts):

   • Added route GET /graph-explorer-config.json to serve the backup config file from CONFIGURATION_FOLDER_PATH
   • Handles missing files gracefully with 404 responses (no error logging)
   • Logs when the backup config file is available for serving

2. Frontend Auto-Load (packages/graph-explorer/src/core/StateProvider/autoLoadBackup.ts):

   • Created new utility function autoLoadBackupIfExists() that checks if IndexedDB is empty
   • Automatically fetches and restores backup config when no existing configuration exists
   • Supports GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG environment variable to always load config (overriding IndexedDB)
   • Uses existing restoreBackup() functionality for consistency
   • Handles errors gracefully without blocking app startup

3. Environment Variable (packages/graph-explorer/src/utils/env.ts):

   • Added GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG environment variable (defaults to false)
   • Reads from import.meta.env.GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG

4. Integration (packages/graph-explorer/src/core/StateProvider/storageAtoms.ts):

   • Added call to autoLoadBackupIfExists() before atom initialization
   • Ensures backup is loaded before React initializes

5. Tests (packages/graph-explorer/src/core/StateProvider/autoLoadBackup.test.ts):

   • Comprehensive test suite with 11 test cases covering:
     • Skipping auto-load when config exists
     • Auto-loading when IndexedDB is empty
     • Force load behavior when GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG=true
     • Error handling (network errors, invalid data, missing files)
     • Edge cases (empty configs, different data formats)

6. Documentation:

   • Updated README.md with new environment variable documentation
   • Added "Auto-Load Backup Configuration" section to troubleshooting.md
   • Updated features/README.md with auto-load information
   • Added tip in getting-started/README.md
   • Added changelog entry in Changelog.md

Behavior:

• defaultConnection.json → ✅ Auto-loads (connections only) - already works
• graph-explorer-config.json → ✅ Auto-loads (full config) when IndexedDB is empty - new behavior
• graph-explorer-config.json → ✅ Always loads when GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG=true - new override option

Safety:

• Only auto-loads when IndexedDB is empty by default (prevents overwriting existing user data)
• Force load option available via environment variable for Docker deployments
• Errors are caught and logged without blocking app startup
• Non-destructive operation

Validation

Manual Testing Steps:

1. Docker Setup:

   # Create config directory with backup file
   mkdir -p config/graph-explorer
   # Place graph-explorer-config.json in config/graph-explorer/
   
   # Build and run with the config folder ENV setup to look at the folder above

2. Verify Auto-Load (Default Behavior):

   • Clear browser IndexedDB (DevTools → Application → Storage → IndexedDB → Delete ge database)
   • Or use an incognito/private window
   • Navigate to Graph Explorer
   • Verify that connections, styles, and schemas are automatically loaded
   • Check browser console for log message: "Auto-loaded backup configuration from file"

3. Verify Skip Behavior:

   • With existing IndexedDB data, refresh the page
   • Verify that auto-load is skipped (check console for "Configuration already exists, skipping auto-load")
   • Existing data should remain unchanged

4. Verify Force Load:

   • Set GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG=true in docker-compose.yml
   • With existing IndexedDB data, refresh the page
   • Verify that backup config is loaded anyway (check console for "Force-loaded backup configuration from file (overrode IndexedDB)")

5. Verify Error Handling:

   • Remove or rename graph-explorer-config.json file
   • Clear IndexedDB and refresh
   • App should start normally without errors
   • Check console for debug message: "No backup config file found or not accessible"

Automated Tests:

• Run pnpm test packages/graph-explorer/src/core/StateProvider/autoLoadBackup.test.ts - all 11 tests pass
• Run pnpm test to ensure no regressions
• Run pnpm checks to verify code quality

Expected Results:

• ✅ Backup config auto-loads on first visit (empty IndexedDB)
• ✅ Existing IndexedDB data is not overwritten (default behavior)
• ✅ Force load option works when enabled
• ✅ Missing config file doesn't cause errors
• ✅ All existing functionality continues to work

Related Issues

Fixes #1451

Check List

• I confirm that my contribution is made under the terms of the Apache 2.0
  license.
• I have run pnpm checks to ensure code compiles and meets standards.
• I have run pnpm test to check if all tests are passing.
• I have covered new added functionality with unit tests if necessary.
• I have added an entry in the Changelog.md.

[jeremy-london]

Sample docker-compose.yml - Uses aws profile on host machine via volume mount - may need tweaks if key/secret is preferred.

services:
  # Graph Explorer is a tool that allows you to explore the Neptune graph database.
  # Graph Explorer UI located at: http://localhost:5000/explorer
  graph-explorer:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: graph-explorer
    platform: linux/amd64
    ports:
      - "5000:5000"
    environment:
      - PROXY_SERVER_HTTP_PORT=5000
      - PUBLIC_OR_PROXY_ENDPOINT=http://localhost:5000
      - GRAPH_CONNECTION_URL=https://your-cluster.us-west-1.neptune.amazonaws.com:8182
      - USING_PROXY_SERVER=true
      - IAM=true
      - SERVICE_TYPE=neptune-db
      - GRAPH_TYPE=gremlin
      - GRAPH_EXP_HTTPS_CONNECTION=true
      - GRAPH_EXP_FETCH_REQUEST_TIMEOUT=240000
      - GRAPH_EXP_NODE_EXPANSION_LIMIT=500
      - PROXY_SERVER_HTTPS_CONNECTION=true
      - AWS_REGION=us-west-1
      - AWS_PROFILE=default
      - AWS_SHARED_CREDENTIALS_FILE=/root/.aws/credentials
      - AWS_CONFIG_FILE=/root/.aws/config
      - LOG_LEVEL=debug
      # Path where configuration files (defaultConnection.json and graph-explorer-config.json) are located
      - CONFIGURATION_FOLDER_PATH=/graph-explorer-config
      # Set to "true" to always load backup config file, overriding IndexedDB (default: false)
      - GRAPH_EXP_FORCE_LOAD_BACKUP_CONFIG=false
    volumes:
      - ${HOME}/.aws:/root/.aws
      # Mount config directory containing graph-explorer-config.json for auto-load on startup
      # The graph-explorer-config.json file will be automatically loaded if IndexedDB is empty
      - ${PWD}/config/graph-explorer:/graph-explorer-config
    restart: unless-stopped

[kmcginnes]

Thanks @jeremy-london. On first glance this seems to be a very complete and well considered solution. Given its size and scope it will take some time to review and test out.

That said, I'm currently focused on some other items. I'll get to this when I have some time to devote to it.

[jeremy-london]

Thanks @jeremy-london. On first glance this seems to be a very complete and well considered solution. Given its size and scope it will take some time to review and test out.

That said, I'm currently focused on some other items. I'll get to this when I have some time to devote to it.

Not a problem at all - we have a local build for what we need, and can Manually load as an alternative - just a nice quality of life improvement. Let me know if you need any changes or rebases on my end.

[kmcginnes]

Since it has been a little while, I wanted to let you know that this is still on my list to test out, but hasn't risen to the top just yet. It will be a bit longer.

[jeremy-london]

Since it has been a little while, I wanted to let you know that this is still on my list to test out, but hasn't risen to the top just yet. It will be a bit longer.

No problem! thanks for the updates - let me know when you get into it if any updates or issues come up