Dify Environment Variable Documentation

Not an entry point — run under dify-docs-write; the procedure below implements its stages for en/self-host/deploy/configuration/environments.mdx. Read references/style-overrides.md (in this skill directory — env-var-specific style rules and description anti-patterns) together with this pack. Use the ref pinned at S1; cite it in the S4 scope report.

Standalone procedure: release-sync diff

Invoked from dify-docs-release-sync only. Run this before any tracing. Per-PR detection misses vars from untagged PRs, and the verifier's Missing-from-docs list hides genuinely new vars inside old backlog.

python3 .claude/skills/dify-docs-env-vars/verify-env-docs.py \
  --compare-rev <last-release-tag> <target-release-tag> \
  --repo <path-to-dify-repo> \
  --docs en/self-host/deploy/configuration/environments.mdx

Pin exact tags or SHAs (e.g., --compare-rev 1.14.1 1.15.0), never a branch name. The script prints the vars added / removed / default-changed between the refs, then === NEW vars NOT documented and NOT in ignored-vars (<n>) — TRIAGE ===, and exits 0. Every triage var must end the task either documented or in ignored-vars.md with a reason — never as silent backlog.

Procedure (S2 → S6)

Work through in order. Every variable goes through steps 1–4 without exception — do not skip a variable because it seems "obvious".

Step 1 (S2): Trace each variable in the codebase

When using subagents for tracing, assign 3–5 related variables per agent. Tracing depth depends on variable type:

Full trace:

1. Find the definition in api/configs/ — Pydantic field type, default, description, and any validation_alias (fallback) settings.
2. Find every usage — grep both the env var name and the Python attribute (difyconfig.VARIABLENAME); read the surrounding code.
3. Determine behavior when empty vs set — trace fallback chains; identify what breaks.

Step 2 (S2): Write a plain-language explanation

Cover: what the variable does in practical terms; the specific features that depend on it (name them); what happens if left empty; what happens if set; key code file paths (no line numbers — they shift). This explanation goes into the S4 scope report.

Step 3 (S5): Write the user-facing description

• Lead with the practical impact, not the technical mechanism
• Name the features that require the variable (e.g., "Required for the Human Input node")
• Explain what breaks if misconfigured (e.g., "If empty, email links will be broken")
• Mention fallback behavior if any (e.g., "falls back to CONSOLEAPIURL")
• Include relationships with other variables when relevant
• Apply every rule in references/style-overrides.md

Step 4 (S4 contribution): Report

The S4 scope report presents: the plain-language explanations, the proposed descriptions, and the pinned ref. The pipeline's S4 gate applies.

Step 5 (S5/S6): Edit the documentation

Edit en/self-host/deploy/configuration/environments.mdx following [Document Structure](#document-structure). Update the zh/ and ja/ copies in the same pass, per tools/translate/formatting-zh.md, tools/translate/formatting-ja.md, and writing-guides/glossary.md.

S7 verifiers

Run the verifier

The canonical command scans BOTH env sources — never pass only one:

python3 .claude/skills/dify-docs-env-vars/verify-env-docs.py \
  --env-example <path-to-dify-repo>/docker/.env.example \
  --env-example <path-to-dify-repo>/docker/envs \
  --docs en/self-host/deploy/configuration/environments.mdx

--env-example is repeatable; a directory argument is globbed **/*.env.example recursively. The script first prints the list of files it parsed — confirm it shows docker/.env.example plus the files under docker/envs/. A single-source run under-scans and produces false "extra in docs" results.

Output contract: on a fully clean doc the last line is ALL CHECKS PASSED — documentation matches .env.example and the script exits 0; otherwise it prints TOTAL ISSUES: <n> with per-category counts and exits 1.

Pass bar for every task: Extra in docs: 0 and Default mismatches: 0. Missing from docs is standing backlog and may stay nonzero, but no variable you touched may appear in it, and every release-sync-diff triage var must be resolved.

Update ignored-vars.md if needed

The verifier filters out variables listed in ignored-vars.md (in this skill directory). When you:

• Remove a variable from the docs as Cloud-only → add it under Cloud-only (SaaS).
• Skip documenting an experimental or internal flag → add it under Experimental / internal.
• Document a supported variable whose .env.example entry is commented out (#FOO=bar) → add it under Verifier false positives. This bucket is only for vars present in .env.example in commented form; see [Source of Truth](#source-of-truth) for vars absent entirely.

Every entry must include a source reference (PR, commit, or audit date).

Source of Truth

After Dify PR #31586, the supported self-host knob surface is split across:

• docker/.env.example — essential startup values
• docker/envs/**/*.env.example — categorized optional vars (core-services, databases, infrastructure, security, vectorstores, middleware)

The verifier reads both — always use the canonical verifier command above, which passes both sources.

The verifier's "extra in docs" signal is not an escape hatch. Never suppress it for Pydantic-only vars via ignored-vars.md.

Document Structure

The doc groups variables by subsystem, broadly following the docker/.env.example and docker/envs/** layout (Common Variables, Server Configuration, Web Frontend Service, Database Service, and so on). Match an existing ## section for a new variable; don't invent one. If a variable genuinely fits no section, raise it with the user rather than guessing.

Reader Persona

Same audience as en/self-host/deploy/ documentation (see the dify-docs-guides pack): DevOps engineers and system administrators deploying Dify. Assume strong infrastructure knowledge. Readers are actively configuring a deployment and scanning for a specific variable, not reading linearly. They need to know what each variable does, when to change it, and what breaks if they get it wrong.