Skip to content

fix: document COLLAB_EMBEDDED_WS=true requirement for local self-hosting#56

Open
jessems wants to merge 1 commit into
EveryInc:mainfrom
jessems:fix/collab-embedded-ws-local
Open

fix: document COLLAB_EMBEDDED_WS=true requirement for local self-hosting#56
jessems wants to merge 1 commit into
EveryInc:mainfrom
jessems:fix/collab-embedded-ws-local

Conversation

@jessems

@jessems jessems commented Jun 9, 2026

Copy link
Copy Markdown

Summary

  • When running on localhost without COLLAB_EMBEDDED_WS=true, the server calculates the collab WebSocket URL as PORT+1 (4001 by default) rather than the actual server port (4000).
  • Nothing runs on port 4001, so the editor silently stays in "connecting" state indefinitely with no error message surfaced to the user.
  • The embedded collab runtime logs wsUrlBase=ws://localhost:4000/ws at startup, but the URL served to clients points elsewhere — the mismatch is invisible without inspecting the /collab-session API response.

Root cause

In server/routes.ts, resolveRequestScopedCollabWsBase defaults to appPort + 1 for loopback hosts unless COLLAB_EMBEDDED_WS is set, because in the hosted deployment the collab runtime runs as a separate process on a different port. For self-hosted local use, the runtime is always embedded and the env var must be set explicitly.

Fix

  • Add COLLAB_EMBEDDED_WS=true to .env.example with an explanation.
  • Update the README quickstart npm run serve command to include it.

Reproduction

npm install && npm run build
npm run serve   # without COLLAB_EMBEDDED_WS
# create a doc, open it in browser → "connecting" forever
curl http://localhost:4000/documents/<slug>/collab-session | grep collabWsUrl
# → ws://localhost:4001/ws  (wrong port, nothing listening)

Test plan

  • COLLAB_EMBEDDED_WS=true npm run serve
  • Confirm /collab-session returns ws://localhost:4000/ws
  • Open editor — connects and loads document

Without this env var, the server assumes the collab WebSocket runs on
PORT+1 (4001 by default) rather than the embedded port (4000). The editor
silently stays in "connecting" state with no useful error message.

Added COLLAB_EMBEDDED_WS=true to .env.example with an explanation, and
updated the README quickstart to include it in the npm run serve command.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant