diff --git a/frontend.rst b/frontend.rst index f233cfe0016..667543b7242 100644 --- a/frontend.rst +++ b/frontend.rst @@ -74,6 +74,7 @@ Guides * :doc:`webpack-dev-server and Hot Module Replacement (HMR) ` * :doc:`Adding custom loaders & plugins ` * :doc:`Advanced Webpack Configuration ` +* :doc:`Using Encore in a Virtual Machine ` Issues & Questions .................. diff --git a/frontend/encore/dev-server.rst b/frontend/encore/dev-server.rst index 60284383256..a29e6f5e903 100644 --- a/frontend/encore/dev-server.rst +++ b/frontend/encore/dev-server.rst @@ -26,19 +26,6 @@ by the normal `webpack-dev-server`_. For example: This will start a server at ``https://localhost:9000``. -Using dev-server inside a VM ----------------------------- - -If you're using ``dev-server`` from inside a virtual machine, then you'll need -to bind to all IP addresses and allow any host to access the server: - -.. code-block:: terminal - - $ ./node_modules/.bin/encore dev-server --host 0.0.0.0 --disable-host-check - -You can now access the dev-server using the IP address to your virtual machine on -port 8080 - e.g. http://192.168.1.1:8080. - Hot Module Replacement HMR -------------------------- diff --git a/frontend/encore/virtual-machine.rst b/frontend/encore/virtual-machine.rst new file mode 100644 index 00000000000..a1cc24697ce --- /dev/null +++ b/frontend/encore/virtual-machine.rst @@ -0,0 +1,112 @@ +Using Encore in a Virtual Machine +================================= + +You may encounter some issues when using Encore in a virtual machine, like VirtualBox or VMWare. + +Fix watching issues +------------------- + +When using a virtual machine, your project root directory is shared with the virtual machine with `NFS`_. +This is really useful, but it introduces some issues with files watching. + +You must enable `polling`_ option to make it work: + +.. code-block:: javascript + + // webpack.config.js + + // ... + + // will be applied for `encore dev --watch` and `encore dev-server` commands + Encore.configureWatchOptions(watchOptions => { + watchOptions.poll = 250; // check for changes every 250 ms + }); + +Fix development server +---------------------- + +Configure public path +~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + You can skip this sub-section if your app is running on ``http://localhost`` + and not a custom local domain-name like ``http://app.vm``. + +When running the development server, you will probably face the following errors in the web console: + +.. code-block:: text + + GET http://localhost:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED + GET http://localhost:8080/build/runtime.js net::ERR_CONNECTION_REFUSED + ... + +If your Symfony application is running on ``http://app.vm``, you must configure the public path explicitly +in your ``package.json``: + +.. code-block:: diff + + { + ... + "scripts": { + - "dev-server": "encore dev-server", + + "dev-server": "encore dev-server --public http://app.vm:8080", + ... + } + } + +After restarting Encore and reloading your web page, you will probably face different issues: + +.. code-block:: text + + GET http://app.vm:8080/build/vendors~app.css net::ERR_CONNECTION_REFUSED + GET http://app.vm:8080/build/runtime.js net::ERR_CONNECTION_REFUSED + +Encore understood our modification but it's still not working. There is still two things to do. + +Allow external access +~~~~~~~~~~~~~~~~~~~~~ + +You must configure how you run the `webpack-dev-server`_. +This can easily be done in your ``package.json`` by adding ``--host 0.0.0.0`` argument: + +.. code-block:: diff + + { + ... + "scripts": { + - "dev-server": "encore dev-server --public http://app.vm:8080", + + "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0", + ... + } + } + +.. warning:: + + Using ``--host 0.0.0.0`` makes your development server accept all incoming connections. + Be sure to run the development server inside your virtual machine and not outside, otherwise other computers can have access to it. + +Fix "Invalid Host header" issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Webpack will respond ``Invalid Host header`` when trying to access files from the dev-server. +To fix this, add the argument ``--disable-host-check``: + +.. code-block:: diff + + { + ... + "scripts": { + - "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0", + + "dev-server": "encore dev-server --public http://app.vm:8080 --host 0.0.0.0 --disable-host-check", + ... + } + } + +.. warning:: + + This is usually not recommended to disable host checking, `more information here `_. + +.. _`NFS`: https://en.wikipedia.org/wiki/Network_File_System +.. _`polling`: https://webpack.js.org/configuration/watch/#watchoptionspoll +.. _`webpack-dev-server`: https://webpack.js.org/configuration/dev-server/