From e83c7438cbc14e5ad48cafa17b615694d10ad4d0 Mon Sep 17 00:00:00 2001
From: Joel <iamjoel007@gmail.com>
Date: Tue, 18 Nov 2025 17:29:54 +0800
Subject: [PATCH] doc: add doc for env config when site and backend are in
 different domains (#28318)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 api/.env.example    | 3 +--
 api/README.md       | 4 ++++
 docker/.env.example | 5 ++---
 web/.env.example    | 6 +++---
 web/README.md       | 6 ++++++
 5 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/api/.env.example b/api/.env.example
index b1ac15d25b..5713095374 100644
--- a/api/.env.example
+++ b/api/.env.example
@@ -159,8 +159,7 @@ SUPABASE_URL=your-server-url
 # CORS configuration
 WEB_API_CORS_ALLOW_ORIGINS=http://localhost:3000,*
 CONSOLE_CORS_ALLOW_ORIGINS=http://localhost:3000,*
-# Set COOKIE_DOMAIN when the console frontend and API are on different subdomains.
-# Provide the registrable domain (e.g. example.com); leading dots are optional.
+# When the frontend and backend run on different subdomains, set COOKIE_DOMAIN to the site’s top-level domain (e.g., `example.com`). Leading dots are optional.
 COOKIE_DOMAIN=
 
 # Vector database configuration
diff --git a/api/README.md b/api/README.md
index 45dad07af0..7809ea8a3d 100644
--- a/api/README.md
+++ b/api/README.md
@@ -26,6 +26,10 @@
    cp .env.example .env
    ```
 
+> [!IMPORTANT]
+>
+> When the frontend and backend run on different subdomains, set COOKIE_DOMAIN to the site’s top-level domain (e.g., `example.com`). The frontend and backend must be under the same top-level domain in order to share authentication cookies.
+
 1. Generate a `SECRET_KEY` in the `.env` file.
 
    bash for Linux
diff --git a/docker/.env.example b/docker/.env.example
index 519f4aa3e0..5cb948d835 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -365,10 +365,9 @@ WEB_API_CORS_ALLOW_ORIGINS=*
 # Specifies the allowed origins for cross-origin requests to the console API,
 # e.g. https://cloud.dify.ai or * for all origins.
 CONSOLE_CORS_ALLOW_ORIGINS=*
-# Set COOKIE_DOMAIN when the console frontend and API are on different subdomains.
-# Provide the registrable domain (e.g. example.com); leading dots are optional.
+# When the frontend and backend run on different subdomains, set COOKIE_DOMAIN to the site’s top-level domain (e.g., `example.com`). Leading dots are optional.
 COOKIE_DOMAIN=
-# The frontend reads NEXT_PUBLIC_COOKIE_DOMAIN to align cookie handling with the API.
+# When the frontend and backend run on different subdomains, set NEXT_PUBLIC_COOKIE_DOMAIN=1.
 NEXT_PUBLIC_COOKIE_DOMAIN=
 
 # ------------------------------
diff --git a/web/.env.example b/web/.env.example
index 5bfcc9dac0..eff6f77fd9 100644
--- a/web/.env.example
+++ b/web/.env.example
@@ -12,6 +12,9 @@ NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
 # console or api domain.
 # example: http://udify.app/api
 NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
+# When the frontend and backend run on different subdomains, set NEXT_PUBLIC_COOKIE_DOMAIN=1.
+NEXT_PUBLIC_COOKIE_DOMAIN=
+
 # The API PREFIX for MARKETPLACE
 NEXT_PUBLIC_MARKETPLACE_API_PREFIX=https://marketplace.dify.ai/api/v1
 # The URL for MARKETPLACE
@@ -34,9 +37,6 @@ NEXT_PUBLIC_CSP_WHITELIST=
 # Default is not allow to embed into iframe to prevent Clickjacking: https://owasp.org/www-community/attacks/Clickjacking
 NEXT_PUBLIC_ALLOW_EMBED=
 
-# Shared cookie domain when console UI and API use different subdomains (e.g. example.com)
-NEXT_PUBLIC_COOKIE_DOMAIN=
-
 # Allow rendering unsafe URLs which have "data:" scheme.
 NEXT_PUBLIC_ALLOW_UNSAFE_DATA_SCHEME=false
 
diff --git a/web/README.md b/web/README.md
index a47cfab041..6daf1e922e 100644
--- a/web/README.md
+++ b/web/README.md
@@ -32,6 +32,7 @@ NEXT_PUBLIC_EDITION=SELF_HOSTED
 # different from api or web app domain.
 # example: http://cloud.dify.ai/console/api
 NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
+NEXT_PUBLIC_COOKIE_DOMAIN=
 # The URL for Web APP, refers to the Web App base URL of WEB service if web app domain is different from
 # console or api domain.
 # example: http://udify.app/api
@@ -41,6 +42,11 @@ NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
 NEXT_PUBLIC_SENTRY_DSN=
 ```
 
+> [!IMPORTANT]
+>
+> 1. When the frontend and backend run on different subdomains, set NEXT_PUBLIC_COOKIE_DOMAIN=1. The frontend and backend must be under the same top-level domain in order to share authentication cookies.
+> 1. It's necessary to set NEXT_PUBLIC_API_PREFIX and NEXT_PUBLIC_PUBLIC_API_PREFIX to the correct backend API URL.
+
 Finally, run the development server:
 
 ```bash