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

Variable	Description
`DB_HOST`	PostgreSQL hostname
`DB_USER`	Database username
`DB_PASS`	Database password
`DB_NAME`	Database name

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=1s

Default: 1s

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_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

Text shown on login button.

STATEGRAPH_OAUTH_DISPLAY_NAME="Sign in with Google"

Default: Login

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: System-dependent

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_DISPLAY_NAME="Sign in with Google"

# 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_DISPLAY_NAME="Sign in with SSO"

# Logging
STATEGRAPH_ACCESS_LOG=/dev/stdout

Variable Reference Table

Variable	Required	Default	Description
`STATEGRAPH_UI_BASE`	Yes	-	Public URL
`DB_HOST`	Yes	-	PostgreSQL host
`DB_USER`	Yes	-	Database user
`DB_PASS`	Yes	-	Database password
`DB_NAME`	Yes	-	Database name
`DB_PORT`	No	`5432`	Database port
`DB_CONNECT_TIMEOUT`	No	`120`	Connection timeout
`DB_MAX_POOL_SIZE`	No	`100`	Max connections
`DB_IDLE_TX_TIMEOUT`	No	`180s`	Idle transaction timeout
`STATEGRAPH_PORT`	No	`8180`	Internal server port
`STATEGRAPH_DB_STATEMENT_TIMEOUT`	No	`1s`	Query timeout
`STATEGRAPH_ACCESS_LOG`	No	`off`	Access logging
`STATEGRAPH_CLIENT_MAX_BODY_SIZE`	No	`512m`	Max request size
`DISABLE_IPV6`	No	`0`	Disable IPv6
`STATEGRAPH_ENABLE_CORS`	No	`false`	Enable CORS
`STATEGRAPH_CORS_DEFAULT_ORIGIN`	No	`http://localhost:3000`	CORS origin
`STATEGRAPH_OAUTH_TYPE`	No	-	OAuth provider
`STATEGRAPH_OAUTH_CLIENT_ID`	If OAuth	-	OAuth client ID
`STATEGRAPH_OAUTH_CLIENT_SECRET`	If OAuth	-	OAuth client secret
`STATEGRAPH_OAUTH_EMAIL_DOMAIN`	No	`*`	Email domain filter
`STATEGRAPH_OAUTH_DISPLAY_NAME`	No	`Login`	Login button text
`STATEGRAPH_OAUTH_REDIRECT_BASE`	No	`http://localhost:{port}`	OAuth callback base (set in production!)
`STATEGRAPH_OAUTH_OIDC_ISSUER_URL`	If OIDC	-	OIDC issuer URL
`STATEGRAPH_OAUTH_GOOGLE_GROUP`	No	-	Google Group email
`STATEGRAPH_OAUTH_GOOGLE_ADMIN_EMAIL`	If Group	-	Admin email
`STATEGRAPH_OAUTH_GOOGLE_SERVICE_ACCOUNT_JSON`	If Group	-	Service account JSON