(nginx) Add php-handler tips + refine overview bullet points

admin_manual/installation/nginx.rst

@@ -12,15 +12,19 @@ NGINX configuration
     These configurations examples were originally provided by `@josh4trunks <https://github.com/josh4trunks>`_
     and are exclusively community-maintained. (Thank you contributors!)
 
--  You need to insert the following code into **your Nginx configuration file.**
--  Adjust **server_name**, **root**, **ssl_certificate** and
-   **ssl_certificate_key** to suit your needs.
--  Make sure your SSL certificates are readable by the server (see `nginx HTTP
-   SSL Module documentation <https://wiki.nginx.org/HttpSslModule>`_).
--  Be careful about line breaks if you copy the examples, as long lines may be
-   broken for page formatting.
--  Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their
-   ``php.ini``.
+- You need to insert the following code into **your Nginx configuration file**. Choose the appropriate example based on whether you are deploying :ref:`nginx_webroot_example` (i.e. :code:`https://cloud.example.com/`) or :ref:`nginx_subdir_example` (i.e. :code:`https://cloud.example.com/nextcloud`).
+- Adjust the server directive under :code:`upstream php-handler` to match your PHP installation's configured FPM listener (a misconfiguration here will result in a :code:`502 Bad Gateway` - see :ref:`nginx_php_handler_tips` for details)
+- Adjust the existing :code:`server_name` directives found under *both* :code:`server` sections to your real hostname
+- Adjust :code:`root` to the webroot of your Nextcloud installation 
+- Adjust the :code:`ssl_certificate` and :code:`ssl_certificate_key` directives to the real paths for your signed 
+  certificate and private key. Make sure your SSL certificates are readable by the nginx server process (see `nginx HTTPS SSL 
+  Module documentation <https://wiki.nginx.org/HttpSslModule>`_).
+- Be careful about line breaks if you copy the examples, as long lines may be
+  broken for page display and result in an invalid configuration files.
+- Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their
+  ``php.ini``.
+
+.. nginx_webroot_example:
 
 Nextcloud in the webroot of NGINX
 ---------------------------------
@@ -32,6 +36,8 @@ webroot of your nginx installation. In this example it is
 .. literalinclude:: nginx-root.conf.sample
    :language: nginx
 
+.. nginx_subdir_example:
+
 Nextcloud in a subdir of the NGINX webroot
 ------------------------------------------
 
@@ -53,6 +59,25 @@ The configuration differs from the "Nextcloud in webroot" configuration above in
 Tips and tricks
 ---------------
 
+.. nginx_php_handler_tips:
+
+PHP-Handler Configuration / Avoiding "502 Bad Gateway"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :code:`server` line within the :code:`upstream php-handler` above needs to be adjusted to reflect your local PHP FPM configuration. It must match whatever is configured for the :code:`listen` directive within the PHP FPM pool you'll be using for NC.
+
+Many Linux distributions define a listener for a default PHP-FPM pool called :code:`www` in a file called :code:`www.conf` located somewhere like :code:`/etc/php/8.1/pool.d`.
+
+Look for the line that is set to something like: 
+
+:code:`listen = /var/run/php/php-fpm.sock`
+or
+:code:`listen = 127.0.0.1:9000`
+
+If PHP FPM will be running on the same host as NGINX (it's probably a safe assumption it will be if you're unsure), it is recommended you use the UNIX socket (i.e. :code:`/var/run/php/php-fpm.sock`) rather than TCP (:code:`127.0.0.1:9000`) for maximum performance (though either will work as long as your NGINX and PHP FPM configurations match).
+
+After deciding how you'd prefer to connect NGINX with PHP FPM (and, if necessary, updating your local PHP FPM configuration and restarting FPM), set your NGINX configuration's :code:`upstream php-handler` :code:`server` to match your preference (Note: If using UNIX sockets, prepend :code:`unix:` in the NGINX configuration, but *not* in your PHP FPM :code:`www.conf`). 
+
 Suppressing log messages
 ^^^^^^^^^^^^^^^^^^^^^^^^