Repository navigation
Conversation
Update the Docker Compose, environment-variable, and Dify Premium pages in English, Chinese, and Japanese for the categorized defaults layout in langgenius/dify#45359. Explain root and service override precedence, shared credential placement, mapped inputs, and Docker Compose requirements. Preserve working configuration during upgrades and identify values that now become effective.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Point sandbox and Code node customization to the current defaults templates in English, Chinese, and Japanese. Explain copying new overrides, editing existing files, and uncommenting optional assignments. Document preserved shared.env paths and cleanup of accidental empty Celery worker overrides when upgrading to the consolidated shared defaults.
Clarify Docker Compose setup, optional service overrides, precedence, and configuration application across English, Chinese, and Japanese guides. Use current-state explanations and a complete Nginx customization example. Correct secret-key persistence, sandbox behavior, Code limits, WebSocket setup, and bundled credential defaults. Preserve upgrade guidance for local overrides, persistent storage, and the agent's named volumes. Remove the AWS AMI additions from this PR because its packaging is not established by the companion Docker configuration change.
laipz8200
changed the title
Update Docker setup and environment references in English, Chinese, and Japanese to use api-worker.defaults and api-worker.env. Explain continued shared.env support and the precedence of the new file, and retain upgrade instructions for both existing and new override paths.
Update the Premium deployment guide in English, Chinese, and Japanese to use the current defaults templates and Docker Compose 2.35.0. Upgrade from a selected release while preserving local environment files, AWS Compose overrides, secrets, and persistent data. Replace outdated Agent template-sync advice with explicit override checks and web container recreation. Document the unset and empty true fallback from web.defaults, root precedence, and current navigation visibility.
RiskeyL
left a comment
RiskeyL
left a comment
There was a problem hiding this comment.
Fact-checked the three pages against dify dc36c3eb44 and tested the database/vector-store switch and the sandbox key on a local stack. The inline comments are factual issues; each applies to the zh and ja pages too.
| Shared secret that authenticates the agent backend to the bundled sandbox. While it's empty, both services exit at startup and keep restarting, so set it before you start Dify. | ||
|
|
||
| Set it once in `docker/.env`, and Compose passes it to both services. A value set only in a file under `docker/envs/` doesn't take effect. | ||
| Set it once in `docker/.env` so both the agent backend and the bundled sandbox receive it. Setting it only in the agent backend's service file leaves the sandbox without the matching credential. |
There was a problem hiding this comment.
"Setting it only in the agent backend's service file leaves the sandbox without the matching credential."
A value set only in envs/core-services/dify-agent.env doesn't reach the agent backend either: docker/.env.example:15 ships an empty DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN= line, agent_backend loads ./.env after dify-agent.env (docker-compose-template.yaml:738-746), and local_sandbox reads the token only by interpolation from docker/.env (template L587). Rendered with the token only in dify-agent.env: both get an empty value. Suggest: "A value set only in envs/core-services/dify-agent.env doesn't take effect: the empty DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN= line from .env.example in docker/.env overrides it, and the sandbox reads the token only from docker/.env."
| These variables stay in `docker/.env` because Docker Compose uses them to select profiles and expose ports before containers start. | ||
| Keep Compose settings in `docker/.env`: profiles, published ports, mount paths, and health-check scheduling are read before containers start. | ||
|
|
||
| Set `DB_TYPE`, `VECTOR_STORE`, and `COMPOSE_PROFILES` together. For example, a deployment with bundled PostgreSQL and Qdrant uses `DB_TYPE=postgresql`, `VECTOR_STORE=qdrant`, and `COMPOSE_PROFILES=qdrant,postgresql,collaboration`. The bundled MySQL service uses the `mysql` profile, and pgvector uses `pgvector`. For an external provider, omit its bundled service profile. |
There was a problem hiding this comment.
"Set
DB_TYPE,VECTOR_STORE, andCOMPOSE_PROFILEStogether. … a deployment with bundled PostgreSQL and Qdrant uses … The bundled MySQL service uses themysqlprofile, and pgvector usespgvector."
The three selectors aren't enough outside PostgreSQL + Weaviate. I tested this layout locally (dc36c3eb44 compose files):
- Qdrant, selectors only: the API starts and reports healthy, but it has no
QDRANT_URL, so the first vector-index write fails withConnection refused(the client falls back tolocalhost:6333). After copyingenvs/vectorstores/qdrant.defaultstoqdrant.envand uncommentingQDRANT_URL, the write succeeds. - MySQL, selectors only: the API keeps
DB_HOST=db_postgres,DB_PORT=5432,DB_USERNAME=postgres(fromapi-worker.defaults) and restart-loops onDatabase migration failed. AddingDB_HOST=db_mysql,DB_PORT=3306,DB_USERNAME=rootfixes it.
Why: the bundled defaults carry connection settings only for PostgreSQL and Weaviate (api-worker.defaults:98-104,466-471); the Qdrant and pgvector client settings are commented out, and the API loads only the local qdrant.env / pgvector.env, not their .defaults.
Suggest: "Set DB_TYPE, VECTOR_STORE, and COMPOSE_PROFILES together, plus the provider's connection settings; the bundled defaults include them only for PostgreSQL and Weaviate. For bundled Qdrant, copy envs/vectorstores/qdrant.defaults to qdrant.env and uncomment QDRANT_URL. For pgvector, uncomment the PGVECTOR_* client settings in pgvector.env. For bundled MySQL, also set DB_HOST=db_mysql, DB_PORT=3306, and DB_USERNAME=root." Related: the Qdrant rows (L728–729) still give http://qdrant:6333 and difyai123456 as defaults the API no longer receives.
| | Variable | Default | Description | | ||
| |---|---|---| | ||
| | `SANDBOX_API_KEY` | `dify-sandbox` | API key for sandbox authentication. Must match `CODE_EXECUTION_API_KEY` in the API service. | | ||
| | `SANDBOX_API_KEY` | `dify-sandbox` | API key for sandbox authentication. Must match `CODE_EXECUTION_API_KEY` in the API and workers. | |
There was a problem hiding this comment.
SANDBOX_API_KEY: "Must matchCODE_EXECUTION_API_KEYin the API and workers." (section says to customize by creatingsandbox.env)
Tested locally: with SANDBOX_API_KEY changed only in sandbox.env, every Code node run fails with "Failed to execute code, which is likely a network issue, please check if the sandbox service is running. ( Error: Failed to execute code, got status code 401 … )", and the sandbox logs a 401. Setting CODE_EXECUTION_API_KEY to the same value in envs/core-services/api-worker.env fixes it.
Why: only sandbox loads sandbox.env; the API reads CODE_EXECUTION_API_KEY (default dify-sandbox, api/configs/feature/__init__.py:130-133), which isn't mapped from SANDBOX_API_KEY and isn't in api-worker.defaults.
Suggest: "Must match CODE_EXECUTION_API_KEY, which the API and workers read separately. To change the key, set both variables in docker/.env, or set CODE_EXECUTION_API_KEY to the same value in envs/core-services/api-worker.env." Also add this pair to the shared-credential list at L27.
| | `SANDBOX_GIN_MODE` | `release` | Sandbox service mode: `release` or `debug`. | | ||
| | `SANDBOX_WORKER_TIMEOUT` | `15` | Maximum execution time in seconds for a single code run. | | ||
| | `SANDBOX_ENABLE_NETWORK` | `true` | Allow code to make outbound HTTP requests. Disable to prevent code nodes from accessing external services. | | ||
| | `SANDBOX_ENABLE_NETWORK` | `true` | Allows scripts to request network access.<br/><br/>Dify's Code nodes request network-enabled execution, so setting this to `false` rejects their requests. Keep it enabled when using Code nodes. | |
There was a problem hiding this comment.
"Dify's Code nodes request network-enabled execution, so setting this to
falserejects their requests." / "Thesandboxservice executes Code nodes."
Every sandbox call sends enable_network: True (api/core/helper/code_executor/code_executor.py:85-90), and the same executor also renders Template nodes (node_factory.py:491-494), Jinja2 prompts in LLM nodes (node_factory.py:515-523, advanced_prompt_transform.py:131,186), and the built-in code tool. Suggest: "Dify requests network-enabled execution on every sandbox call, so false makes Code nodes, Template nodes, and Jinja2 prompt templates fail. Keep it enabled." Intro: "The sandbox service runs Code nodes and renders Jinja2 for Template nodes and LLM prompts."
|
|
||
| ### Precedence | ||
|
|
||
| For settings a service loads, `docker/.env` overrides its local service `.env`, which overrides the bundled or application defaults. A service reads only the files assigned to it; a value in an unrelated service file has no effect. |
There was a problem hiding this comment.
"For settings a service loads,
docker/.envoverrides its local service.env, which overrides the bundled or application defaults."
Holds for services that load ./.env (API, WebSocket API, workers, Beat, web, sandbox, plugin daemon, agent backend, KnowledgeFS workers). Nginx, the databases, Redis, the vector stores, the SSRF proxies, certbot, and etcd/MinIO/Milvus don't load it: a root value reaches them only for variables named in their .defaults file. knowledge_fs_unstructured never reads docker/.env. Rendered: ASYNC_INDEXING=false in weaviate.env + true in docker/.env → Weaviate gets false. Suggest appending: "Containers that don't load docker/.env, such as Nginx, the databases, Redis, and the vector stores, take root values only for variables listed in their .defaults file; set any other variable in the service's local file."
| | `docker/.env` | Deployment inputs and overrides, including shared credentials and settings Compose reads before containers start: profiles, published ports, mount paths, and health-check scheduling. Create it from `docker/.env.example` for a new deployment. | | ||
| | `docker/envs/**/*.defaults` | Bundled Docker defaults and commented examples of optional settings. Each service loads the files assigned to it in Compose. | | ||
| | Local `.env` files under `docker/envs/` | Overrides for the services that load each file. A template's comments identify the local file to create. | | ||
| | `docker/envs/**/*.env.example` | Templates for optional or provider-specific settings. Copy one without the `.example` suffix to create its local `.env` file. | |
There was a problem hiding this comment.
"Copy one without the
.examplesuffix to create its local.envfile."
Exception: envs/middleware.env.example is copied to docker/middleware.env (docker/README.md:263; the source-code deployment page does the same), and nothing loads envs/middleware.env.
| Shows the new Agent in the web UI: the **Agents** item in the main navigation and the new Agent node in the node picker of Workflow apps. | ||
|
|
||
| Set to `false` to hide it and fall back to the classic Agent node. Replaces `ENABLE_AGENT_V2`, which still works as a fallback. | ||
| Set to `false` to hide it and fall back to the classic Agent node. |
There was a problem hiding this comment.
The PR drops the "replaces the former … / still works as a legacy alias" clauses. Some old names still work: DIFY_AGENT_SHELLCTL_AUTH_TOKEN and DIFY_AGENT_SHELLCTL_ENTRYPOINT (dify-agent/src/dify_agent/server/settings.py:75,79, template L587, dify-agent.defaults:64,66). Upgraders searching for an old name (EDITION, ENABLE_AGENT_V2, DIFY_AGENT_SHELLCTL_*, AGENT_BACKEND_RUN_TIMEOUT_SECONDS) can no longer find its successor; the env-var reference keeps one successor clause per renamed variable.
| Use your deployment's backup process to save `docker/.env`, local service `.env` files, custom Compose files, and persistent data. Preserve your working secrets and volume paths, including the explicit or stored [SECRET_KEY](/en/self-host/deploy/configuration/environments#secret_key). | ||
|
|
||
| - **Essential startup values** live in `docker/.env`, which you created from `docker/.env.example` during deployment. Edit them directly. | ||
| For the default deployment, include `docker/volumes/` and the `local_sandbox` named volumes: `dify_agent_local_sandbox_home` and `dify_agent_local_sandbox_workspace`. Use consistent database backups; a file copy while databases are writing is not a reliable backup. Include external databases and storage if you configured them. |
There was a problem hiding this comment.
"include
docker/volumes/and thelocal_sandboxnamed volumes:dify_agent_local_sandbox_homeanddify_agent_local_sandbox_workspace."
The top-level volumes have no name: (template L1384-1388), so Docker prefixes them with the project name (docker from dify/docker). A backup command using the bare names would back up a new, empty volume. Suggest: "…which Docker lists with the Compose project prefix: docker_dify_agent_local_sandbox_home and docker_dify_agent_local_sandbox_workspace by default (check with docker volume ls)."
| ## Access | ||
|
|
||
| To customize your deployment later, see [Customize](#customize). | ||
| Before exposing the deployment publicly, configure [HTTPS](/en/self-host/deploy/configuration/environments#nginx-reverse-proxy) and replace the development credentials described under [Plugin Daemon Configuration](/en/self-host/deploy/configuration/environments#plugin-daemon-configuration) and [Agent settings](/en/self-host/deploy/configuration/environments#dify_agent_server_secret_key). |
There was a problem hiding this comment.
"replace the development credentials described under Plugin Daemon Configuration and Agent settings."
The bundled defaults also ship the database and Redis password difyai123456 (db-postgres.defaults:8, redis.defaults:8), the sandbox key dify-sandbox, and the Weaviate key; docker/README.md:60-63 says to replace the bundled credentials. None of those ports is published by default. Suggest listing them: "…plus the database, Redis, sandbox (SANDBOX_API_KEY and CODE_EXECUTION_API_KEY), and Weaviate keys."
| ## Security Considerations | ||
|
|
||
| Code executes in a strict sandbox that prevents file system access, network requests, and system commands. This maintains security while providing programming flexibility. | ||
| Code runs in a separate sandbox, isolating execution from the host and other Dify services. |
There was a problem hiding this comment.
"Code runs in a separate sandbox, isolating execution from the host and other Dify services."
The sandbox shares ssrf_proxy_network with the API, WebSocket API, workers, Beat, and plugin daemon (template L568, L316, L352, L391, L421, L456, L627); docker/README.md:437-441 says services on the shared networks "can still connect directly, including the code sandbox on ssrf_proxy_network." Suggest: "Code runs in a separate sandbox container, isolated from the host's file system and processes. Its outbound requests go through the SSRF proxy, but it shares an internal network with the Dify API and plugin daemon."
Describe automatic bundled provider defaults and preserve the existing override workflow in English, Chinese, and Japanese. Clarify root Agent sandbox token placement, matching Code sandbox credentials, and architecture-independent network request restrictions.
Describe complete MySQL inputs, shared credential pairs, root override boundaries, middleware paths, and legacy variable replacements. Identify actual sandbox backup volumes and explain Code sandbox network reachability in English, Chinese, and Japanese.
Clarify provider selection, optional template copying, unchanged container mappings, and preservation of configured or stored keys without altering the English guidance.
Load middleware.env explicitly when managing Weaviate in the source-development stack. Document the Compose file and project options before the first command, and retain the existing project name across upgrades. Keep the English, Chinese, and Japanese migration instructions aligned.
Document OpenSearch certificate verification as enabled by default, require an explicit local demo-certificate opt-out, and explain that saved false overrides survive an upgrade. Preserve connections and Compose profiles for existing vector backends when choosing a new default. Explain legacy Weaviate fallbacks and continued provider override loading, with matching English, Chinese, and Japanese guidance.
Describe Docker Compose setup and customization with a minimal root
.env.example, automatically loaded service defaults, and local.envoverrides. New deployments copy the root template, generate the required Agent local sandbox token, and start withdocker compose up -d.Document the selected bundled vector store's automatic connection defaults and matching Compose profile. Explain provider overrides, external connection settings, and root
.envprecedence. Use the current Milvus, MyScale, MatrixOne, and Vastbase.defaultstemplates while preserving their existing.envpaths.Keep common API and worker settings in
api-worker.defaultsandapi-worker.env. Existingshared.envoverrides remain supported. Explain blank overrides, shared plugin credentials, and how to apply configuration changes without replacing existing secrets or persistent data.Keep the user-generated Agent local sandbox token in root
.env, shared by the Agent backend and local sandbox. Explain how to move an existing service-file token without changing its value. Document the separate Code sandbox's matching credentials and the networking requirement for Code nodes, Template nodes, Jinja2 prompts, and the built-in Code tool.Update the Docker Compose guide, environment-variable reference, Premium deployment guide, Code node deployment guidance, and Agent troubleshooting in English, Chinese, and Japanese. The Premium guide requires Compose 2.35.0 or later and uses templates from the selected release. Agent troubleshooting explains the
web.defaultstrue fallback and explicitNEXT_PUBLIC_ENABLE_AGENT_V2=falseoverrides.Aligns with langgenius/dify#45359, langgenius/dify#45376, and langgenius/dify#45407. Related to langgenius/dify#45358 and langgenius/dify#45405.