You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude/skills/dify-docs-guides/SKILL.md
+49Lines changed: 49 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,6 +55,55 @@ This is a team effort. The user brings documentation expertise and user empathy;
55
55
- Trust the codebase over existing documentation. Existing docs may be outdated or inaccurate.
56
56
-**Code presence ≠ working feature.** A code path existing does not guarantee the feature functions end to end. When behavior is inferred from code analysis rather than observed in the running product, flag it as unverified and ask the user to test before documenting it as fact.
57
57
58
+
## Environment Variables in User Guides
59
+
60
+
When a feature is gated by or configured through environment variables (feature toggles, endpoints, self-host-only switches, worker classes), coordinate with the reference doc instead of duplicating it.
61
+
62
+
### Investigate first
63
+
64
+
During feature research, check whether the feature has related environment variables:
65
+
66
+
- Grep `docker/.env.example`, `api/configs/`, and the feature's PR for any `ENABLE_*`, `*_URL`, worker, or socket settings tied to the feature.
67
+
- Note which variables are mandatory vs. optional, and what their defaults are.
68
+
69
+
If the feature has related variables, use the `dify-docs-env-vars` skill to update `en/self-host/configuration/environments.mdx` in the same session. The reference doc is the single source of truth for variable semantics.
70
+
71
+
### Division of responsibility
72
+
73
+
-**Environment Variable Reference** (`en/self-host/configuration/environments.mdx`): exhaustive. Every variable gets a description covering purpose, defaults, interactions, and failure modes. Maintained via the `dify-docs-env-vars` skill.
74
+
-**User Guide**: functional only. Name the mandatory variables and the values to set, then link to the reference. Do not re-explain the mechanism (WebSocket paths, worker classes, scheme rules, fallback behavior). Those details live in the reference.
75
+
76
+
### How to present in the User Guide
77
+
78
+
User Guides serve both SaaS (Dify Cloud) and self-hosted readers. Place self-host-only configuration in a callout rather than a dedicated H2 section. The callout surfaces the information clearly for self-hosters while letting SaaS readers skip past it without breaking the flow of the guide.
79
+
80
+
Choose the callout type by what the variables do:
81
+
82
+
-**`<Note>`** — when the variables are **mandatory** for the feature to work. Without them, self-hosters will not be able to use the feature at all. Example: `ENABLE_COLLABORATION_MODE` gates the entire collaboration feature.
83
+
-**`<Info>`** — when the variables only **customize** existing behavior (tuning a default, switching backends, adjusting an endpoint). The feature works without them; these are optional knobs.
84
+
85
+
Pattern (substitute `<Note>` or `<Info>` per the rule above):
86
+
87
+
```mdx
88
+
<Note>
89
+
On self-hosted deployments, [feature] is turned off by default. Enable it by setting:
90
+
91
+
-`VAR_NAME` = `value`
92
+
- ...
93
+
94
+
See [Environment Variables](/en/self-host/configuration/environments#var_name) for details.
95
+
</Note>
96
+
```
97
+
98
+
Do not promote self-host config to an H2 section. Giving deployment-specific content equal weight with product-facing content clutters the guide for SaaS readers, who are the majority of the audience.
99
+
100
+
### What to exclude from the User Guide
101
+
102
+
- Default values already covered in the reference.
103
+
- The "why" behind each variable: worker types, proxy paths, scheme rules, fallback behavior.
104
+
- Custom-domain examples, deployment-specific mechanics, or variable interactions.
105
+
- Anything a reader could find by clicking through to the reference.
106
+
58
107
## Style Overrides
59
108
60
109
No overrides. Follow `writing-guides/style-guide.md` as written.
Copy file name to clipboardExpand all lines: en/self-host/configuration/environments.mdx
+15-1Lines changed: 15 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,19 @@ Default: `300` (5 minutes)
91
91
92
92
How long signed file URLs remain valid, in seconds. After this time, the URL is rejected and the file must be re-requested. Increase for long-running processes; decrease for tighter security.
93
93
94
+
### ENABLE_COLLABORATION_MODE
95
+
96
+
Default: `false`
97
+
98
+
Master switch for real-time collaboration on the Workflow canvas, covering simultaneous editing, in-canvas comments, and @mentions.
99
+
100
+
Setting this alone is not sufficient. Collaboration runs over WebSocket, which also requires:
101
+
102
+
-`SERVER_WORKER_CLASS` set to `geventwebsocket.gunicorn.workers.GeventWebSocketWorker` (see [Container Startup Configuration](#container-startup-configuration)).
103
+
-`NEXT_PUBLIC_SOCKET_URL` set to a WebSocket URL your browser can reach (see [CORS Configuration](#cors-configuration)).
104
+
105
+
If you use your own reverse proxy, forward `Upgrade` and `Connection` headers on `/socket.io/` (the bundled nginx template already does this). Running multiple API replicas requires sticky sessions.
106
+
94
107
### System Encoding
95
108
96
109
| Variable | Default | Description |
@@ -165,7 +178,7 @@ Only effective when starting with Docker image or Docker Compose.
165
178
|`DIFY_BIND_ADDRESS`|`0.0.0.0`| Network interface the API server binds to. `0.0.0.0` listens on all interfaces; set to `127.0.0.1` to restrict to localhost only. |
166
179
|`DIFY_PORT`|`5001`| Port the API server listens on. |
167
180
|`SERVER_WORKER_AMOUNT`|`1`| Number of Gunicorn worker processes. With gevent (default), each worker handles multiple concurrent connections via greenlets, so 1 is usually sufficient. For sync workers, use `(2 x CPU cores) + 1`. [Reference](https://gunicorn.org/design/#how-many-workers). |
168
-
|`SERVER_WORKER_CLASS`|`gevent`| Gunicorn worker type. Gevent provides lightweight async concurrency. Changing this breaks psycopg2 and gRPC patching—it is strongly discouraged. |
181
+
|`SERVER_WORKER_CLASS`|`gevent`| Gunicorn worker type. `gevent` provides lightweight async concurrency. Set to `geventwebsocket.gunicorn.workers.GeventWebSocketWorker` when `ENABLE_COLLABORATION_MODE` is `true`; left at `gevent`, WebSocket handshakes fail silently. Other values break psycopg2 and gRPC patching. |
169
182
|`SERVER_WORKER_CONNECTIONS`|`10`| Maximum concurrent connections per worker. Only applies to async workers (gevent). If you experience connection rejections or slow responses under load, try increasing this value. |
170
183
|`GUNICORN_TIMEOUT`|`360`| If a worker doesn't respond within this many seconds, Gunicorn kills and restarts it. Set to 360 (6 minutes) to support long-lived SSE connections used for streaming LLM responses. |
171
184
|`CELERY_WORKER_CLASS`| (empty; defaults to gevent) | Celery worker type. Same gevent patching requirements as `SERVER_WORKER_CLASS`—it is strongly discouraged to change. |
@@ -321,6 +334,7 @@ Controls cross-domain access policies for the frontend.
321
334
|`CONSOLE_CORS_ALLOW_ORIGINS`|`*`| Allowed origins for cross-origin requests to the console API. If not set, falls back to `CONSOLE_WEB_URL`. |
322
335
|`COOKIE_DOMAIN`| (empty) | Set to the shared top-level domain (e.g., `example.com`) when frontend and backend run on different subdomains. This allows authentication cookies to be shared across subdomains. When empty, cookies use the most secure `__Host-` prefix and are locked to a single domain. |
323
336
|`NEXT_PUBLIC_COOKIE_DOMAIN`| (empty) | Frontend flag for cross-subdomain cookies. Set to `1` (or any non-empty value) to enable—the actual domain is read from `COOKIE_DOMAIN` on the backend. |
337
+
|`NEXT_PUBLIC_SOCKET_URL`|`ws://localhost`| Browser-side WebSocket endpoint for real-time collaboration. Scheme + host + port only (path `/socket.io/` is fixed). Swap `http(s)://` for `ws(s)://`. Example: `wss://dify.example.com`. The default targets the bundled nginx on port 80. Applied at runtime; container restart picks up changes. |
324
338
|`NEXT_PUBLIC_BATCH_CONCURRENCY`|`5`| Frontend-only. Controls how many concurrent API calls the UI makes during batch operations. |
description: Edit workflows with teammates in real time and discuss design decisions through in-canvas comments
4
+
sidebarTitle: Collaboration
5
+
---
6
+
7
+
Building a workflow sometimes takes more than one person: a prompt engineer tuning instructions, a domain expert validating logic, a reviewer flagging edge cases.
8
+
9
+
Rather than taking turns, you can edit the same workflow alongside your teammates and leave comments directly on the canvas, so the discussion stays with the work.
10
+
11
+
<Tip>
12
+
Comments and collaborator cursors can be hidden from the zoom menu in the bottom-right corner of the canvas.
13
+
14
+
<Frame>
15
+
16
+
</Frame>
17
+
</Tip>
18
+
19
+
## Real-Time Editing
20
+
21
+
Workspace members with editor permissions or above can edit the same workflow simultaneously. When two members change the same element at the same time, the last edit wins.
22
+
23
+
## Comments
24
+
25
+
Right-click an empty area of the canvas and select **Add Comment** to leave a note. To drop multiple comments in a row, press `C` to enter comment mode. Comments persist across workflow versions.
26
+
27
+
If you @mention a teammate in a comment, they'll receive an email notification.
28
+
29
+
Anyone with access to the app can read comments; adding, editing, or resolving requires editor permissions or above.
30
+
31
+
<Note>
32
+
On self-hosted deployments, collaboration is turned off by default. Enable it by setting:
0 commit comments