data-formulator/.env.template

# Data Formulator Configuration
# Copy this file to .env and fill in your values.
#   cp .env.template .env

# -------------------------------------------------------------------
# Server settings
# -------------------------------------------------------------------
# You can also override these via CLI flags (run `data_formulator --help`).

DISABLE_DISPLAY_KEYS=false # if true, API keys will not be shown in the frontend
SANDBOX=local              # code execution backend: 'local' (default) or 'docker'
# LOG_LEVEL=INFO           # logging level for data_formulator modules (DEBUG, INFO, WARNING, ERROR)

# --- Feature gates ---
# Enable administrator-managed resources and the Administration navigation page.
# Default: off. Authentication, storage, and sandbox are configured independently.
# DF_MANAGED=false
# Hosted administrators must have verified identities; anonymous IDs are not accepted.
# DF_ADMIN_IDENTITIES=user:<verified-admin-subject>
# Fresh managed installs default to configured resources only; admins may relax this.
# The flags below enforce restrictions even when managed mode is off.
# Allow configured data connectors only; block user-created connections.
# DISABLE_DATA_CONNECTORS=false

# Prevent users from adding custom LLM endpoints; configured models remain available.
# DISABLE_CUSTOM_MODELS=false

# Flask session secret key — used to sign cookies and encrypt session data.
# Required for SSO and plugin auth (Superset, etc.). Generate one with:
#   python -c "import secrets; print(secrets.token_hex(32))"
#
# IMPORTANT for production / migration:
#   If not set, a random key is generated on each restart — all user sessions
#   (SSO logins, plugin tokens) will be invalidated, and Agent code signatures
#   will fail verification. When migrating servers, copy this value to the new
#   .env to preserve sessions. See DEVELOPMENT.md "Server Migration Checklist".
# FLASK_SECRET_KEY=

# Kusto delegated Microsoft sign-in (Authorization Code + PKCE).
# Register a public-client Entra application for your deployment. Client and
# tenant IDs are public identifiers, but they are deployment-specific and
# should not be copied from another organization. No client secret is needed.
# KUSTO_OAUTH_CLIENT_ID=<application-client-id>
# KUSTO_OAUTH_TENANT_ID=<tenant-id-or-organizations>
# KUSTO_OAUTH_REDIRECT_URI=http://localhost:5567/api/auth/kusto/callback

# Data directory — where workspaces and user data are stored on disk.
# Useful for server deployments with large datasets or dedicated storage volumes.
# Resolution order: --data-dir CLI flag > DATA_FORMULATOR_HOME env var > ~/.data_formulator
# Directory structure:
#   DATA_FORMULATOR_HOME/
#   ├── users/<id>/workspaces/   (per-user workspace data: parquet, metadata)
#   ├── workspaces/              (legacy default workspace root)
#   └── cache/                   (local cache, only for azure_blob backend)
# DATA_FORMULATOR_HOME=

# -------------------------------------------------------------------
# LLM provider API keys
# -------------------------------------------------------------------
# A provider is enabled when {PROVIDER}_MODELS is set together with
# {PROVIDER}_API_KEY and/or {PROVIDER}_API_BASE. Uncomment and fill in the
# providers you want to use.
# For details see: https://docs.litellm.ai/docs#litellm-python-sdk

# OpenAI
# OPENAI_API_KEY=<your-openai-api-key>
# OPENAI_MODELS=gpt-5.5 # comma separated list of models

# Azure OpenAI
# AZURE_API_KEY=<your-azure-openai-api-key>
# AZURE_API_BASE=https://your-azure-openai-endpoint.openai.azure.com/
# AZURE_MODELS=gpt-5.4

# Anthropic
# ANTHROPIC_API_KEY=<your-anthropic-api-key>
# ANTHROPIC_MODELS=claude-sonnet-4-20250514

# Ollama
# OLLAMA_API_BASE=http://localhost:11434
# OLLAMA_MODELS=qwen3:32b # models with good code generation capabilities recommended

# OrcaRouter (third-party OpenAI-compatible API service)
# See: https://www.orcarouter.ai
# ORCAROUTER_API_KEY=<your-orcarouter-api-key>
# ORCAROUTER_API_BASE=https://api.orcarouter.ai/v1
# ORCAROUTER_MODELS=auto # comma separated list of models; use e.g. "auto" or "openai/gpt-4.1-mini"

# Cheaper Inference (third-party OpenAI-compatible API service)
# Model ids are bare, e.g. "gpt-5.4-mini".
# See: https://cheaperinference.com/docs
# CHEAPERINFERENCE_API_KEY=<your-cheaperinference-api-key>
# CHEAPERINFERENCE_API_BASE=https://api.cheaperinference.com/v1
# CHEAPERINFERENCE_MODELS=gpt-5.4-mini # comma separated list of models; use e.g. "gpt-5.4-mini" or "claude-sonnet-5"

# Add other LiteLLM-supported providers with PROVIDER_API_KEY, PROVIDER_MODELS, etc.
# (optionally PROVIDER_API_BASE and PROVIDER_ENDPOINT, which defaults to openai).

# -------------------------------------------------------------------
# API base URL allowlist (SSRF protection)
# -------------------------------------------------------------------
# When users add custom models via the UI, they can provide an arbitrary
# api_base URL.  To prevent the server from being used as an SSRF proxy,
# set a comma-separated list of allowed URL glob patterns.
#
# Open mode (default): leave unset to allow all URLs (convenient for local dev).
# Enforce mode: set to restrict which endpoints users can target.
#
# Glob patterns use fnmatch syntax (* matches anything, case-insensitive).
# Empty api_base (provider defaults like OpenAI/Anthropic) is always allowed,
# except for third-party gateways (OpenRouter, OrcaRouter, Cheaper Inference),
# whose default base URL must match a pattern.
# Global models (configured above via env vars) bypass this check.
#
# Examples:
#   DF_ALLOWED_API_BASES=https://api.openai.com*,https://*.openai.azure.com/*
#   DF_ALLOWED_API_BASES=https://api.openai.com*,https://*.openai.azure.com/*,http://localhost:11434/*
# DF_ALLOWED_API_BASES=

# -------------------------------------------------------------------
# Authentication (SSO / OAuth2)
# -------------------------------------------------------------------
# Single-select: only one provider can be active at a time.
# Leave unset for anonymous mode (default, no login required).
#
# AUTH_PROVIDER values:
#   oidc   — OIDC-compliant IdP (discovers via /.well-known/openid-configuration)
#            Use this for Keycloak, Auth0, Okta, Authelia, etc.
#   oauth2 — Plain OAuth2 server (discovers via /.well-known/oauth-authorization-server)
#            Use this for custom SSO servers that only expose the RFC 8414 endpoint.
#   github         — GitHub OAuth2
#   azure_easyauth — Azure App Service built-in auth (platform headers)
#
# NOTE: If the primary discovery URL fails, the system automatically tries the
#       other discovery path as a fallback, so either value usually works.
#
# --- OIDC / OAuth2 ---
# AUTH_PROVIDER=oidc
# OIDC_ISSUER_URL=https://your-idp.example.com/realms/main
# OIDC_CLIENT_ID=your-client-id
#
# Auto-discovery (recommended):
#   Only the three variables above are needed. The backend fetches all endpoint
#   URLs from the discovery document and passes them to the frontend.
#
# Manual endpoints (fallback when discovery is not available):
#   When your IdP does NOT expose a discovery document, set the endpoint URLs
#   explicitly. Manual values always take precedence over discovery.
#
# OIDC_AUTHORIZE_URL=https://your-idp.example.com/oauth2/authorize
# OIDC_TOKEN_URL=https://your-idp.example.com/oauth2/token
# OIDC_USERINFO_URL=https://your-idp.example.com/oauth2/userinfo
# OIDC_JWKS_URL=https://your-idp.example.com/oauth2/jwks
#
# If your IdP has no JWKS endpoint, leave OIDC_JWKS_URL unset — the backend
# will validate tokens by calling the UserInfo endpoint instead.
#
# OAuth2 scopes to request (optional — auto-selected if unset):
# OIDC_SCOPES=openid profile email
#
# SSL verification (set to false for self-signed certificates):
# OIDC_VERIFY_SSL=true
#
# Client secret — setting this automatically enables backend (Confidential
# Client) mode. The server handles the full OAuth2 code exchange; the
# browser never sees client_secret or raw tokens — only a session cookie.
#
# When OIDC_CLIENT_SECRET is NOT set, the frontend handles the exchange
# using PKCE (Public Client) — no secret needed.
#
# IMPORTANT — HTTPS requirement:
#   Frontend (PKCE) mode requires a Secure Context in the browser, which
#   means the page MUST be served over HTTPS (or accessed via localhost).
#   Plain HTTP deployments will fail with a crypto.subtle error.
#   Backend mode does NOT have this limitation — it works over HTTP too.
#   If you cannot set up HTTPS, use a confidential client with a secret.
#
# Redirect URI to register in your IdP (same for both modes):
#   http(s)://<your-df-host>/auth/callback
#
# OIDC_CLIENT_SECRET=
#
# Override auto-detection (rarely needed):
# AUTH_MODE=frontend  # force Public Client even if secret is set
# AUTH_MODE=backend   # force Confidential Client even if secret is absent
#
# Endpoint auto-discovery works in BOTH modes. If the IdP exposes
# .well-known/openid-configuration, you do NOT need to set the
# OIDC_*_URL variables — they are discovered automatically.
#
# --- GitHub OAuth2 ---
# AUTH_PROVIDER=github
# GITHUB_CLIENT_ID=your-github-app-client-id
# GITHUB_CLIENT_SECRET=your-github-app-client-secret
#
# Create a GitHub OAuth App at https://github.com/settings/developers
# Set the callback URL to: http(s)://<your-df-host>/api/auth/github/callback
#
# --- Azure App Service EasyAuth ---
# AUTH_PROVIDER=azure_easyauth
# (No extra variables needed — Azure injects identity via platform headers)
#
# --- Common options (all providers) ---
# ALLOW_ANONYMOUS=true          # allow unauthenticated access as fallback (default: true)
# AUTH_DISPLAY_NAME=SSO Login   # label shown on the login button

# -------------------------------------------------------------------
# Workspace storage backend
# -------------------------------------------------------------------
# Controls where workspace data (tables, sessions, metadata) is persisted.
# Also configurable via CLI: --workspace-backend
#
# Choices:
#   local      — (default) durable storage under DATA_FORMULATOR_HOME; no TTL cleanup
#   azure_blob — stores data in Azure Blob Storage (see below)
#   ephemeral  — temporary server-local storage with TTL and LRU cleanup
#
# WORKSPACE_BACKEND=local
#
# Ephemeral-only retention settings (ignored by local and azure_blob):
# EPHEMERAL_WORKSPACE_TTL_HOURS=24
# EPHEMERAL_WORKSPACE_MAX_BYTES=10737418240
# EPHEMERAL_WORKSPACE_CLEANUP_INTERVAL_SECONDS=1800
# EPHEMERAL_WORKSPACE_ROOT=~/.data_formulator/ephemeral

# -------------------------------------------------------------------
# Azure Blob Storage settings (only when WORKSPACE_BACKEND=azure_blob)
# -------------------------------------------------------------------
# Authentication — choose ONE of the following:
#   Option A: Connection string (shared key / SAS)
#     AZURE_BLOB_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
#   Option B: Entra ID (Managed Identity / az login / workload identity)
#     AZURE_BLOB_ACCOUNT_URL=https://<account>.blob.core.windows.net
#
# Blob container name (default: data-formulator):
#   AZURE_BLOB_CONTAINER=data-formulator
#
# CLI equivalents:
#   --azure-blob-connection-string, --azure-blob-account-url, --azure-blob-container
#
# AZURE_BLOB_CONNECTION_STRING=
# AZURE_BLOB_ACCOUNT_URL=
# AZURE_BLOB_CONTAINER=data-formulator

# -------------------------------------------------------------------
# Data source plugins
# -------------------------------------------------------------------
# Plugins are activated by setting their required env vars.
# Each plugin uses a PLG_<PLUGIN>_ prefix.
#
# --- Apache Superset ---
# PLG_SUPERSET_URL=http://superset.example.com:8088
#
# SSO login URL (optional):
#   By default DF opens {PLG_SUPERSET_URL}/df-sso-bridge/ as the SSO popup.
#   Override this if your Superset requires going through the login page first:
#   PLG_SUPERSET_SSO_LOGIN_URL=http://superset.example.com:8088/login/?next=/df-sso-bridge/
#
# Superset-side setup:
#   The Superset instance needs a small bridge endpoint at /df-sso-bridge/
#   that converts a Superset session into a JWT and posts it back to DF.
#   See: superset-sso-bridge-setup.md

# -------------------------------------------------------------------
# Deployment profiles (quick-start presets)
# -------------------------------------------------------------------
# See DEVELOPMENT.md "Deployment Profiles" for full documentation.
#
# Profile 1 — Single-user local (default, no changes needed):
#   Just run: data_formulator
#
# Profile 2 — Multi-user anonymous demo:
#   DF_MANAGED=true
#   WORKSPACE_BACKEND=ephemeral
#   DISABLE_DATA_CONNECTORS=true
#   DISABLE_CUSTOM_MODELS=true
#   DISABLE_DISPLAY_KEYS=true
#   Legacy shortcut: DISABLE_DATABASE=true (deprecated; also enables managed mode)
#
# Profile 3 — Multi-user authenticated (team):
#   DF_MANAGED=true
#   DF_ADMIN_IDENTITIES=user:<verified-admin-subject>
#   AUTH_PROVIDER=oidc
#   OIDC_ISSUER_URL=https://your-idp.example.com/realms/main
#   OIDC_CLIENT_ID=data-formulator
#   ALLOW_ANONYMOUS=false
#   DISABLE_CUSTOM_MODELS=true
#   WORKSPACE_BACKEND=azure_blob
#   FLASK_SECRET_KEY=<generate-with: python -c "import secrets; print(secrets.token_hex(32))">
#
#   If your IdP requires a confidential (private) client, just add the secret:
#   OIDC_CLIENT_SECRET=your-client-secret