// Use when writing, rewriting, or auditing environment variable documentation for Dify self-hosted deployment. Applies to en/self-host/configuration/environments.mdx. Covers the full process from codebase tracing to user-facing descriptions.
| name | dify-docs-env-vars |
| description | Use when writing, rewriting, or auditing environment variable documentation for Dify self-hosted deployment. Applies to en/self-host/configuration/environments.mdx. Covers the full process from codebase tracing to user-facing descriptions. |
Read these shared guides:
writing-guides/style-guide.mdwriting-guides/formatting-guide.mdwriting-guides/glossary.mddocker/.env.example + docker/envs/**/*.env.exampleAfter Dify PR #31586, the supported self-host knob surface is split across:
docker/.env.example — essential startup valuesdocker/envs/**/*.env.example — categorized optional vars (core-services, databases, infrastructure, security, vectorstores, middleware)The verifier reads both. Pass --env-example docker/.env.example --env-example docker/envs (the second arg is a directory; the verifier globs **/*.env.example recursively).
| Var location | Action |
|---|---|
In any .env.example file, uncommented | Document. |
In any .env.example file, commented (#FOO=bar) | Document; add to Verifier false positives in ignored-vars.md (the verifier can't parse defaults from comments). |
Only in api/configs/ Pydantic, not in any .env.example | Don't document. Upstream-deferred; file a PR adding it to the appropriate .env.example file first. |
Removed from .env.example because the code no longer reads it | Remove from docs. Documenting unreferenced vars implies they still take effect. Discoverability for upgraders belongs in upstream Dify release notes, not this docs site. |
The verifier's "extra in docs" signal is not an escape hatch. Never suppress it for Pydantic-only vars via ignored-vars.md.
Pull the latest Dify code before tracing. In the Dify codebase directory:
git fetch origin && git checkout main && git pull origin main
This process applies to every variable without exception. Do not skip variables because they seem "obvious" — every variable must be traced, explained, and described.
Agent granularity: When using subagents for tracing, assign 3–5 related variables per agent.
Tracing depth depends on variable type:
api/configs/): Full tracing — find definition, all usage locations, and behavior when empty vs set.web/docker/entrypoint.sh): Trace from entrypoint.sh to find the Docker-to-NEXT_PUBLIC_* mapping, verify the default in both docker/.env.example and web/.env.example, and check whether the variable is also used in Python code (dual-purpose). For Next.js-only variables (UI knobs like MAX_TOOLS_NUM), light verification is sufficient.docker-compose.yaml): Light verification — grep to confirm the variable is not used in Python code, then document from .env.example comments.PLUGIN_* not in api/configs/): Document from .env.example comments.For full tracing, search the Dify codebase:
api/configs/ — note the Pydantic field type, default, description, and any validation_alias (fallback) settings.dify_config.VARIABLE_NAME). Read surrounding code to understand what each usage does.Write an explanation covering:
Save to deep-dive.md (in this skill directory) under the appropriate section heading.
Transform the explanation into a concise documentation description. The description must:
CONSOLE_API_URL")Present the proposed description to the user for review before editing the documentation file.
The env var doc is organized into three sections following docker/.env.example section order:
<Tabs> to show Docker and source code variable names.When to use tables: Groups of related, straightforward variables (connection settings, credentials, tuning knobs).
When to use individual headings: Important variables needing explanation — typically enum-type selectors (STORAGE_TYPE, VECTOR_STORE) or variables where the "why" matters (SECRET_KEY, FILES_URL).
When to use tabs: Frontend section variables where Docker and source code deployments use different variable names. Tabs cannot be placed inside table cells, so all tabbed variables require individual headings.
When to use accordions: Provider-specific configuration (storage backends, vector databases, mail providers) — users only need one provider.
Same audience as en/self-host/ documentation (see dify-docs-guides skill): DevOps engineers and system administrators deploying Dify. Assume strong infrastructure knowledge.
Additional context for env var docs: Readers are actively configuring a deployment. They need to know what each variable does, when to change it, and what breaks if they get it wrong. They are not reading linearly—they are scanning for a specific variable.
Rules specific to env var docs (override or extend the shared style guide):
(empty) for empty-string defaults, not "" or blank(empty; falls back to X) or (empty; defaults to X)sk-* patterns. Use descriptions like (pre-filled in .env.example; must be replaced for production)Consistency over variety in reference tables. The general style guide says to vary sentence patterns. In reference tables, consistency aids scanning. Use predictable patterns for connection credentials (hostname, port, username, password) across providers. Vary descriptions only when variables genuinely differ in behavior or purpose.
Variable descriptions should be self-contained. The general style guide says not to restate the heading. Variable descriptions must state what the variable does—even if the name partially implies it. Not all variable names are self-explanatory, and users may arrive at a description via search without seeing the surrounding section context.
Include actionable technical mechanisms. The general style guide favors user outcomes over technical mechanisms. For env var docs, include technical mechanisms that help users configure, troubleshoot, or understand trade-offs—algorithm names, encoding behavior, fallback chains, version requirements. Exclude mechanisms that only describe code architecture—factory patterns, lazy imports, class names—unless understanding them is necessary for configuration.
@, :, % are safe to use", "HMAC-SHA256", "Requires Milvus >= 2.5.0", "Falls back to CONSOLE_API_URL"No specific recommended values for tuning parameters. For numeric tuning parameters without clear boundaries (connection pool sizes, worker counts, timeouts, buffer sizes), do not prescribe values. Describe the symptom that indicates the value needs changing: "If you experience connection rejections under load, try increasing this value." Exception: when a value has a well-established recommendation (e.g., PostgreSQL shared_buffers = 25% of RAM), include it with a reference link.
| Anti-Pattern | Better |
|---|---|
| "Used for frontend references" | "Required for the Human Input node — form links in email notifications are built from this URL" |
| "The backend URL of the console API" | "Set this if you use OAuth login (GitHub, Google) or Notion integration — these features need an absolute callback URL" |
| "Upload file size limit, default 15" | "Maximum file size in MB for uploads" |
| Restating the code comment verbatim | Explaining when you'd change it and what happens if you don't |
Run after completing any documentation change:
python3 .claude/skills/dify-docs-env-vars/verify-env-docs.py \
--env-example <path-to-docker/.env.example> \
--docs <path-to-environments.mdx>
The script reports:
.env.example not yet documented (address over time).env.example (verify manually).env.example — must be zero before work is completeUse .env.example defaults (what Docker Compose users actually get), not Pydantic code defaults.
Some variables in .env.example are deliberately not documented (Cloud-only, experimental, or verifier false positives). The verifier reads these from ignored-vars.md (same directory) and filters them out. When you:
ignored-vars.md..env.example entry is commented out (e.g., #FOO=bar) → add it under Verifier false positives. This bucket is only for vars that exist in .env.example in commented form. Do not use it to suppress verifier signal for vars that are absent from .env.example entirely — those are upstream-deferred (see Source of Truth) and must not be documented.Every entry must include a source reference (PR, commit, or audit date).
The automated translation pipeline does not cover en/self-host/configuration/environments.mdx. After editing that English file, manually update zh/self-host/configuration/environments.mdx and ja/self-host/configuration/environments.mdx to match.
After completing the document, run the post-writing checks listed in writing-guides/index.md#post-writing-verification.
Use when editing, auditing, or creating OpenAPI specs for the Dify documentation repo. Applies to files in en/api-reference/. Covers formatting rules, error code conventions, example standards, operationId patterns.
Use when preparing documentation updates for a Dify release. User provides two version references to compare (e.g., v1.13.2 and v1.13.3, or v1.13.2 and main). Covers API reference, help documentation, environment variable changes, and UI i18n glossary impact.
Check formatting compliance in changed Chinese and Japanese documentation against writing-guides/formatting-guide.md, tools/translate/formatting-zh.md, and tools/translate/formatting-ja.md. Use after finalizing a translation batch, or when the user says "check formatting (zh/ja)", "check CJK formatting", or "format audit" on translated content.
Check formatting compliance in changed English documentation against writing-guides/formatting-guide.md. Use after finalizing a draft, or when the user says "check formatting", "format audit", "format check" on English content.
Research a Dify feature before writing or optimizing documentation. Use when starting any doc task that requires understanding a feature's implementation, user pain points, or community feedback. Triggers: 'research this feature', 'investigate the code for', 'what do users say about', 'let's understand how X works before writing', or any documentation task where the current docs are being rewritten or significantly expanded.
Use when writing, improving, or reviewing Dify user guide documentation. Covers pages in en/use-dify/, en/develop-plugin/, and en/self-host/. Triggers: "write docs for [feature]", "improve this page", "review this documentation section".