docs: update docker compose environment docs

laipz8200 · laipz8200 · commit 3dee5c739c6c · 2026-05-08T22:56:33.000+08:00
diff --git a/en/self-host/advanced-deployments/local-source-code.mdx b/en/self-host/advanced-deployments/local-source-code.mdx
@@ -1,5 +1,6 @@
 ---
 title: Local Source Code Start
+description: Run Dify locally from source with middleware services started by Docker Compose
 ---
 
 ## Prerequisites
@@ -31,11 +32,10 @@ A series of middlewares for storage (e.g. PostgreSQL / Redis / Weaviate (if not
 ```bash
 cd docker
 
-cp middleware.env.example middleware.env
+cp envs/middleware.env.example middleware.env
 
-# change the profile to mysql if you are not using postgresql
-# change the profile to other vector database if you are not using weaviate
-docker compose -f docker-compose.middleware.yaml --profile postgresql --profile weaviate -p dify up -d
+# Change DB_TYPE or COMPOSE_PROFILES in middleware.env if you are not using PostgreSQL and Weaviate.
+docker compose --env-file middleware.env -f docker-compose.middleware.yaml -p dify up -d
 ```
 
 ---
diff --git a/en/self-host/configuration/environments.mdx b/en/self-host/configuration/environments.mdx
@@ -6,9 +6,21 @@ description: Reference for all environment variables used by Dify self-hosted de
 Dify works out of the box with default settings. You can customize your deployment by modifying the environment variables in the `.env` file.
 
 <Tip>
-After upgrading Dify, run `diff .env .env.example` in the `docker` directory to check for newly added or changed variables, then update your `.env` file accordingly.
+After upgrading Dify, compare `.env` with `.env.example` in the `docker` directory. If you copied optional files under `envs/`, compare each copied `.env` file with its matching `.env.example` file.
 </Tip>
 
+## Configuration Files
+
+Docker Compose reads essential startup values from `docker/.env`, which you create from `docker/.env.example`. Optional and provider-specific variables live in `docker/envs/**/*.env.example`.
+
+To customize optional settings, copy the matching file without the `.example` suffix, then edit the copied file. For example:
+
+```bash
+cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env
+```
+
+Values in `docker/.env` take precedence over values in files under `docker/envs/`. This page lists variables from both `docker/.env.example` and the optional examples under `docker/envs/`.
+
 ## Common Variables
 
 These URL variables configure the addresses of Dify's various services.
@@ -1294,6 +1306,8 @@ These configure the Squid-based SSRF proxy container that blocks requests to int
 
 ## Docker Compose
 
+These variables stay in `docker/.env` because Docker Compose uses them to select profiles and expose ports before containers start.
+
 | Variable | Default | Description |
 |---|---|---|
 | `COMPOSE_PROFILES` | `${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql}` | Automatically selects which service containers to start based on your database and vector store choices. For example, setting `DB_TYPE=mysql` starts MySQL instead of PostgreSQL. |
@@ -1614,4 +1628,4 @@ The plugin daemon can store plugin packages in different storage backends. Confi
 | `PLUGIN_VOLCENGINE_TOS_REGION` | (empty) | Volcengine TOS region. |
 
 </Accordion>
-</AccordionGroup>
+</AccordionGroup>
diff --git a/en/self-host/platform-guides/dify-premium.mdx b/en/self-host/platform-guides/dify-premium.mdx
@@ -1,5 +1,6 @@
 ---
 title: Dify Premium on AWS
+description: Deploy, customize, and upgrade Dify Premium on AWS Marketplace
 ---
 
 Dify Premium is our AWS AMI offering that allows custom branding and is one-click deployable to your AWS VPC as an EC2 instance. Head to [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-t22mebxzwjhu6) to subscribe. It's useful in a couple of scenarios:
@@ -21,8 +22,8 @@ If this is your first time accessing Dify, enter the Admin initialization passwo
 Just like a self-hosted deployment, you may modify the environment variables in the `.env` file in your EC2 instance as you see fit. Then, restart Dify with:
 
 ```bash
-docker-compose down
-docker-compose -f docker-compose.yaml -f docker-compose.override.yaml up -d
+docker compose down
+docker compose -f docker-compose.yaml -f docker-compose.override.yaml up -d
 ```
 
 ### Web App Logo & Branding
@@ -41,7 +42,7 @@ In the EC2 instance, run the following commands:
     <Step title="Stop the Running Services">
         ```bash
         cd /dify
-        docker-compose down
+        docker compose down
         ```
     </Step>
     <Step title="Back Up Your Data">
@@ -68,16 +69,16 @@ In the EC2 instance, run the following commands:
         ```
     </Step>
     <Step title="Check for New Environment Variables">
-        New versions may introduce new environment variables in `.env.example`. Compare it with your current `.env` and add any missing variables:
+        New versions may introduce variables in `.env.example` or optional examples under `envs/`. Compare `.env` with `.env.example`, and repeat the comparison for any copied `envs/**/*.env` file against its matching `.env.example` file:
 
         ```bash
         diff /dify/.env /dify/.env.example
         ```
     </Step>
     <Step title="Start Services">
         ```bash
-        docker-compose pull
-        docker-compose -f docker-compose.yaml -f docker-compose.override.yaml up -d
+        docker compose pull
+        docker compose -f docker-compose.yaml -f docker-compose.override.yaml up -d
         ```
     </Step>
-</Steps>
+</Steps>
diff --git a/en/self-host/quick-start/docker-compose.mdx b/en/self-host/quick-start/docker-compose.mdx
@@ -1,6 +1,7 @@
 ---
 title: Deploy Dify with Docker Compose
 sidebarTitle: Docker Compose
+description: Install and start Dify Community Edition with Docker Compose
 ---
 
 <Tip>
@@ -18,11 +19,11 @@ Make sure your machine meets the following minimum system requirements.
 
 ### Software
 
-| Operating System              | Required Software                        | Notes |  
-| :----------------------------- | :---------------------------------------- | :----- |  
-| macOS 10.14 or later          | Docker Desktop                           | Configure the Docker virtual machine with at least 2 virtual CPUs and 8 GiB of memory. <br></br><br></br>For installation instructions, see [Install Docker Desktop on Mac](https://docs.docker.com/desktop/mac/install/). |  
-| Linux distributions           | Docker 19.03+<br></br><br></br>Docker Compose 1.28+ | For installation instructions, see [Install Docker Engine](https://docs.docker.com/engine/install/) and [Install Docker Compose](https://docs.docker.com/compose/install/). |  
-| Windows with WSL 2 enabled    | Docker Desktop                           | Store source code and data bound to Linux containers in the Linux file system rather than Windows. <br></br><br></br>For installation instructions, see [Install Docker Desktop on Windows](https://docs.docker.com/desktop/windows/install/#wsl-2-backend). |  
+| Operating System              | Required Software                        | Notes |
+| :----------------------------- | :---------------------------------------- | :----- |
+| macOS 10.14 or later          | Docker Desktop with Docker Compose 2.24.0+ | Configure the Docker virtual machine with at least 2 virtual CPUs and 8 GiB of memory. <br></br><br></br>For installation instructions, see [Install Docker Desktop on Mac](https://docs.docker.com/desktop/mac/install/). |
+| Linux distributions           | Docker 19.03+<br></br><br></br>Docker Compose 2.24.0+ | For installation instructions, see [Install Docker Engine](https://docs.docker.com/engine/install/) and [Install Docker Compose](https://docs.docker.com/compose/install/). |
+| Windows with WSL 2 enabled    | Docker Desktop with Docker Compose 2.24.0+ | Store source code and data bound to Linux containers in the Linux file system rather than Windows. <br></br><br></br>For installation instructions, see [Install Docker Desktop on Windows](https://docs.docker.com/desktop/windows/install/#wsl-2-backend). |
 
 
 ## Deploy and Start
@@ -46,22 +47,19 @@ Make sure your machine meets the following minimum system requirements.
     2. Copy the example environment configuration file:
 
         ```bash
-        cp .env.example .env  
+        cp .env.example .env
         ```
 
-    3. Start the containers using the command that matches your Docker Compose version:
+        The root `.env` file contains the essential startup values. Optional and provider-specific settings live under `envs/` as `.env.example` files. Copy only the files you need without the `.example` suffix before editing those advanced settings.
 
-        <CodeGroup>
-          ```bash Docker Compose V2
-          docker compose up -d
-          ```
-          ```bash Docker Compose V1
-          docker-compose up -d
-          ```
-        </CodeGroup>
+    3. Start the containers:
+
+        ```bash
+        docker compose up -d
+        ```
 
         <Tip>
-          Run `docker compose version` to check your Docker Compose version.
+          Dify uses optional Compose `env_file` entries. Run `docker compose version` and make sure your Docker Compose version is 2.24.0 or later.
         </Tip>        
 
         The following containers will be started:
@@ -137,13 +135,21 @@ Make sure your machine meets the following minimum system requirements.
 
 ## Customize
 
-Modify the environment variable values in your local `.env` file, then restart Dify to apply the changes:
+Modify environment variables in your local `.env` file, then restart Dify to apply the changes:
 
 ```bash
 docker compose down
 docker compose up -d
 ```
 
+For optional or provider-specific settings, copy the matching file from `envs/` without the `.example` suffix, then edit the copied file. For example:
+
+```bash
+cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env
+```
+
+Values in `.env` take precedence over values in files under `envs/`.
+
 <Tip>
   For more information, see [environment variables](/en/self-host/configuration/environments).
 </Tip>
@@ -154,6 +160,6 @@ Upgrade steps may vary between releases. Refer to the upgrade guide for your tar
 
 <Note>
 
-  After upgrading, check whether the `.env.example` file has changed and update your local `.env` file accordingly.
+  After upgrading, check whether `.env.example` or any copied `envs/**/*.env.example` files have changed, then update your local `.env` and optional `envs/**/*.env` files accordingly.
 
-</Note>
+</Note>
diff --git a/en/self-host/troubleshooting/common-issues.mdx b/en/self-host/troubleshooting/common-issues.mdx
@@ -1,5 +1,6 @@
 ---
 title: Common Issues
+description: Resolve common authentication, configuration, database, and workspace issues in self-hosted Dify
 ---
 
 ## Authentication & Access
@@ -41,7 +42,7 @@ EXPOSE_NGINX_PORT=80
 EXPOSE_NGINX_SSL_PORT=443
 ```
 
-For API service port changes, update the nginx configuration in `docker-compose.yaml`.
+For API service port changes, update the Nginx configuration under `docker/nginx/conf.d/`.
 
 ### Increase file upload limits
 
@@ -91,7 +92,7 @@ Allow connections from the error's network segment:
 
 ```bash
 docker exec -it docker-db-1 sh -c "echo 'host all all 172.19.0.0/16 trust' >> /var/lib/postgresql/data/pgdata/pg_hba.conf"
-docker-compose restart
+docker compose restart
 ```
 
 ### File not found error for encryption keys
@@ -125,4 +126,4 @@ Modify the `tenants` table in the database directly.
 
 ### Change application access domain
 
-Update `APP_WEB_URL` in `docker-compose.yaml`.
+Update `APP_WEB_URL` in `.env`, then restart Dify.
diff --git a/en/self-host/troubleshooting/docker-issues.mdx b/en/self-host/troubleshooting/docker-issues.mdx
@@ -1,5 +1,6 @@
 ---
 title: Docker Issues
+description: Resolve common Docker Compose networking, volume, port, and container issues in self-hosted Dify
 ---
 
 ## Network & Connectivity
@@ -32,7 +33,7 @@ Example: For OpenLLM running on host, configure Dify with `http://192.168.1.100:
 
 ### Page loads forever with CORS errors
 
-Domain/URL changes cause cross-origin issues. Update in `docker-compose.yml`:
+Domain or URL changes can cause cross-origin issues. Update these values in `.env`:
 
 - `CONSOLE_API_URL` - Backend URL for console API
 - `CONSOLE_WEB_URL` - Frontend URL for console web
@@ -67,11 +68,7 @@ Port 80 already in use? Either:
    sudo service apache2 stop
    ```
 
-2. Or change port mapping in `docker-compose.yaml`:
-   ```yaml
-   ports:
-     - "8080:80"  # Map to different port
-   ```
+2. Or change `EXPOSE_NGINX_PORT` in `.env`, then restart Dify.
 
 ## Container Management
 
diff --git a/en/self-host/troubleshooting/storage-and-migration.mdx b/en/self-host/troubleshooting/storage-and-migration.mdx
@@ -1,5 +1,6 @@
 ---
 title: Storage & Migration
+description: Migrate vector databases, storage backends, and stored data in self-hosted Dify
 ---
 
 ## Vector Database Migration
@@ -13,9 +14,9 @@ title: Storage & Migration
    VECTOR_STORE=qdrant
    ```
 
-   Docker Compose (`docker-compose.yaml`):
-   ```yaml
-   VECTOR_STORE: qdrant
+   Docker Compose (`.env`):
+   ```text
+   VECTOR_STORE=qdrant
    ```
 
 2. **Run migration**
@@ -38,8 +39,8 @@ Migrate files from local storage to cloud providers (e.g., Alibaba Cloud OSS):
 
 1. **Configure cloud storage**
 
-   `.env` or `docker-compose.yaml`:
-   ```
+   `.env`:
+   ```text
    STORAGE_TYPE=aliyun-oss
    # Add OSS credentials
    ```
diff --git a/en/self-host/troubleshooting/weaviate-v4-migration.mdx b/en/self-host/troubleshooting/weaviate-v4-migration.mdx
@@ -1,5 +1,6 @@
 ---
 title: Weaviate Migration Guide upgrading to Client v4 and Server 1.27+
+description: Upgrade Weaviate server and migrate data for Dify deployments that use weaviate-client v4
 ---
 
 > This guide explains how to migrate from Weaviate client v3 to v4.17.0 and upgrade your Weaviate server from version 1.19.0 to 1.27.0 or higher. This migration is required for Dify versions that include the weaviate-client v4 upgrade.
@@ -137,7 +138,7 @@ Restart Weaviate to apply the change:
 ```bash
 cd docker
 docker compose down
-docker compose --profile up -d
+docker compose up -d
 sleep 10
 ```
 
diff --git a/ja/self-host/configuration/environments.mdx b/ja/self-host/configuration/environments.mdx
@@ -8,9 +8,21 @@ description: Dify セルフホストデプロイで使用されるすべての
 Dify はデフォルト設定でそのまま動作します。`.env` ファイルの環境変数を変更することで、デプロイをカスタマイズできます。
 
 <Tip>
-Dify をアップグレードした後、`docker`ディレクトリで `diff .env .env.example`を実行して、新しく追加または変更された変数を確認し、`.env` ファイルを適宜更新してください。
+Dify をアップグレードした後、`docker` ディレクトリで `.env` と `.env.example` を比較してください。`envs/` 配下の任意ファイルをコピーしている場合は、コピー済みの各 `.env` ファイルを対応する `.env.example` ファイルと比較してください。
 </Tip>
 
+## 設定ファイル
+
+Docker Compose は、`docker/.env.example` から作成した `docker/.env` から基本的な起動値を読み込みます。任意設定やプロバイダー固有の変数は `docker/envs/**/*.env.example` にあります。
+
+任意設定をカスタマイズするには、該当ファイルを `.example` サフィックスなしでコピーしてから、コピーしたファイルを編集します。例：
+
+```bash
+cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env
+```
+
+`docker/.env` の値は、`docker/envs/` 配下のファイルの値より優先されます。このページでは、`docker/.env.example` と `docker/envs/` 配下の任意サンプルファイルの両方にある変数を一覧しています。
+
 ## 共通変数
 
 これらの URL 変数は、Dify の各サービスのアドレスを設定します。
@@ -1296,6 +1308,8 @@ HTTPS を有効化した後、 [共通変数](#共通変数) の URL 変数（
 
 ## Docker Compose
 
+これらの変数は、コンテナ起動前に Docker Compose が Compose profiles の選択とポート公開に使用するため、`docker/.env` に残ります。
+
 | 変数 | デフォルト値 | 説明 |
 |---|---|---|
 | `COMPOSE_PROFILES` | `${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql}` | データベースとベクトルストアの選択に基づいて、起動するサービスコンテナを自動選択します。例えば、`DB_TYPE=mysql` を設定すると PostgreSQL の代わりに MySQL が起動します。 |
@@ -1616,4 +1630,4 @@ API と Celery ワーカー間の Redis ベースのイベント転送です。
 | `PLUGIN_VOLCENGINE_TOS_REGION` | （空） | Volcengine TOS リージョン。 |
 
 </Accordion>
-</AccordionGroup>
+</AccordionGroup>
diff --git a/zh/self-host/configuration/environments.mdx b/zh/self-host/configuration/environments.mdx
@@ -8,9 +8,21 @@ description: Dify 自托管部署使用的所有环境变量参考
 Dify 使用默认配置即可开箱即用。你可以通过修改 `.env` 文件中的环境变量来自定义部署。
 
 <Tip>
-升级 Dify 后，在 `docker` 目录下运行 `diff .env .env.example` 检查新增或变更的变量，然后相应更新你的 `.env` 文件。
+升级 Dify 后，在 `docker` 目录中比较 `.env` 和 `.env.example`。如果你复制了 `envs/` 下的可选文件，请将每个复制出的 `.env` 文件与对应的 `.env.example` 文件进行比较。
 </Tip>
 
+## 配置文件
+
+Docker Compose 从 `docker/.env` 读取基础启动值，该文件由 `docker/.env.example` 复制而来。可选变量和特定供应商变量位于 `docker/envs/**/*.env.example`。
+
+如需自定义可选设置，请复制对应文件并去掉 `.example` 后缀，然后编辑复制出的文件。例如：
+
+```bash
+cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env
+```
+
+`docker/.env` 中的值优先于 `docker/envs/` 下文件中的值。本页同时列出 `docker/.env.example` 和 `docker/envs/` 下可选示例文件中的变量。
+
 ## 通用变量
 
 这些 URL 变量用于配置 Dify 各服务的访问地址。
@@ -1296,6 +1308,8 @@ Dify 的所有出站 HTTP 请求（HTTP 节点、图片下载等）都通过代
 
 ## Docker Compose
 
+这些变量保留在 `docker/.env` 中，因为 Docker Compose 会在容器启动前使用它们选择 Compose profiles 并暴露端口。
+
 | 变量 | 默认值 | 说明 |
 |---|---|---|
 | `COMPOSE_PROFILES` | `${VECTOR_STORE:-weaviate},${DB_TYPE:-postgresql}` | 根据你的数据库和向量存储选择自动决定启动哪些服务容器。例如设置 `DB_TYPE=mysql` 将启动 MySQL 而非 PostgreSQL。 |
