Live reload not working with reverse proxy

[jeengbe]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

When running Docusaurus behind a reverse proxy (Codespaces, code-server etc.), Docusaurus is likely being accessed under a different url than it is being exposed on. (eg. localhost:3000 --Docker & Reverse Proxy-> dev.mycodespace.io)
In this scenario (Docusaurus needs to be run with --host 0.0.0.0), webpack uses the same options for the web socket server as for the dev server, and passes those on to the client: protocol=ws%3A&hostname=0.0.0.0&port=3000&pathname=%2Fws&logging=warn&reconnect=10
(https://github.com/webpack/webpack-dev-server/blob/master/lib/Server.js#L634). Luckily, 0.0.0.0 is replaced by self.location.hostname (https://github.com/webpack/webpack-dev-server/blob/master/client-src/utils/createSocketURL.js#L91), same goes for the protocol, but there is no way to correct the incorrect port, so there must be a way for the developer to specify this. This should be implemented here: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/commands/start.ts#L190

For those who are looking for a solution for the time being, this patch will make webpack hot reload connect to self.location.port.

diff --git a/node_modules/@docusaurus/core/lib/commands/start.js b/node_modules/@docusaurus/core/lib/commands/start.js
index 4fd663b..3678353 100644
--- a/node_modules/@docusaurus/core/lib/commands/start.js
+++ b/node_modules/@docusaurus/core/lib/commands/start.js
@@ -142,6 +142,9 @@ async function start(siteDirParam = '.', cliOptions = {}) {
                 warnings: false,
                 errors: true,
             },
+            webSocketURL: {
+                port: 0
+            }
         },
         headers: {
             'access-control-allow-origin': '*',

Reproducible demo

No response

Steps to reproduce

1. Run Docusaurus behind a reverse proxy (inside a Docker Container in this example)
2. Start dev mode pnpm start --host 0.0.0.0
3. Open console and see errors (also no live reload)

Expected behavior

Docusaurus should automatically refresh after changes to the source file.

Actual behavior

It does not.

Your environment

pnpm start --host 0.0.0.0 inside a Docker Container that rebinds :3000 -> :3007 hidden behind a reverse proxy that serves :3007 on dev.mycodespace.io

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Hey

I'm not a Docker / Codespace expert, can you provide us a runnable sandbox or clearer repro instructions so that we are sure to reproduce your problem without having to figure out the details ourselves?

Can you explain why this config solves the problem?

           webSocketURL: {
                port: 0
           }

Where does this solution come from exactly? What does port: 0 do?

[jeengbe]

The snippet fixes the problem, since it tells HMR to use the same port that the website is currently running on. You should also consider always passing 0.0.0.0 as hostname, since that sets it to the current domain.

The following code snippets go together, and this is where the issue arises:

• https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/commands/start.ts#L190 (This is where webpack dev server is initialized)
• https://github.com/webpack/webpack-dev-server/blob/master/lib/Server.js#L478 (Constructing data to pass to the client)
• https://github.com/webpack/webpack-dev-server/blob/49efdf87341d4e40106baae60670a4aabf3285fb/client-src/utils/createSocketURL.js#L75 (Parsing of the passed data)

Will provide a repo with steps to reproduce asap

[jeengbe]

Yeah no there isn't really a repo to provide.
What you need is a development instance of Docusaurus running, and a reverse proxy (nginx, Apache, IIS etc.) that wraps around Docusaurus, normally port 3000. The only important thing is that Docusaurus is not served on the same port to the client as it is exposed to on the server.
In that situation, hmr will try to use the port the server was started on, unless its told to pick the port the browser is currently accessing (see comment above) by passing port: 0.

[slorber]

@jeengbe this is an edge case and I don't want to spend 1 day relearning how to install and configure apache. If you want it to be solved faster, provide clear instructions to reproduce it, preferably with Docker. Yes, I'm asking you to invest your own time to save mine.

Now if you can create a PR where it doesn't change the behavior at all for regular users, but solve your problem, I'm ok to merge it blindly. I'm ok to add a secret env variable just for this for example.

---

Note I believe this is a decent escape hatch you can use today with a docusaurus plugin:

function CustomDevServerPlugin() {
  return {
    name: "custom-dev-server-plugin",
    configureWebpack() {
      return {
        devServer: {
          client: {
            webSocketURL: {
              port: 0
            }
          }
        }
      };
    }
  };
}

Please give it a try and let me know how it works

So what we implement here would just be a convenient shortcut for the above?

[jeengbe]

I do very well understand that. Luckily, I had a similar configuration lying around and quickly managed to throw together a working sample repository. Note that you might have to wait a little for Docusaurus to finish building upon launching it.
Locate to localhost, and open dev tools to see ws:// connections being made to localhost:3000

The patch fixes this issue as it, as outlined above with code references, makes hmr use the port the site is being accessed on.

[IceflowRE]

Your environment

pnpm start --host 0.0.0.0 inside a Docker Container that rebinds :3000 -> :3007 hidden behind a reverse proxy that serves :3007 on dev.mycodespace.io

Do not remap the port with Docker.

"Remap" to the same port and if you need a different port change it via the --port option.
Tested with 2.3.0.

[splurgebudget]

I'm currently seeing this error on a new Docusaurus (2.4.1) running behind Nginx (1.22.0) on a remote server:

Is there a configuration option I can use to tell webpack to use my real server address to serve up the websocket?

[slorber]

@splurgebudget try v3 canary, cf #7951 (comment)