From 71280085480fdb6f7daefe0a685cc4088751f196 Mon Sep 17 00:00:00 2001 From: Riskey Date: Sat, 6 Dec 2025 00:05:06 +0800 Subject: [PATCH] update the note for when the frontend and backend run on different subdomains --- .../local-source-code.mdx | 43 +++++++++------- en/self-host/configuration/environments.mdx | 15 +++++- en/self-host/quick-start/docker-compose.mdx | 49 ++++++++++--------- 3 files changed, 66 insertions(+), 41 deletions(-) diff --git a/en/self-host/advanced-deployments/local-source-code.mdx b/en/self-host/advanced-deployments/local-source-code.mdx index bf1cedef..5292c9ab 100644 --- a/en/self-host/advanced-deployments/local-source-code.mdx +++ b/en/self-host/advanced-deployments/local-source-code.mdx @@ -44,7 +44,7 @@ The backend services include 2. Worker Service: serving the aync tasks for datasets processing, workspaces, cleaning-ups etc. -### Start API service +### Start API Service 1. Navigate to the `api` directory: @@ -52,19 +52,25 @@ The backend services include cd api ``` -2. Prepare the environment variable config file +2. Prepare the environment variable config file: ``` cp .env.example .env ``` -3. Generate a random secret key and replace the value of SECRET_KEY in the .env file + + When the frontend and backend run on different subdomains, set `COOKIE_DOMAIN` to the site's top-level domain (e.g., `example.com`) in the `.env` file. + + The frontend and backend must be under the same top-level domain to share authentication cookies. + + +3. Generate a random secret key and replace the value of SECRET_KEY in the `.env` file: ``` awk -v key="$(openssl rand -base64 42)" '/^SECRET_KEY=/ {sub(/=.*/, "=" key)} 1' .env > temp_env && mv temp_env .env ``` -4. Dependencies installation +4. Install dependencies: [uv](https://docs.astral.sh/uv/getting-started/installation/) is used to manage dependencies. Install the required dependencies with `uv` by running: @@ -73,7 +79,7 @@ The backend services include ``` > For macOS: install libmagic with `brew install libmagic`. -5. Perform the database migration +5. Perform the database migration: Perform database migrations to the latest version: @@ -81,7 +87,7 @@ The backend services include uv run flask db upgrade ``` -6. Start the API service +6. Start the API service: ``` uv run flask run --host 0.0.0.0 --port=5001 --debug @@ -99,7 +105,7 @@ The backend services include INFO:werkzeug: * Debugger PIN: 695-801-919 ``` -### Start the Worker service +### Start the Worker Service To consume asynchronous tasks from the queue, such as dataset file import and dataset document updates, follow these steps to start the Worker service @@ -206,49 +212,52 @@ To start the web frontend service, [Node.js v22 (LTS)](http://nodejs.org/) and [ ### Start Web Service -1. Enter the web directory +1. Enter the web directory: ``` cd web ``` -2. Dependencies installation +2. Install dependencies: ``` pnpm install --frozen-lockfile ``` -3. Prepare the environment variable config file - +3. Prepare the environment variable configuration file\ Create a file named `.env.local` in the current directory and copy the contents from `.env.example`. Modify the values of these environment variables according to your requirements: ``` # For production release, change this to PRODUCTION NEXT_PUBLIC_DEPLOY_ENV=DEVELOPMENT + # The deployment edition, SELF_HOSTED or CLOUD NEXT_PUBLIC_EDITION=SELF_HOSTED - # The base URL of console application, refers to the Console base URL of WEB service if console domain is - # different from api or web app domain. + + # The base URL of console application, refers to the Console base URL of WEB service if console domain is different from api or web app domain. # example: http://cloud.dify.ai/console/api NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api - # 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. + + # 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 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= + # SENTRY NEXT_PUBLIC_SENTRY_DSN= NEXT_PUBLIC_SENTRY_ORG= NEXT_PUBLIC_SENTRY_PROJECT= ``` -4. Build the web service +4. Build the web service: ``` pnpm build ``` -5. Start the web service +5. Start the web service: ``` pnpm start diff --git a/en/self-host/configuration/environments.mdx b/en/self-host/configuration/environments.mdx index 6469420e..a16d8203 100644 --- a/en/self-host/configuration/environments.mdx +++ b/en/self-host/configuration/environments.mdx @@ -184,8 +184,19 @@ This Redis configuration is used for caching and for pub/sub during conversation Used to set the front-end cross-domain access policy. -- CONSOLE_CORS_ALLOW_ORIGINS: Console CORS cross-domain policy, default is `*`, that is, all domains can access. -- WEB_API_CORS_ALLOW_ORIGINS: WebAPP CORS cross-domain policy, default is `*`, that is, all domains can access. +- CONSOLE_CORS_ALLOW_ORIGINS\ + Console CORS cross-domain policy, default is `*`, that is, all domains can access. + +- WEB_API_CORS_ALLOW_ORIGINS\ + WebAPP CORS cross-domain policy, default is `*`, that is, all domains can access. + +- COOKIE_DOMAIN\ + 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 to share authentication cookies. + +- NEXT_PUBLIC_COOKIE_DOMAIN\ + When the frontend and backend run on different subdomains, set `NEXT_PUBLIC_COOKIE_DOMAIN` to `1`.\ + The frontend and backend must be under the same top-level domain to share authentication cookies. ### File Storage Configuration diff --git a/en/self-host/quick-start/docker-compose.mdx b/en/self-host/quick-start/docker-compose.mdx index 37ed7728..c0d72c72 100644 --- a/en/self-host/quick-start/docker-compose.mdx +++ b/en/self-host/quick-start/docker-compose.mdx @@ -39,22 +39,23 @@ Make sure your machine meets the following minimum system requirements. 1. Navigate to the `docker` directory in the Dify source code: - ```bash - cd dify/docker - ``` + ```bash + cd dify/docker + ``` 2. Copy the example environment configuration file: - ```bash - cp .env.example .env - ``` + ```bash + cp .env.example .env + ``` + + When the frontend and backend run on different subdomains, set `COOKIE_DOMAIN` to the site's top-level domain (e.g., `example.com`) and set `NEXT_PUBLIC_COOKIE_DOMAIN` to `1` in the .`env` file. + + The frontend and backend must be under the same top-level domain to share authentication cookies. + 3. Start the containers using the command that matches your Docker Compose version: - - Run `docker compose version` to check your Docker Compose version. - - ```bash Docker Compose V2 docker compose up -d @@ -64,6 +65,10 @@ Make sure your machine meets the following minimum system requirements. ``` + + Run `docker compose version` to check your Docker Compose version. + + The following containers will be started: - 5 core services: `api`, `worker`, `worker_beat`, `web`, `plugin_daemon` @@ -117,23 +122,23 @@ Make sure your machine meets the following minimum system requirements. 1. Open the administrator initialization page to set up the admin account: -```bash -# Local environment -http://localhost/install + ```bash + # Local environment + http://localhost/install -# Server environment -http://your_server_ip/install -``` + # Server environment + http://your_server_ip/install + ``` 2. After completing the admin account setup, log in to Dify at: -```bash -# Local environment -http://localhost + ```bash + # Local environment + http://localhost -# Server environment -http://your_server_ip -``` + # Server environment + http://your_server_ip + ``` ## Customize Dify