diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst index 1bb17f2b0..99295fc18 100644 --- a/docs/en/rst/installing/apache.rst +++ b/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 + + + 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 header to your TLS virtual host 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..17954d595 --- /dev/null +++ b/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.