Dify Docs Env Vars

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.

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 (dify_config.VARIABLE_NAME); 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 CONSOLE_API_URL")
• 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. 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 \
  --compose <path-to-dify-repo>/docker \
  --docs en/self-host/deploy/configuration/environments.mdx

--compose reads the ${VAR} references in docker/docker-compose*.y*ml. A variable a compose file consumes with no .env.example entry is invisible to every other check — EXPOSE_WEAVIATE_GRPC_PORT went undocumented for eleven months that way — so the script lists them under === IN COMPOSE BUT NOT IN ANY .env.example (<n>) === and treats them as source variables from then on. --compare-rev reads the compose files at both refs on its own. docker-compose.pytest.ports.yaml is skipped in both modes and the skip is printed: it publishes vector-store ports for the integration tests, and nothing a deployment reads.

--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/, then the compose file count. 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.

Cadence. The full command above is the baseline audit, and the baseline was cleared at dify tag 1.17.1. A release pass runs --compare-rev — it diffs both the .env.example files and the compose references between two refs, so a clean baseline stays clean incrementally. Re-run the full command whenever this script, the ignore list's location, or the .env.example layout changes, and after any pass that touched more than a handful of variables; it must end on ALL CHECKS PASSED or every remaining line must be accounted for in the ignore list. Run it against the zh and ja pages too — the parser understands 默认值：, デフォルト値： and （空）, so their counts are as meaningful as English's.

Pass bar for every task: the full command ends on ALL CHECKS PASSED, or every remaining line is accounted for in the ignore list with a reason. Missing from docs stopped being standing backlog when the baseline was cleared at tag 1.17.1: a nonzero count now means a variable arrived since, and it is documented or ignored before the task ends. If the script prints WARNING: ignore list not found, it stops with exit status 2 and prints no counts: fix the path and re-run.