Skip to content

environment-variables.md

Latest commit

 

History

History
275 lines (194 loc) · 5.68 KB

environment-variables.md

File metadata and controls

275 lines (194 loc) · 5.68 KB
Raw

Environment Variables

Configuration guide for the GraphQL proxy server environment variables.

Required Variables

UPSTREAM_GRAPHQL_ENDPOINT or GRAPHQL_ENDPOINT

Upstream GraphQL API endpoint URL

# Direct configuration
UPSTREAM_GRAPHQL_ENDPOINT=https://api.example.com/graphql

# Alternative name (also supported)
GRAPHQL_ENDPOINT=https://api.example.com/graphql

Requirements:

  • Must be a valid HTTP/HTTPS URL
  • Must point to a GraphQL API endpoint
  • Must be accessible from the server

Verification:

curl -X POST $UPSTREAM_GRAPHQL_ENDPOINT \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

Authentication

AUTH_TOKEN or UPSTREAM_AUTH_TOKEN

Authentication token for upstream GraphQL API

# Bearer token authentication
AUTH_TOKEN=your-auth-token-here

# Alternative name (also supported)
UPSTREAM_AUTH_TOKEN=your-auth-token-here

Usage: Sent as Authorization: Bearer <token> header with authenticated requests

Server Configuration

PORT

Server listening port

# Default port
PORT=5001

# Custom port
PORT=8080

# For containerized deployments
PORT=80

Default: 5001 Type: Number

BIND_HOST

Host/interface to bind the HTTP server

# Default (bind all interfaces)
BIND_HOST=0.0.0.0

# Local-only
BIND_HOST=127.0.0.1

Default: 0.0.0.0

Storage Configuration

CACHE_DIR

Directory for GraphQL response caching

# Default location
CACHE_DIR=./data/graphql-cache

# Custom location
CACHE_DIR=/tmp/graphql-cache

# Absolute path
CACHE_DIR=/var/cache/graphql-proxy

Default: ./data/graphql-cache Requirements: Directory must be writable by the server process

PATHS_RELATIVE_TO / PATHS_BASE_DIR

Controls how relative paths are resolved for CACHE_DIR, QUEUE_DIR, and LOCAL_DB_PATH.

By default, values like ./data/graphql-cache are resolved from the current working directory (cwd). If you want relative paths to be resolved from the location of the executable file (useful when you copy the built file into another project), switch to script.

# Default behavior (relative to where you run the process from)
PATHS_RELATIVE_TO=cwd

# Resolve relative paths from the directory of the executable file
PATHS_RELATIVE_TO=script

# Explicit base directory (overrides PATHS_RELATIVE_TO)
PATHS_BASE_DIR=/absolute/or/relative/base/dir

Examples:

# If your built file is at: other-project/src/endpoint.mjs
# and you want: other-project/src/data/graphql-cache
PATHS_RELATIVE_TO=script
CACHE_DIR=./data/graphql-cache

# If you want: other-project/data/graphql-cache (project root)
PATHS_RELATIVE_TO=cwd
CACHE_DIR=./data/graphql-cache

QUEUE_DIR

Directory for mutation queue storage

# Default location
QUEUE_DIR=./data/mutation-queue

# Custom location
QUEUE_DIR=/tmp/mutation-queue

# Absolute path
QUEUE_DIR=/var/queue/graphql-proxy

Default: ./data/mutation-queue Requirements: Directory must be writable by the server process

LOCAL_DB_PATH

Path to local JSON database file

# Default location
LOCAL_DB_PATH=./data/local-db.json

# Custom location
LOCAL_DB_PATH=/tmp/local-db.json

# Absolute path
LOCAL_DB_PATH=/var/db/graphql-proxy/local.json

Default: ./data/local-db.json Requirements: File must be writable by the server process

CORS Configuration

CORS_ORIGIN

Allowed CORS origins

# Allow all origins (default)
CORS_ORIGIN=*

# Single origin
CORS_ORIGIN=https://myapp.com

# Multiple origins (comma-separated)
CORS_ORIGIN=https://app1.com,https://app2.com

Default: * Security: Use specific origins in production

GraphQL Mode

GRAPHQL_MODE

GraphQL operation mode

# Read-only mode: queries only, mutations blocked
GRAPHQL_MODE=GETMODE

# Offline-capable mode: mutations queued when offline
GRAPHQL_MODE=SETMODE

# CRUD mode: mutations fail when offline
GRAPHQL_MODE=CRUDMODE

Default: GETMODE Options:

  • GETMODE: Queries forwarded to upstream, mutations blocked
  • SETMODE: Queries forwarded, mutations executed online/queued offline
  • CRUDMODE: Queries forwarded, mutations executed online/fail offline

Environment Examples

Development

# Basic development setup
UPSTREAM_GRAPHQL_ENDPOINT=http://localhost:4000/graphql
PORT=5001
GRAPHQL_MODE=SETMODE

# Optional: enable authentication
AUTH_TOKEN=dev-token-123

Production

# Production configuration
UPSTREAM_GRAPHQL_ENDPOINT=https://api.production.com/graphql
AUTH_TOKEN=prod-token-456
PORT=80
GRAPHQL_MODE=SETMODE

# Custom storage locations
CACHE_DIR=/var/cache/graphql-proxy
QUEUE_DIR=/var/queue/graphql-proxy
LOCAL_DB_PATH=/var/db/graphql-proxy/local.json

# Security: restrict CORS
CORS_ORIGIN=https://myapp.com

Docker

# Container configuration
PORT=80
CACHE_DIR=/app/data/cache
QUEUE_DIR=/app/data/queue
LOCAL_DB_PATH=/app/data/local.json

# Environment from Docker secrets
UPSTREAM_GRAPHQL_ENDPOINT=https://api.external.com/graphql
AUTH_TOKEN_FILE=/run/secrets/auth_token

Validation

Environment variables are validated at startup. The server will fail to start with invalid configuration:

# Check for required variables
if (!process.env.UPSTREAM_GRAPHQL_ENDPOINT && !process.env.GRAPHQL_ENDPOINT) {
  throw new Error('UPSTREAM_GRAPHQL_ENDPOINT or GRAPHQL_ENDPOINT is required');
}

# Validate URLs
try {
  new URL(graphqlEndpoint);
} catch {
  throw new Error('UPSTREAM_GRAPHQL_ENDPOINT must be a valid URL');
}

# Validate port
const port = Number(process.env.PORT ?? 5001);
if (isNaN(port) || port < 1 || port > 65535) {
  throw new Error('PORT must be a valid port number');
}