From 68bc0a4fab0682a372afcc468a80580b44f5a204 Mon Sep 17 00:00:00 2001
From: topunix <833824+topunix@users.noreply.github.com>
Date: Wed, 23 Sep 2026 13:30:22 -0500
Subject: [PATCH 1/3] Bug 1849943: Add Apache and Nginx reverse proxy
instructions
---
docs/en/rst/installing/apache.rst | 51 +++++++++++++++++++++++++++++--
docs/en/rst/installing/nginx.rst | 48 +++++++++++++++++++++++++++++
2 files changed, 96 insertions(+), 3 deletions(-)
create mode 100644 docs/en/rst/installing/nginx.rst
diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst
index 1bb17f2b0..624f6104f 100644
--- a/docs/en/rst/installing/apache.rst
+++ b/docs/en/rst/installing/apache.rst
@@ -5,9 +5,54 @@
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
+
+
+ ServerName bugzilla.example.org
+
+ ProxyPreserveHost On
+ ProxyPass / http://127.0.0.1:3001/
+ ProxyPassReverse / http://127.0.0.1:3001/
+
+
+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 line inside the ````
+block so Bugzilla generates ``https`` URLs:
+
+.. code-block:: apache
-.. todo::
- Instructions for using Apache as a reverse proxy.
+ RequestHeader set X-Forwarded-Proto "https"
+.. 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.
diff --git a/docs/en/rst/installing/nginx.rst b/docs/en/rst/installing/nginx.rst
new file mode 100644
index 000000000..873887b1e
--- /dev/null
+++ b/docs/en/rst/installing/nginx.rst
@@ -0,0 +1,48 @@
+.. 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``.
+
+.. 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.
From c5e715b1d84362b2e457ad0768e5579272ba1f4b Mon Sep 17 00:00:00 2001
From: topunix <833824+topunix@users.noreply.github.com>
Date: Wed, 23 Sep 2026 14:29:53 -0500
Subject: [PATCH 2/3] Bug 1849943: Show TLS header inside its VirtualHost block
---
docs/en/rst/installing/apache.rst | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst
index 624f6104f..99295fc18 100644
--- a/docs/en/rst/installing/apache.rst
+++ b/docs/en/rst/installing/apache.rst
@@ -44,12 +44,14 @@ On Debian and Ubuntu, enable the site and reload Apache:
On Fedora and Red Hat, reload with ``sudo systemctl reload httpd``.
-If Apache terminates TLS, add this line inside the ````
-block so Bugzilla generates ``https`` URLs:
+If Apache terminates TLS, add this header to your TLS virtual host so
+Bugzilla generates ``https`` URLs:
.. code-block:: apache
- RequestHeader set X-Forwarded-Proto "https"
+
+ RequestHeader set X-Forwarded-Proto "https"
+
.. note::
Bugzilla listens on port 3001 by default. Set the ``PORT`` environment
From 45c8496e8379f2e72ddf813f3ff79ae844ee6b36 Mon Sep 17 00:00:00 2001
From: topunix <833824+topunix@users.noreply.github.com>
Date: Wed, 23 Sep 2026 14:35:05 -0500
Subject: [PATCH 3/3] Bug 1849943: Add HTTPS example to Nginx page
---
docs/en/rst/installing/nginx.rst | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/docs/en/rst/installing/nginx.rst b/docs/en/rst/installing/nginx.rst
index 873887b1e..17954d595 100644
--- a/docs/en/rst/installing/nginx.rst
+++ b/docs/en/rst/installing/nginx.rst
@@ -36,6 +36,38 @@ On Debian and Ubuntu, enable the site:
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