Vulcan Environment Variables

This document lists all environment variables that can be used to configure Vulcan.

System Configuration

Variable	Description	Default	Example
`VULCAN_CONFIG`	Override path to vulcan.yml config file	`config/vulcan.yml`	`/etc/vulcan/config.yml`
`VULCAN_ENV`	Override Rails environment	Uses `RAILS_ENV`	`production`

Database Configuration

Variable	Description	Default	Example
`DATABASE_URL`	PostgreSQL connection string (12-factor, takes precedence)	-	`postgres://user:pass@localhost:5432/vulcan_production`
`DATABASE_PORT`	PostgreSQL client connection port (used by database.yml)	`5432`	`5435`
`DATABASE_HOST`	PostgreSQL host (used by database.yml)	`127.0.0.1`	`localhost`
`DATABASE_GSSENCMODE`	GSSAPI encryption mode (set to `disable` on macOS with Kerberos)	`prefer`	`disable`
`DATABASE_NAME`	Override database name (dev + production only; test is hardcoded)	`vulcan_development` / `vulcan_production`	`vulcan_staging`
`POSTGRES_PORT`	Docker host-side port mapping (should match DATABASE_PORT)	`5432`	`5435`
`POSTGRES_USER`	PostgreSQL username (Docker init + database.yml)	`postgres`	`vulcan_user`
`POSTGRES_PASSWORD`	PostgreSQL password (Docker init + database.yml)	`postgres`	`secure_password`
`POSTGRES_DB`	PostgreSQL database name (Docker container init only, not used by database.yml)	`vulcan_production`	`vulcan_prod`
`PORT`	Application server (Puma) listen port	`3000`	`3001`

Note: DATABASE_URL takes precedence when set (recommended for Heroku, Kubernetes). Individual variables (POSTGRES_USER, POSTGRES_PASSWORD, etc.) are used as fallback.

Deprecated: VULCAN_VUE_DATABASE_PASSWORD and DB_SUFFIX are removed. Use POSTGRES_PASSWORD and DATABASE_NAME respectively. POSTGRES_DB is no longer read by database.yml — use DATABASE_NAME for all environments. Test database name (vulcan_test) is hardcoded to prevent collision with development.

Multi-Project Development: See the port registry for recommended port assignments when running multiple projects simultaneously.

General Application Settings

Variable	Description	Default	Example
`VULCAN_APP_URL`	Application URL (for mailer links)	— (must be set for emails)	`https://vulcan.example.com`
`VULCAN_WELCOME_TEXT`	Extra welcome text under the sign-in page heading	— (unset; the page carries its own heading)	`Welcome to MITRE Vulcan`
`VULCAN_CONTACT_EMAIL`	Contact email for notifications and default SMTP username	— (unset)	`support@mycompany.com`
`VULCAN_DOCS_REQUIRE_LOGIN`	Require a signed-in user to read the in-app documentation site at `/docs`	`false` (public)	`true`

Authentication Settings

Variable	Description	Default	Example
`VULCAN_ENABLE_LOCAL_LOGIN`	Enable local username/password login	`true`	`true` or `false`
`VULCAN_ENABLE_EMAIL_CONFIRMATION`	Require email confirmation for new users	`false`	`true` or `false`
`VULCAN_SESSION_TIMEOUT`	Session inactivity timeout. Accepts explicit suffix (`30s`, `15m`, `1h`) or plain numbers (1-9 = hours, 10-299 = minutes, 300+ = seconds).	`600` (10 minutes)	`900` (DoD 15-min), `15m`, `1h`
`VULCAN_ENABLE_REMEMBER_ME`	Show "Remember Me" checkbox on login forms	`true`	`false` for DoD
`VULCAN_REMEMBER_ME_DURATION`	How long Remember Me keeps session alive. Same format as session timeout.	`8h`	`1d`, `28800`

Account Linking

Variable	Description	Default	Example
`VULCAN_AUTO_LINK_USER`	Automatically link external identities (OIDC, LDAP, GitHub) to existing local accounts with the same email. Only enable when all configured identity providers verify email ownership (e.g., enterprise Okta, corporate LDAP). When `false`, users see a clear error directing them to sign in with their existing method or contact an administrator.	`false`	`true` or `false`

User Registration

Variable	Description	Default	Example
`VULCAN_ENABLE_USER_REGISTRATION`	Allow new users to register	`true`	`true` or `false`

Admin Bootstrap

Vulcan provides multiple ways to create the initial admin user. These are evaluated in priority order:

Variable	Description	Default	Example
`VULCAN_ADMIN_EMAIL`	Email for auto-created admin user	-	`admin@example.com`
`VULCAN_ADMIN_PASSWORD`	Password for auto-created admin user	Auto-generated	`SecurePass123!`
`VULCAN_FIRST_USER_ADMIN`	First registered user becomes admin	`true`	`true` or `false`

Priority Order:

Environment Variables (Most Secure): Set VULCAN_ADMIN_EMAIL and optionally VULCAN_ADMIN_PASSWORD
- Admin is created automatically during db:prepare
- If password is omitted, a secure random password is generated and logged
- Best for: Production, CI/CD, Kubernetes
First User Admin (Convenience): Set VULCAN_FIRST_USER_ADMIN=true
- First user to register or login becomes admin automatically
- Protected by database advisory lock to prevent race conditions
- Best for: Quick demos, development, evaluations
Manual Rake Task: Run rails db:create_admin
- Interactive terminal prompt
- Best for: Traditional deployments, manual setup

Default: VULCAN_FIRST_USER_ADMIN=true in all environments (set to false in production to require explicit admin creation), allowing immediate use after docker compose up. For production, disable this and use VULCAN_ADMIN_EMAIL.

Security Note: The first-user-admin feature uses PostgreSQL advisory locks to prevent race condition attacks (similar to WordPress installer vulnerabilities). However, for production deployments, explicit admin configuration via environment variables is recommended.

Demo/Evaluation Data

Variable	Description	Default	Example
`VULCAN_SEED_DEMO_DATA`	Populate database with demo data in production	`false`	`true`

When VULCAN_SEED_DEMO_DATA=true, db:seed creates sample users, projects, and components for evaluation purposes. In development/test environments, demo data is always seeded.

If no admin user exists (i.e., VULCAN_ADMIN_EMAIL was not set), a fallback demo admin is created:

Email: admin@example.com
Password: 12qwaszx\!@QWASZX (DoD 2222/15 compliant)

If an admin already exists from admin:bootstrap, the demo admin is skipped and only sample projects/users are created.

OIDC/OAuth (e.g., Okta, Auth0, Keycloak)

New in v2.2+: Vulcan supports automatic endpoint discovery, reducing configuration from 8+ variables to just 4 essential ones.

Essential Configuration (Auto-Discovery Enabled)

Variable	Description	Required	Example
`VULCAN_ENABLE_OIDC`	Enable OIDC authentication	✅	`true`
`VULCAN_OIDC_ISSUER_URL`	OIDC issuer URL	✅	`https://dev-12345.okta.com`
`VULCAN_OIDC_CLIENT_ID`	OIDC client ID	✅	`0oa1b2c3d4e5f6g7h8i9j`
`VULCAN_OIDC_CLIENT_SECRET`	OIDC client secret	✅	`secret_key_here`
`VULCAN_OIDC_REDIRECT_URI`	OIDC redirect URI	✅	`https://vulcan.example.com/users/auth/oidc/callback`

Provider registration: register TWO URIs in your identity provider's app — the sign-in callback above, AND the sign-out landing <app_url>/users/signed_out (built from VULCAN_APP_URL). Without the sign-out entry, providers reject Vulcan's logout with 400 invalid_request. See the Okta/OIDC setup guide for the full settings tables.

Multiple OIDC Providers (Registry — v2.3+)

To offer several OIDC providers simultaneously (e.g. Okta and login.gov on one login page), set a registry and give each provider its own variable family. Step-by-step provider guides: Okta/OIDC and Login.gov (PIV/CAC) — the Login.gov guide covers keypair generation, sandbox portal registration, and end-to-end testing.

Variable	Description	Example
`VULCAN_OIDC_PROVIDERS`	Comma-separated registry of provider keys (lowercase snake_case). Each key becomes the strategy name, the `/users/auth/<key>/callback` path, and the stored provider value.	`okta,login_gov`

Every variable in the single-provider tables above has a per-provider formVULCAN_OIDC_<KEY>_<FIELD> — e.g. for okta,login_gov:

VULCAN_OIDC_OKTA_ISSUER_URL=https://org.okta.com/oauth2/default
VULCAN_OIDC_OKTA_CLIENT_ID=...
VULCAN_OIDC_OKTA_CLIENT_SECRET=...
VULCAN_OIDC_OKTA_TITLE=Okta

VULCAN_OIDC_LOGIN_GOV_ISSUER_URL=https://idp.int.identitysandbox.gov/   # trailing slash REQUIRED (issuer-mismatch otherwise)
VULCAN_OIDC_LOGIN_GOV_CLIENT_ID=urn:gov:gsa:openidconnect:...
VULCAN_OIDC_LOGIN_GOV_CLIENT_AUTH_METHOD=jwt_bearer        # login.gov: private_key_jwt
VULCAN_OIDC_LOGIN_GOV_PRIVATE_KEY_PATH=/path/to/key.pem    # or _PRIVATE_KEY (inline PEM)
VULCAN_OIDC_LOGIN_GOV_ACR_VALUES=urn:acr.login.gov:auth-only
VULCAN_OIDC_LOGIN_GOV_TITLE=login.gov

VULCAN_OIDC_<KEY>_CLIENT_AUTH_METHOD accepts secret (default) or jwt_bearer (login.gov's private_key_jwt). jwt_bearer requires _PRIVATE_KEY (inline PEM) or _PRIVATE_KEY_PATH.
Backward compatible: when VULCAN_OIDC_PROVIDERS is unset, the unprefixed VULCAN_OIDC_* variables above define a single provider named oidc — existing deployments need no change.

Optional Configuration

Variable	Description	Default	Example
`VULCAN_OIDC_DISCOVERY`	Enable automatic endpoint discovery	`true`	`false` (to disable)
`VULCAN_OIDC_PROVIDER_TITLE`	Display name for the legacy single OIDC provider	`OIDC Provider`	`Okta`
`VULCAN_OIDC_PROMPT`	OIDC prompt parameter	-	`login` (forces re-authentication)
`VULCAN_OIDC_CLIENT_SIGNING_ALG`	OIDC signing algorithm	`RS256`	`RS256`

Manual Configuration (Legacy/Fallback)

Only required when VULCAN_OIDC_DISCOVERY=false or as fallback endpoints

Variable	Description	Example
`VULCAN_OIDC_AUTHORIZATION_URL`	OIDC authorization endpoint	`https://dev-12345.okta.com/oauth2/default/v1/authorize`
`VULCAN_OIDC_TOKEN_URL`	OIDC token endpoint	`https://dev-12345.okta.com/oauth2/default/v1/token`
`VULCAN_OIDC_USERINFO_URL`	OIDC userinfo endpoint	`https://dev-12345.okta.com/oauth2/default/v1/userinfo`
`VULCAN_OIDC_JWKS_URI`	OIDC JWKS endpoint	`https://dev-12345.okta.com/oauth2/default/v1/keys`

Deprecated Variables

With auto-discovery enabled, these are usually not needed. They are still read by the YAML config as fallback/override values for non-discovery setups.

Variable	Description	Default
`VULCAN_OIDC_HOST`	OIDC provider hostname (fallback when discovery disabled)	—
`VULCAN_OIDC_PORT`	OIDC provider port	`443`
`VULCAN_OIDC_SCHEME`	OIDC provider scheme	`https`

Migration Examples

Before (8+ variables):

bash

VULCAN_ENABLE_OIDC=true
VULCAN_OIDC_ISSUER_URL=https://dev-12345.okta.com
VULCAN_OIDC_CLIENT_ID=your-client-id
VULCAN_OIDC_CLIENT_SECRET=your-secret
VULCAN_OIDC_REDIRECT_URI=https://vulcan.example.com/users/auth/oidc/callback
VULCAN_OIDC_AUTHORIZATION_URL=https://dev-12345.okta.com/oauth2/default/v1/authorize
VULCAN_OIDC_TOKEN_URL=https://dev-12345.okta.com/oauth2/default/v1/token
VULCAN_OIDC_USERINFO_URL=https://dev-12345.okta.com/oauth2/default/v1/userinfo
VULCAN_OIDC_JWKS_URI=https://dev-12345.okta.com/oauth2/default/v1/keys

After (4 variables):

bash

VULCAN_ENABLE_OIDC=true
VULCAN_OIDC_ISSUER_URL=https://dev-12345.okta.com
VULCAN_OIDC_CLIENT_ID=your-client-id
VULCAN_OIDC_CLIENT_SECRET=your-secret
VULCAN_OIDC_REDIRECT_URI=https://vulcan.example.com/users/auth/oidc/callback
# Endpoints automatically discovered from /.well-known/openid-configuration

LDAP

Variable	Description	Default	Example
`VULCAN_ENABLE_LDAP`	Enable LDAP authentication	`false`	`true` or `false`
`VULCAN_LDAP_HOST`	LDAP server hostname	`localhost`	`ldap.example.com`
`VULCAN_LDAP_PORT`	LDAP server port	`389`	`636`
`VULCAN_LDAP_TITLE`	Display name for LDAP	`LDAP`	`Corporate LDAP`
`VULCAN_LDAP_ATTRIBUTE`	LDAP attribute for user lookup	`uid`	`sAMAccountName`
`VULCAN_LDAP_ENCRYPTION`	LDAP encryption method	`plain`	`simple_tls` or `start_tls`
`VULCAN_LDAP_BIND_DN`	LDAP bind DN	-	`cn=admin,dc=example,dc=com`
`VULCAN_LDAP_ADMIN_PASS`	LDAP bind password	-	`ldap_password`
`VULCAN_LDAP_BASE`	LDAP search base	-	`dc=example,dc=com`

Email/SMTP Settings

Variable	Description	Default	Example
`VULCAN_ENABLE_SMTP`	Enable SMTP for sending emails	`false`	`true` or `false`
`VULCAN_SMTP_ADDRESS`	SMTP server address	-	`smtp.gmail.com`
`VULCAN_SMTP_PORT`	SMTP server port	-	`587`
`VULCAN_SMTP_DOMAIN`	SMTP domain	-	`example.com`
`VULCAN_SMTP_SERVER_USERNAME`	SMTP username (defaults to VULCAN_CONTACT_EMAIL if not set)	-	`notifications@example.com`
`VULCAN_SMTP_SERVER_PASSWORD`	SMTP password	-	`smtp_password`
`VULCAN_SMTP_AUTHENTICATION`	SMTP authentication method	-	`plain`
`VULCAN_SMTP_OPENSSL_VERIFY_MODE`	OpenSSL verify mode for SMTP	-	`none`
`VULCAN_SMTP_TLS`	Use TLS for SMTP	-	`true` or `false`
`VULCAN_SMTP_ENABLE_STARTTLS_AUTO`	Enable STARTTLS auto	-	`true` or `false`

API Tokens (Personal Access Tokens)

Personal access tokens enable programmatic API access via Authorization: Token vulcan_xxx header. Tokens are SHA-256 hashed (never stored in plaintext), support scoped permissions (read/write/admin), IP allowlisting, and automatic idle revocation.

Variable	Description	Default	Example
`VULCAN_API_TOKENS_ENABLED`	Enable/disable the PAT feature entirely	`true`	`false`
`VULCAN_API_TOKENS_MAX_PER_USER`	Maximum active tokens per user	`20`	`10`
`VULCAN_API_TOKENS_MAX_LIFETIME_DAYS`	Maximum token lifetime in days	`365`	`90`
`VULCAN_API_TOKENS_AUTO_REVOKE_IDLE_DAYS`	Auto-revoke tokens unused for this many days	`90`	`30`

Maintenance tasks (recommended via cron):

bash

# Revoke idle tokens (unused for configured days)
bundle exec rake api_tokens:revoke_idle

# Revoke expired tokens (past expires_at date)
bundle exec rake api_tokens:revoke_expired

Slack Integration

Variable	Description	Default	Example
`VULCAN_ENABLE_SLACK_COMMS`	Enable Slack notifications	`false`	`true` or `false`
`VULCAN_SLACK_API_TOKEN`	Slack API token	-	`xoxb-your-token`
`VULCAN_SLACK_CHANNEL_ID`	Slack channel ID	-	`C1234567890`

Display a colored banner at the top and bottom of every page, commonly used for DoD classification markings.

Variable	Description	Default	Example
`VULCAN_BANNER_ENABLED`	Enable classification banner	`false`	`true`
`VULCAN_BANNER_TEXT`	Banner text displayed on every page (plain text, no formatting)	`""`	`UNCLASSIFIED`
`VULCAN_BANNER_BACKGROUND_COLOR`	Banner background color (hex)	`#007a33`	`#c8102e`
`VULCAN_BANNER_TEXT_COLOR`	Banner text color (hex)	`#ffffff`	`#000000`

DoD Standard Colors:

Classification	Background	Text
UNCLASSIFIED	`#007a33`	`#ffffff`
CUI	`#502b85`	`#ffffff`
CONFIDENTIAL	`#0033a0`	`#ffffff`
SECRET	`#c8102e`	`#ffffff`
TOP SECRET	`#ff671f`	`#ffffff`
TS/SCI	`#f7ea48`	`#000000`

Terminology

Rename the key entity noun per document kind. STIG components say "Rule" and SRG components say "Requirement" by default; an organization can override either set at deployment (for example, renaming to "Control"). The label form is the abbreviated variant used on buttons and panel tabs. Semi-static like the classification banner — read once per page load, no runtime setting.

Variable	Description	Default	Example
`VULCAN_TERM_STIG_SINGULAR`	Entity noun on STIG surfaces, singular	`Rule`	`Control`
`VULCAN_TERM_STIG_PLURAL`	Entity noun on STIG surfaces, plural	`Rules`	`Controls`
`VULCAN_TERM_STIG_LABEL`	Abbreviated form for STIG buttons/panels	`Rule`	`Ctrl`
`VULCAN_TERM_SRG_SINGULAR`	Entity noun on SRG surfaces, singular	`Requirement`	`Control`
`VULCAN_TERM_SRG_PLURAL`	Entity noun on SRG surfaces, plural	`Requirements`	`Controls`
`VULCAN_TERM_SRG_LABEL`	Abbreviated form for SRG buttons/panels	`Req`	`Ctrl`

Display a blocking consent modal that users must acknowledge before accessing the application. Acknowledgment is tracked server-side in the Rails session with a configurable TTL. Setting TTL to 0 (default) requires consent once per session (AC-8 compliant).

Variable	Description	Default	Example
`VULCAN_CONSENT_ENABLED`	Enable consent modal	`false`	`true`
`VULCAN_CONSENT_VERSION`	Version string for consent (increment to re-prompt)	`1`	`2`
`VULCAN_CONSENT_TITLE`	Modal title	`Terms of Use`	`Acceptable Use Policy`
`VULCAN_CONSENT_CONTENT`	Modal body content (supports Markdown)	`""`	`By using this system you agree to the AUP.`
`VULCAN_CONSENT_TTL`	How long consent acknowledgment remains valid. `0` = per-session (re-prompt on every new session, DoD compliant). Accepts durations: `1h`, `30m`, `24h`.	`0`	`24h`

Consent Content Formatting: The VULCAN_CONSENT_CONTENT variable supports full Markdown formatting including headings, bold, italics, numbered/bulleted lists, links, and blockquotes. HTML is sanitized for security. The banner text (VULCAN_BANNER_TEXT) is plain text only — no formatting is applied.

Account Lockout

Lock accounts after consecutive failed login attempts. Enabled by default.

Variable	Description	Default	Example
`VULCAN_LOCKOUT_ENABLED`	Enable account lockout	`true`	`false`
`VULCAN_LOCKOUT_MAX_ATTEMPTS`	Failed attempts before lock	`3`	`5`
`VULCAN_LOCKOUT_UNLOCK_IN_MINUTES`	Minutes before auto-unlock	`15`	`30`
`VULCAN_LOCKOUT_UNLOCK_STRATEGY`	Unlock method: `email`, `time`, or `both`	`both`	`time`
`VULCAN_LOCKOUT_LAST_ATTEMPT_WARNING`	Warn user on last attempt before lock	`true`	`false`

Unlock strategies:

email — sends an unlock link to the user's email (requires SMTP)
time — automatically unlocks after VULCAN_LOCKOUT_UNLOCK_IN_MINUTES
both — either method works (recommended, ensures unlock even without SMTP)

Administrators can also manually unlock accounts from the Users page (/users).

Session Limits

Per-user concurrent session limits (AC-10).

Variable	Description	Default	Example
`VULCAN_SESSION_LIMITS_ENABLED`	Enable per-user session limits	`true`	`false`
`VULCAN_MAX_CONCURRENT_SESSIONS`	Maximum concurrent sessions per user	`1`	`3`

Password Policy

DoD-aligned defaults ("2222" policy). Set any count to 0 to disable that requirement.

Variable	Description	Default	Example
`VULCAN_PASSWORD_MIN_LENGTH`	Minimum password length	`15`	`8`
`VULCAN_PASSWORD_MIN_UPPERCASE`	Minimum uppercase letters	`2`	`0`
`VULCAN_PASSWORD_MIN_LOWERCASE`	Minimum lowercase letters	`2`	`0`
`VULCAN_PASSWORD_MIN_NUMBER`	Minimum digits	`2`	`0`
`VULCAN_PASSWORD_MIN_SPECIAL`	Minimum special characters	`2`	`0`

Input Length Limits

Configurable maximum lengths for text fields. Defaults are based on analysis of real DISA STIG/SRG data across 1,785 rules. Group limits by category rather than individual fields — each env var controls a category of related fields.

See input length limits for the complete field-to-setting mapping.

Variable	Description	Default	Example
`VULCAN_LIMIT_SHORT_STRING`	IDs, version strings, reference fields	`255`	`512`
`VULCAN_LIMIT_IDENT`	Comma-joined CCI list (real max: 310)	`2048`	`4096`
`VULCAN_LIMIT_TITLE`	Rule titles (real max: 436)	`500`	`1000`
`VULCAN_LIMIT_MEDIUM_TEXT`	Status justification, brief text	`1000`	`2000`
`VULCAN_LIMIT_LONG_TEXT`	Descriptions, check content, fixtext (real max: 6,330)	`10000`	`20000`
`VULCAN_LIMIT_INSPEC_CODE`	InSpec control bodies (user-authored)	`50000`	`100000`
`VULCAN_LIMIT_COMPONENT_NAME`	Component name	`255`	`500`
`VULCAN_LIMIT_COMPONENT_PREFIX`	STIG ID prefix	`10`	`15`
`VULCAN_LIMIT_COMPONENT_TITLE`	Component title	`500`	`1000`
`VULCAN_LIMIT_COMPONENT_DESCRIPTION`	Component description	`5000`	`10000`
`VULCAN_LIMIT_PROJECT_NAME`	Project name	`255`	`500`
`VULCAN_LIMIT_PROJECT_DESCRIPTION`	Project description	`5000`	`10000`
`VULCAN_LIMIT_USER_NAME`	User display name	`255`	`500`
`VULCAN_LIMIT_USER_EMAIL`	User email address	`255`	`500`
`VULCAN_LIMIT_REVIEW_COMMENT`	Review comments	`10000`	`20000`
`VULCAN_LIMIT_BENCHMARK_NAME`	SRG/STIG display name	`500`	`1000`
`VULCAN_LIMIT_BENCHMARK_TITLE`	SRG/STIG title	`500`	`1000`
`VULCAN_LIMIT_BENCHMARK_DESCRIPTION`	STIG description	`10000`	`20000`
`VULCAN_IMPORT_JSON_ARCHIVE_SIZE_BUDGET_MB`	Maximum total uncompressed size (MB) of all entries in a json_archive zip upload — the zip-bomb guard behind the 100 MB upload cap	`500`	`1000`

Project Settings

Variable	Description	Default	Example
`VULCAN_PROJECT_CREATE_PERMISSION_ENABLED`	Require permission to create projects	`true`	`true` or `false`

Development Environment

For local development, create a .env file in the project root with your settings:

bash

# Database (see docs/site/development/port-registry.md for multi-project ports)
DATABASE_PORT=5435
POSTGRES_PORT=5435
DATABASE_HOST=127.0.0.1
DATABASE_GSSENCMODE=disable

# Enable OIDC (example for Okta)
VULCAN_ENABLE_OIDC=true
VULCAN_OIDC_PROVIDER_TITLE=Okta
VULCAN_OIDC_ISSUER_URL=https://dev-12345.okta.com
VULCAN_OIDC_HOST=dev-12345.okta.com
VULCAN_OIDC_CLIENT_ID=your_client_id
VULCAN_OIDC_CLIENT_SECRET=your_client_secret

# Disable local login when using OIDC
VULCAN_ENABLE_LOCAL_LOGIN=false

Production Environment

In production, set these as actual environment variables through your deployment platform (Docker, Kubernetes, etc.) rather than using .env files.

Docker Deployment

When using Docker, you can set environment variables in:

.env file (created by setup-docker-secrets.sh)
docker-compose.yml using the environment: section
Container runtime with -e flags

For Container Deployments (Docker, ECS, Kubernetes):

yaml

# docker-compose.yml
environment:
  RAILS_LOG_TO_STDOUT: "true"
  STRUCTURED_LOGGING: "true"  # Enable JSON logging for CloudWatch/monitoring
  # Other environment variables...

AWS ECS Example:

json

{
  "environment": [
    {"name": "RAILS_LOG_TO_STDOUT", "value": "true"},
    {"name": "STRUCTURED_LOGGING", "value": "true"}
  ]
}

This ensures OIDC auto-discovery events and all application logs are visible in your container orchestration platform's logging system.

Rails/Framework Settings

Variable	Description	Default	Example
`RAILS_MASTER_KEY`	Rails master key for credentials	-	Generated by Rails
`RAILS_LOG_TO_STDOUT`	Log to stdout instead of files	-	`true`
`RAILS_SERVE_STATIC_FILES`	Serve static files in production	-	`true`
`RAILS_FORCE_SSL`	Force HTTPS redirects (set to `false` for Docker without SSL termination)	`true`	`false`
`RAILS_MAX_THREADS`	Database connection pool size per process	`5`	`10`
`RAILS_LOG_LEVEL`	Production log verbosity	`info`	`debug`

Container Logging (Production)

Variable	Description	Default	Example
`RAILS_LOG_TO_STDOUT`	Enable container-friendly logging	`false`	`true`
`STRUCTURED_LOGGING`	Enable JSON structured logging for CloudWatch/monitoring	`false`	`true`
`DOCKER_CONTAINER`	Indicates running in Docker container (auto-detected)	-	`true`
`ECS_CONTAINER_METADATA_URI`	AWS ECS metadata URI (auto-detected)	-	Auto-set by ECS

Container Logging Features:

Automatic Detection: Vulcan automatically detects container environments (Docker, ECS, Kubernetes)
JSON Logging: When STRUCTURED_LOGGING=true, logs are output in JSON format for easy parsing by CloudWatch, Splunk, etc.
OIDC Discovery Visibility: All OIDC auto-discovery events are logged with detailed context for production debugging
Request Tracking: Includes request IDs in structured logs when available

GitHub OAuth (Optional)

Variable	Description	Default	Example
`GITHUB_APP_ID`	GitHub OAuth app ID	-	`your_github_app_id`
`GITHUB_APP_SECRET`	GitHub OAuth app secret	-	`your_github_app_secret`

Notes

Boolean values: Use true or false (case-insensitive)
All boolean environment variables default to false unless otherwise specified
Variables marked with - in the Default column are required when the feature is enabled
Sensitive values (passwords, secrets) should never be committed to version control

Vulcan Environment Variables ​

System Configuration ​

Database Configuration ​

General Application Settings ​

Authentication Settings ​

Local Login ​

Account Linking ​

User Registration ​

Admin Bootstrap ​

Demo/Evaluation Data ​

OIDC/OAuth (e.g., Okta, Auth0, Keycloak) ​

Essential Configuration (Auto-Discovery Enabled) ​

Multiple OIDC Providers (Registry — v2.3+) ​

Optional Configuration ​

Manual Configuration (Legacy/Fallback) ​

Deprecated Variables ​

Migration Examples ​

LDAP ​

Email/SMTP Settings ​

API Tokens (Personal Access Tokens) ​

Slack Integration ​

Classification Banner ​

Terminology ​

Consent / Terms of Use Modal ​

Account Lockout ​

Session Limits ​

Password Policy ​

Input Length Limits ​

Project Settings ​

Development Environment ​

Production Environment ​

Docker Deployment ​

Rails/Framework Settings ​

Container Logging (Production) ​

GitHub OAuth (Optional) ​

Notes ​

Vulcan Environment Variables

System Configuration

Database Configuration

General Application Settings

Authentication Settings

Local Login

Account Linking

User Registration

Admin Bootstrap

Demo/Evaluation Data

OIDC/OAuth (e.g., Okta, Auth0, Keycloak)

Essential Configuration (Auto-Discovery Enabled)

Multiple OIDC Providers (Registry — v2.3+)

Optional Configuration

Manual Configuration (Legacy/Fallback)

Deprecated Variables

Migration Examples

LDAP

Email/SMTP Settings

API Tokens (Personal Access Tokens)

Slack Integration

Classification Banner

Terminology

Consent / Terms of Use Modal

Account Lockout

Session Limits

Password Policy

Input Length Limits

Project Settings

Development Environment

Production Environment

Docker Deployment

Rails/Framework Settings

Container Logging (Production)

GitHub OAuth (Optional)

Notes