Environment Variables

Complete reference of all environment variables for configuring Stategraph.

Required Variables

These variables must be set for Stategraph to start.

STATEGRAPH_UI_BASE

Required

Public URL where users access Stategraph.

STATEGRAPH_UI_BASE=https://stategraph.example.com

Used for:
- OAuth redirect URLs
- Internal link generation
- CORS configuration

Database Configuration

All required

DB_HOST=postgres.example.com
DB_USER=stategraph
DB_PASS=your-secure-password
DB_NAME=stategraph

Optional Variables

Server Configuration

STATEGRAPH_PORT

Internal port the backend server listens on. In containerized deployments, nginx proxies from external port 8080 to this internal port.

STATEGRAPH_PORT=8180

Default: 8180

DB_PORT

PostgreSQL port.

DB_PORT=5432

Default: 5432 (standard PostgreSQL port)

DB_CONNECT_TIMEOUT

Database connection timeout in seconds.

DB_CONNECT_TIMEOUT=120

Default: 120

DB_MAX_POOL_SIZE

Maximum database connection pool size.

DB_MAX_POOL_SIZE=100

Default: 100

DB_IDLE_TX_TIMEOUT

Idle transaction timeout.

DB_IDLE_TX_TIMEOUT=180s

Default: 180s

STATEGRAPH_DB_STATEMENT_TIMEOUT

Database statement timeout.

STATEGRAPH_DB_STATEMENT_TIMEOUT=30s

Default: 30s

STATEGRAPH_TRANSACTION_SUBGRAPH_RETENTION_DAYS

How many days a committed transaction's subgraph is retained before database garbage collection reclaims the space.

STATEGRAPH_TRANSACTION_SUBGRAPH_RETENTION_DAYS=7

Default: 7

Nginx Configuration

STATEGRAPH_ACCESS_LOG

Enable nginx access logging.

STATEGRAPH_ACCESS_LOG=/dev/stdout  # Enable
STATEGRAPH_ACCESS_LOG=off          # Disable

Default: off

STATEGRAPH_CLIENT_MAX_BODY_SIZE

Maximum request body size (for large state files).

STATEGRAPH_CLIENT_MAX_BODY_SIZE=512m

Default: 512m

DISABLE_IPV6

Disable IPv6 in nginx.

DISABLE_IPV6=1  # Disable
DISABLE_IPV6=0  # Enable

Default: 0 (IPv6 enabled)

CORS Configuration

STATEGRAPH_ENABLE_CORS

Enable CORS headers.

STATEGRAPH_ENABLE_CORS=true

Default: false

Only needed for development when UI runs on a different port.

STATEGRAPH_CORS_DEFAULT_ORIGIN

Default CORS origin.

STATEGRAPH_CORS_DEFAULT_ORIGIN=http://localhost:3000

Default: http://localhost:3000

OAuth Configuration

Basic OAuth

STATEGRAPH_OAUTH_TYPE

OAuth provider type.

STATEGRAPH_OAUTH_TYPE=google  # Google OAuth
STATEGRAPH_OAUTH_TYPE=oidc    # Generic OIDC

Values: google, oidc

Default: Not set (OAuth disabled)

STATEGRAPH_OAUTH_CLIENT_ID

Required when OAuth enabled

OAuth client ID from your provider.

STATEGRAPH_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com

STATEGRAPH_OAUTH_CLIENT_SECRET

Required when OAuth enabled

OAuth client secret from your provider.

STATEGRAPH_OAUTH_CLIENT_SECRET=your-client-secret

STATEGRAPH_OAUTH_COOKIE_SECRET

Secret used to sign the OAuth session/CSRF cookies. Must be 16, 24, or 32 characters.

STATEGRAPH_OAUTH_COOKIE_SECRET=$(openssl rand -hex 16)  # 32 chars

Default: a random value generated at startup.

Set this explicitly when running more than one replica. If it is left
unset, each replica generates its own secret, so a login whose callback is
load-balanced to a different replica than it started on fails with
403 — invalid CSRF token. Pin the same value on every replica (and keep it
stable across restarts) to avoid this. Single-replica deployments work with the
generated default, but pinning it also keeps users logged in across restarts.

STATEGRAPH_OAUTH_EMAIL_DOMAIN

Restrict access to specific email domain.

STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com  # Single domain
STATEGRAPH_OAUTH_EMAIL_DOMAIN=*                # All domains

Default: * (all domains allowed)

STATEGRAPH_OAUTH_DISPLAY_NAME

Provider name for login button (displayed as "Sign in with {name}").

STATEGRAPH_OAUTH_DISPLAY_NAME="Google"

Default: Google (for google) / SSO (for oidc)

STATEGRAPH_OAUTH_REDIRECT_BASE

Base URL for OAuth callbacks. Important: In production, you must set this to your public URL.

STATEGRAPH_OAUTH_REDIRECT_BASE=https://stategraph.example.com

Default: http://localhost:{STATEGRAPH_PORT}

Warning: If not explicitly set, OAuth redirects will use localhost, which will fail in production environments.

Google-Specific OAuth

STATEGRAPH_OAUTH_GOOGLE_GROUP

Google Group email for access restriction.

STATEGRAPH_OAUTH_GOOGLE_GROUP=stategraph-users@yourcompany.com

Requires service account configuration.

STATEGRAPH_OAUTH_GOOGLE_ADMIN_EMAIL

Admin email for Google Groups API access.

STATEGRAPH_OAUTH_GOOGLE_ADMIN_EMAIL=admin@yourcompany.com

Must be a Google Workspace super admin.

STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON

Service account JSON key for Google Admin API.

STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

Required for Google Groups integration.

OIDC-Specific OAuth

STATEGRAPH_OAUTH_OIDC_ISSUER_URL

Required when STATEGRAPH_OAUTH_TYPE=oidc

OIDC provider issuer URL.

STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://your-provider.com

The provider must support OIDC discovery at {issuer}/.well-known/openid-configuration.

Internal OAuth Configuration

STATEGRAPH_OAUTH2_API_KEY

API key for internal session storage.

STATEGRAPH_OAUTH2_API_KEY=your-random-key

Default: Auto-generated random key

STATEGRAPH_OAUTH2_PROXY_PATH

Path to oauth2-proxy binary (Docker internal use).

STATEGRAPH_OAUTH2_PROXY_PATH=/usr/local/bin/oauth2-proxy

Default: /usr/local/bin/oauth2-proxy

Complete Example

Development

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=stategraph
DB_PASS=stategraph
DB_NAME=stategraph

# Server
STATEGRAPH_UI_BASE=http://localhost:8080
STATEGRAPH_PORT=8080

# Development CORS (for separate UI server)
STATEGRAPH_ENABLE_CORS=true
STATEGRAPH_CORS_DEFAULT_ORIGIN=http://localhost:3000

Production without OAuth

# Database
DB_HOST=postgres.internal.example.com
DB_PORT=5432
DB_USER=stategraph
DB_PASS=${DB_PASSWORD}  # From secrets manager
DB_NAME=stategraph

# Server
STATEGRAPH_UI_BASE=https://stategraph.example.com
STATEGRAPH_PORT=8080

# Logging
STATEGRAPH_ACCESS_LOG=/dev/stdout

Production with Google OAuth

# Database
DB_HOST=postgres.internal.example.com
DB_PORT=5432
DB_USER=stategraph
DB_PASS=${DB_PASSWORD}
DB_NAME=stategraph

# Server
STATEGRAPH_UI_BASE=https://stategraph.example.com
STATEGRAPH_PORT=8080

# OAuth
STATEGRAPH_OAUTH_TYPE=google
STATEGRAPH_OAUTH_CLIENT_ID=${GOOGLE_CLIENT_ID}
STATEGRAPH_OAUTH_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com
STATEGRAPH_OAUTH_REDIRECT_BASE=https://stategraph.example.com

# Optional: Google Groups
STATEGRAPH_OAUTH_GOOGLE_GROUP=stategraph-users@yourcompany.com
STATEGRAPH_OAUTH_GOOGLE_ADMIN_EMAIL=admin@yourcompany.com
STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON=${GOOGLE_SERVICE_ACCOUNT}

# Logging
STATEGRAPH_ACCESS_LOG=/dev/stdout

Production with OIDC

# Database
DB_HOST=postgres.internal.example.com
DB_PORT=5432
DB_USER=stategraph
DB_PASS=${DB_PASSWORD}
DB_NAME=stategraph

# Server
STATEGRAPH_UI_BASE=https://stategraph.example.com
STATEGRAPH_PORT=8080

# OAuth
STATEGRAPH_OAUTH_TYPE=oidc
STATEGRAPH_OAUTH_OIDC_ISSUER_URL=https://your-okta.okta.com
STATEGRAPH_OAUTH_CLIENT_ID=${OIDC_CLIENT_ID}
STATEGRAPH_OAUTH_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
STATEGRAPH_OAUTH_EMAIL_DOMAIN=yourcompany.com
STATEGRAPH_OAUTH_REDIRECT_BASE=https://stategraph.example.com

# Logging
STATEGRAPH_ACCESS_LOG=/dev/stdout

Gap Analysis Configuration

Environment variables for configuring gap analysis behavior.

GCP Configuration

GOOGLE_CLOUD_PROJECT

GCP project ID for gap analysis scope.

GOOGLE_CLOUD_PROJECT=my-project-id

Default: Auto-detected from Application Default Credentials

GOOGLE_CLOUD_FOLDER

GCP folder ID for broader gap analysis scope (covers all projects in folder).

GOOGLE_CLOUD_FOLDER=123456789

Default: Not set

GOOGLE_CLOUD_ORGANIZATION

GCP organization ID for full gap analysis visibility.

GOOGLE_CLOUD_ORGANIZATION=123456789

Default: Not set

AWS Configuration

AWS_DEFAULT_REGION

AWS region for Resource Explorer queries.

AWS_DEFAULT_REGION=us-east-1

Default: From AWS credentials/config

Cache Configuration

GAP_ANALYSIS_CACHE_TTL

Gap analysis cache time-to-live in seconds.

GAP_ANALYSIS_CACHE_TTL=10800  # 3 hours

Default: 10800 (3 hours)

SG_GAP_ANALYSIS_CACHE

Directory for gap analysis cache files.

SG_GAP_ANALYSIS_CACHE=/var/cache/stategraph/gap-analysis

Default: /var/cache/stategraph/gap-analysis

Cost Analysis Configuration

Environment variables for Cost Analysis. Cost analysis is disabled until
STATEGRAPH_COST_ENABLED is set to true.

STATEGRAPH_COST_ENABLED

Master on/off switch for cost analysis. Set it to true to turn cost on; leave it unset (or false)
and cost analysis stays off — POST /costs/calculate returns 503 and capabilities.costs.enabled
is false. Because it lives in your deployment environment, cost analysis survives redeploys,
restarts, and reschedules.

STATEGRAPH_COST_ENABLED=true

Default: false (cost analysis disabled)

STATEGRAPH_PRICING_SERVICE_URL

Endpoint of the pricing service used to estimate costs. Defaults to http://localhost:8090, the
pricing service bundled in the all-in-one image, so most deployments leave it unset. Set it only to
point the server at an external pricing service.

STATEGRAPH_PRICING_SERVICE_URL=https://pricing.internal.example.com  # external service

Default: http://localhost:8090 (bundled in-image pricing service)

PRICING_REFRESH_HOURS

How often the pricing service reloads the cloud price book into the cloud_pricing database.
Set to 0 to disable automatic refresh.

PRICING_REFRESH_HOURS=168

Default: 168 (weekly)

STATEGRAPH_PRICING_DEFAULT_REGION

Region assumed when a resource does not specify one.

STATEGRAPH_PRICING_DEFAULT_REGION=us-east-1

Default: us-east-1

STATEGRAPH_COST_SCHEDULE_HOURS

How often cost snapshots are recomputed on a schedule, in hours.

STATEGRAPH_COST_SCHEDULE_HOURS=24

Default: 24

STATEGRAPH_COST_EVENT_DEBOUNCE_HOURS

Minimum number of hours before an apply triggers another recompute.

STATEGRAPH_COST_EVENT_DEBOUNCE_HOURS=6

Default: 6

STATEGRAPH_COST_PRICING_CALL_TIMEOUT_SECONDS

Timeout for a single pricing-service call, in seconds.

STATEGRAPH_COST_PRICING_CALL_TIMEOUT_SECONDS=30

Default: 30

Price-book database and loader

The pricing service loads the cloud price book into the cloud_pricing database on first boot and
refreshes it on the PRICING_REFRESH_HOURS cadence. Override where the price book lives, or mirror
its download source, with PRICING_DB_HOST / PRICING_DB_PORT, PRICING_DB_USER /
PRICING_DB_PASSWORD, PRICING_DB_NAME (default cloud_pricing), and PRICING_DATA_URL. These
default to the bundled database and Stategraph's hosted price book, so most deployments leave them
unset. See Cost Setup for the full price-book reference and
air-gapped installs.

STATEGRAPH_COSTS_WAIT_SECONDS

Client-side (CLI) variable — not a server setting. Sets the deployment-level default for the
--costs-wait flag on stategraph tf plan and stategraph tf apply, the number of
seconds the CLI waits for the cost delta to become available. Unlike the flag, this variable may be
set alongside --skip-costs; when both apply, --skip-costs takes precedence.

STATEGRAPH_COSTS_WAIT_SECONDS=3

Default: 3

Variable Reference Table