[Encore] Adding docs about deploying to a subdirectory - see #8069

symfony · weaverryan · Jun 26, 2017 · Jun 24, 2017 · Jun 24, 2017 · Jun 25, 2017
commit 8b0a22afb9310dec7e0834da57d58cdfeae60312
diff --git a/frontend.rst b/frontend.rst
@@ -61,6 +61,11 @@ Guides
 * :doc:`Adding custom loaders </frontend/encore/custom-loaders>`
 * :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
 
+Troubleshooting
+...............
+
+* :doc:`FAQ </frontend/encore/faq>`
+
 Full API
 ........
 

diff --git a/frontend/encore/faq.rst b/frontend/encore/faq.rst
@@ -0,0 +1,39 @@
+Frequently Asked Questions
+==========================
+
+My App Lives under a Subdirectory
+---------------------------------
+
+    My app doesn't live at the root of my web server: it lives under a subdirectory
+    (e.g. ``/myAppSubdir/``). How can I configure Encore to work?
+
+If your app lives under a subdirectory, you just need to include that when calling
+``Encore.setPublicPrefix()``:
+
+.. code-block:: diff
+
+    // webpack.config.js
+    Encore
+        // ...
+
+        .setOutputPath('web/build/')
+
+        - .setPublicPath('/build')
+        + // this is your *true* public path
+        + .setPublicPath('/myAppSubdir/build')
+
+        + // this is now needed so that your manifest.json keys are still `build/foo.js`
+        + // i.e. you won't need to change anything in your Symfony app
+        + config.setManifestKeyPrefix('build')
+    ;
+
+If you're :ref:`processing your assets through manifest.json <load-manifest-files>`,
+you're done! The ``manifest.json`` file will now include the subdirectory in the
+final paths:
+
+.. code-block:: json
+
+    {
+        "build/app.js": "/myAppSubdir/build/app.123abc.js",
+        "build/dashboard.css": "/myAppSubdir/build/dashboard.a4bf2d.css"
+    }