.env.example

# ── DeepSQL Self-Hosted — Environment Variables ────────────────────────────────
# Copy this file to .env and fill in the required values.
#   cp .env.example .env
#
# Deployment model:
# - Everything runs inside your environment: DeepSQL, Postgres, Valkey, pgvector,
#   and your database connections.
# - There are no prebuilt DeepSQL images and no container registry. `docker compose`
#   builds the backend and frontend from this checkout (backend/Dockerfile and the
#   root Dockerfile). The first build takes several minutes.
# - You bring your own LLM. DeepSQL ships no model credentials and bakes none into
#   the build; it calls whichever provider you configure below.

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# REQUIRED — Security
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Both secrets below are REAL values, not free text — the backend validates them at
# startup and refuses to boot on a placeholder. `install.sh` generates and writes them
# for you. If you are driving Compose yourself, generate them now:
#
#   printf 'SECURITY_JWT_SECRET=%s\n' "$(openssl rand -base64 64 | tr -d '\n')" >> .env
#   printf 'ENCRYPTION_KEY=%s\n'      "$(openssl rand -base64 32)"             >> .env
#
# and delete the two empty assignments below.

# JWT signing secret — 64 random bytes, base64.
SECURITY_JWT_SECRET=

# AES-GCM key for the stored-credential vault — exactly 32 random bytes, base64.
# Anything else fails startup with "Invalid encryption key material".
# Losing this key makes every stored database credential unrecoverable: back it up.
ENCRYPTION_KEY=
ENCRYPTION_KEY_ID=self-hosted-key-1

# Vault database password — leave empty / change-me-* so install.sh generates one.
# Never leave this as the literal "postgres" on a networked host.
DB_PASSWORD=change-me-db-password

# Valkey/Redis password (compose --requirepass). Generated by install.sh when placeholder.
DEEPSQL_VALKEY_PASSWORD=change-me-valkey-password

# Self-host should always use the hardened production Spring profile.
SPRING_PROFILES_ACTIVE=prod

# Optional — a display label for this installation, shown in the admin views.
# It stays in your own vault database; nothing is reported anywhere.
# Falls back to the admin email domain on first boot if left blank, then
# to the literal string 'unknown'. Stored once at first start; change later
# by editing this value and restarting the backend.
#DEEPSQL_COMPANY_NAME=

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# REQUIRED — AI / LLM (bring your own)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# DeepSQL calls the LLM provider you configure here. No credentials are supplied
# by the DeepSQL project and none are baked into the images.
#
# Chat and embeddings are configured independently — they may point at different
# providers, keys, or endpoints.
#
# The only provider id shipped in this release is `openai`, which speaks OpenAI,
# Azure OpenAI, and any OpenAI-compatible server or gateway (vLLM, Ollama,
# LM Studio, TGI, LiteLLM). Point ENDPOINT at it and it works; there is nothing
# else to select.
#
# Behind a LiteLLM proxy, API_KEY is the virtual key and MODEL is your alias from
# its config.yaml — include the /v1 on the endpoint:
#   DEEPSQL_CHAT_ENDPOINT=http://litellm:4000/v1
#   DEEPSQL_CHAT_API_KEY=sk-your-litellm-virtual-key
#   DEEPSQL_CHAT_MODEL=your-alias
# and the same three for DEEPSQL_EMBEDDING_*. See USE_RESPONSES_API below for the
# one way alias naming can matter.
#
# Setting these is the supported way to configure the LLM. The onboarding wizard
# in the UI writes a different, older set of keys that nothing reads — do not rely
# on it.
#
# The backend itself boots fine with all of these unset; it only raises when
# something first asks for a model. install.sh nevertheless requires the three chat
# values below, because an install that cannot answer a question is not a working
# install.

# ── Chat ────────────────────────────────────────────────────────────────────
# PROVIDER must be set for any of the others to be read at all.
# ENDPOINT has no fallback for chat — set it explicitly, including for OpenAI.
DEEPSQL_CHAT_PROVIDER=openai
DEEPSQL_CHAT_API_KEY=replace-with-your-chat-api-key
DEEPSQL_CHAT_ENDPOINT=https://api.openai.com/v1
DEEPSQL_CHAT_MODEL=gpt-4o

# Optional chat tuning. Shown with their built-in defaults; omit unless changing.
#DEEPSQL_CHAT_TEMPERATURE=1.0
# Azure REST API version, used only against an Azure endpoint.
#DEEPSQL_CHAT_API_VERSION=2025-03-01-preview
# true | false | auto. `auto` picks the Responses API for reasoning models
# (gpt-5*, o1/o3/o4, codex) and chat completions for gpt-4*/gpt-3*.
#
# `auto` decides from the MODEL NAME, not from what the endpoint implements. Behind
# a gateway that lets you name models freely, an alias starting gpt-5/o1/o3/o4/codex
# therefore selects /v1/responses even if the gateway only serves chat completions.
# Either avoid those prefixes or set this to false. An alias that looks nothing like
# an OpenAI model — the usual case — already resolves to chat completions.
#DEEPSQL_CHAT_USE_RESPONSES_API=auto

# ── Embeddings ──────────────────────────────────────────────────────────────
# Used for RAG retrieval. Without them, retrieval falls back to keyword-only.
# MODEL and ENDPOINT do have defaults here (text-embedding-3-large,
# https://api.openai.com/v1); PROVIDER and API_KEY do not.
DEEPSQL_EMBEDDING_PROVIDER=openai
DEEPSQL_EMBEDDING_API_KEY=replace-with-your-embedding-api-key
DEEPSQL_EMBEDDING_ENDPOINT=https://api.openai.com/v1
DEEPSQL_EMBEDDING_MODEL=text-embedding-3-large

# ── Azure OpenAI example ────────────────────────────────────────────────────
#   DEEPSQL_CHAT_PROVIDER=openai
#   DEEPSQL_CHAT_API_KEY=replace-with-your-azure-openai-key
#   DEEPSQL_CHAT_ENDPOINT=https://replace-with-your-resource.cognitiveservices.azure.com/
#   DEEPSQL_CHAT_MODEL=replace-with-your-deployment-name
# An `.azure.com` / `.azure-api.net` endpoint switches authentication to the
# `api-key` header automatically. MODEL is the *deployment* name, not the model id.

# ── Self-hosted (Ollama) example ────────────────────────────────────────────
#   DEEPSQL_CHAT_PROVIDER=openai
#   DEEPSQL_CHAT_ENDPOINT=http://host.docker.internal:11434/v1
#   DEEPSQL_CHAT_MODEL=llama3.1
#   DEEPSQL_CHAT_API_KEY=ollama

# When an embedding call fails: true returns an empty vector and degrades retrieval
# silently, false propagates the error. Defaults to true, except under the prod
# profile which defaults to false.
EMBEDDING_FAIL_OPEN=false

# ── DeepSQL Agent (Agent tab + AI dashboards) ───────────────────────────────
# The fifth Compose service (`deepsql-agent`) serves the Agent tab, AI
# dashboards, and Slack/CLI agent turns. install.sh auto-generates
# AGENT_PROVISION_SECRET; Compose wires the rest. Override only for native
# (non-Compose) development or a custom agent hostname.
#
# AGENT_WEBUI_URL          Agent HTTP API. Compose default: http://deepsql-agent:8787
# AGENT_PROVISIONER_URL   Per-user profile provisioner. Compose default:
#                         http://deepsql-agent:8788/provision
# DEEPSQL_API_BASE_URL    Where the agent container's MCP tools call the backend.
#                         Compose default: http://backend:8080/api/
#                         Native Java + Compose agent: http://host.docker.internal:8080/api/
# AGENT_PROVISION_SECRET  Shared secret between backend and agent (required).
# DEEPSQL_AGENT_PORT / DEEPSQL_AGENT_PROVISIONER_PORT — host port mappings
# (compose binds these to 127.0.0.1 only; public path is nginx /agent-api).
# Native (non-Compose) agent: HERMES_WEBUI_HOST defaults to 127.0.0.1 in
# setup-agent.sh — do not set 0.0.0.0 on internet-facing hosts.
#
#AGENT_WEBUI_URL=http://deepsql-agent:8787
#AGENT_PROVISIONER_URL=http://deepsql-agent:8788/provision
AGENT_PROVISION_SECRET=change-me-agent-provision-secret
#DEEPSQL_AGENT_PORT=8787
#DEEPSQL_AGENT_PROVISIONER_PORT=8788
#HERMES_WEBUI_HOST=127.0.0.1
#DEEPSQL_SMOKE_AGENT=1

# ── Demo Data Seeding ───────────────────────────────────────────────────────
# Seed a ready-to-explore demo database with sample e-commerce data, users,
# saved queries, slow query history, and index recommendations.
# Set to 1 to automatically run seed-demo-data.sh during install.
# Can also be run manually: ./scripts/self-host/seed-demo-data.sh
#DEEPSQL_SEED_DEMO_DATA=0
#DEEPSQL_SEED_CONNECTION_NAME=Demo Shop (E-commerce)
#DEEPSQL_SEED_SKIP_DEMO_DB=0

# ── The /api/llm/v1 agent gateway ───────────────────────────────────────────
# The DeepSQL CLI agent (`@deepsql/mcp`) points its model at <backend>/api/llm/v1
# and authenticates with a DeepSQL token; the backend forwards those calls
# upstream. It needs no configuration of its own — LlmProxyController resolves the
# same DEEPSQL_CHAT_* bundle set above.
#
# AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_KEY / AZURE_OPENAI_CHAT_DEPLOYMENT are NOT
# listed here on purpose: they still appear in application.properties, but no Java
# code reads any azure.openai.* property any more, so setting them changes nothing.

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL — Native (non-Compose) DeepSQL Agent
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Only needed when you run the backend with `mvn spring-boot:run` instead of
# Compose. Point at a local agent process and start the provisioner:
#   python3 scripts/local-agent-provisioner.py
# Or use the legacy host installer: ./scripts/self-host/setup-agent.sh
# (set DEEPSQL_HOST_AGENT_SETUP=1). Prefer Compose for self-host / enterprise.
#AGENT_WEBUI_URL=http://127.0.0.1:8787
#AGENT_PROVISIONER_URL=http://127.0.0.1:8788/provision

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# VECTOR STORE — choose one mode
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# MODE A: pgvector (self-hosted, no external dependencies)
# RAG embeddings stored locally in the PostgreSQL vault DB.
# Requires pgvector extension — already included in the docker-compose postgres image.
VECTOR_STORE_TYPE=pgvector
AZURE_SEARCH_ENABLED=false

# Required for pgvector mode — disables Azure Vector Store auto-configuration.
# install.sh sets this automatically; leave blank only if using Azure AI Search (Mode B).
SPRING_AUTOCONFIGURE_EXCLUDE=org.springframework.ai.vectorstore.azure.autoconfigure.AzureVectorStoreAutoConfiguration

# MODE B: Azure AI Search — your own Azure resource, managed hybrid search.
# Uncomment and fill these in if you prefer it to local pgvector. You supply the
# search resource and key; DeepSQL only talks to the endpoint you name here.
#VECTOR_STORE_TYPE=azure
#AZURE_SEARCH_ENABLED=true
#AZURE_SEARCH_ENDPOINT=https://your-search-resource.search.windows.net
#AZURE_SEARCH_API_KEY=your-azure-search-api-key
#AZURE_SEARCH_INDEX_NAME=deepsql-training-data

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL — Frontend
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Host ports (change these only if the defaults are already in use)
DEEPSQL_FRONTEND_PORT=3000
DEEPSQL_BACKEND_PORT=8080
DEEPSQL_POSTGRES_PORT=5432
DEEPSQL_VALKEY_PORT=6379

# Browser origins allowed to call the backend
CORS_ALLOWED_ORIGINS=http://localhost:3000

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL — Email / SMTP
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Configure these later from Settings if you prefer. The app reads env values as
# fallback defaults and runtime DB-backed settings as the primary source.
#EMAIL_HOST=smtp.gmail.com
#EMAIL_PORT=587
#EMAIL_USERNAME=your-email@gmail.com
#EMAIL_PASSWORD=your-app-password
#EMAIL_FROM=noreply@yourcompany.com

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL — Slack Data Agent (Socket Mode)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Slack bot runs inside the DeepSQL backend and connects outbound via Socket Mode.
# Recommended setup: create a dedicated non-admin DeepSQL user that owns only the
# connections Slack should be allowed to use, then set that username below.
SLACK_ENABLED=false
SLACK_SOCKET_MODE_ENABLED=false
SLACK_APP_TOKEN=
SLACK_BOT_TOKEN=
SLACK_SIGNING_SECRET=
SLACK_DEEPSQL_BOT_USERNAME=

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# OPTIONAL — Admin Bootstrap (managed by install.sh)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# install.sh temporarily enables bootstrap, creates the first admin directly,
# then disables bootstrap again after the stack is healthy.
SECURITY_ADMIN_BOOTSTRAP_ENABLED=false
ADMIN_BOOTSTRAP_SECRET=replace-with-a-one-time-bootstrap-secret

# install.sh prompts for these values if they are blank.
DEEPSQL_INITIAL_ADMIN_EMAIL=
DEEPSQL_INITIAL_ADMIN_PASSWORD=