Bug 1849943: Add Apache and Nginx reverse proxy instructions

docs/en/rst/installing/apache.rst

@@ -5,9 +5,56 @@
 Apache
 ######
 
-.. note:: 
+Bugzilla runs as its own web application. Apache is used as a reverse
+proxy in front of it and can also handle TLS.
+
+.. note::
   Previous versions of Bugzilla ran using Apache's ModPerl or as CGI.
+  Neither is used anymore, so no Bugzilla-specific changes to the main
+  Apache configuration file are needed.
+
+Enable the proxy and header modules. On Debian and Ubuntu:
+
+.. code-block:: console
+
+    sudo a2enmod proxy proxy_http headers
+
+On Fedora and Red Hat these modules are enabled by default.
+
+Add a virtual host for your Bugzilla hostname. On Debian and Ubuntu use
+:file:`/etc/apache2/sites-available/bugzilla.conf`; on Fedora and Red Hat
+use :file:`/etc/httpd/conf.d/bugzilla.conf`:
+
+.. code-block:: apache
+
+    <VirtualHost *:80>
+        ServerName bugzilla.example.org
+
+        ProxyPreserveHost On
+        ProxyPass / http://127.0.0.1:3001/
+        ProxyPassReverse / http://127.0.0.1:3001/
+    </VirtualHost>
+
+On Debian and Ubuntu, enable the site and reload Apache:
+
+.. code-block:: console
+
+    sudo a2ensite bugzilla
+    sudo systemctl reload apache2
+
+On Fedora and Red Hat, reload with ``sudo systemctl reload httpd``.
+
+If Apache terminates TLS, add this header to your TLS virtual host so
+Bugzilla generates ``https`` URLs:
+
+.. code-block:: apache
 
-.. todo::
-  Instructions for using Apache as a reverse proxy.
+    <VirtualHost *:443>
+        RequestHeader set X-Forwarded-Proto "https"
+    </VirtualHost>
 
+.. note::
+    Bugzilla listens on port 3001 by default. Set the ``PORT`` environment
+    variable to change it, and update the ``ProxyPass`` lines to match.
+    Start the web app using ``MOJO_REVERSE_PROXY=1 ./bugzilla.pl daemon``
+    when running behind Apache, so it trusts the forwarded headers.

docs/en/rst/installing/nginx.rst

@@ -0,0 +1,80 @@
+.. This document is shared among all non-Windows OSes.
+
+.. _nginx:
+
+Nginx
+#####
+
+Bugzilla runs as its own web application. Nginx is used as a reverse
+proxy in front of it and can also handle TLS.
+
+Add a server block for your Bugzilla hostname. On Debian and Ubuntu use
+:file:`/etc/nginx/sites-available/bugzilla`; on Fedora and Red Hat use
+:file:`/etc/nginx/conf.d/bugzilla.conf`:
+
+.. code-block:: nginx
+
+    server {
+        listen 80;
+        server_name bugzilla.example.org;
+
+        client_max_body_size 10m;
+
+        location / {
+            proxy_pass http://127.0.0.1:3001;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+On Debian and Ubuntu, enable the site:
+
+.. code-block:: console
+
+    sudo ln -s /etc/nginx/sites-available/bugzilla /etc/nginx/sites-enabled/
+
+Then reload Nginx with ``sudo systemctl reload nginx``.
+
+If Nginx terminates TLS, serve Bugzilla from a ``443`` server block and
+redirect plain HTTP to it. The ``X-Forwarded-Proto $scheme`` header above
+already tells Bugzilla to generate ``https`` URLs. Tools such as Certbot can
+generate this configuration and the certificates for you.
+
+.. code-block:: nginx
+
+    server {
+        listen 443 ssl;
+        listen [::]:443 ssl;
+        server_name bugzilla.example.org;
+
+        ssl_certificate     /etc/letsencrypt/live/bugzilla.example.org/fullchain.pem;
+        ssl_certificate_key /etc/letsencrypt/live/bugzilla.example.org/privkey.pem;
+
+        client_max_body_size 10m;
+
+        location / {
+            proxy_pass http://127.0.0.1:3001;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        listen [::]:80;
+        server_name bugzilla.example.org;
+        return 301 https://$host$request_uri;
+    }
+
+.. note::
+    Nginx rejects request bodies larger than 1 MB by default, which blocks
+    larger attachment uploads. Set ``client_max_body_size`` to at least the
+    value of the :param:`maxattachmentsize` parameter.
+
+.. note::
+    Bugzilla listens on port 3001 by default. Set the ``PORT`` environment
+    variable to change it, and update ``proxy_pass`` to match. Start the
+    web app using ``MOJO_REVERSE_PROXY=1 ./bugzilla.pl daemon`` when
+    running behind Nginx, so it trusts the forwarded headers.