From d2c6bee9e4e3de2503d8e28f49b5beacf34cdc6b Mon Sep 17 00:00:00 2001 From: Emma Humphries Date: Tue, 14 May 2024 00:12:50 -0700 Subject: [PATCH] Bug 1849943: (WIP) Update Ubuntu LTS Quick Start (#125) --- docs/en/rst/installing/apache-windows.rst | 132 +------------ docs/en/rst/installing/apache.rst | 140 +------------- docs/en/rst/installing/caddy.rst | 21 ++ docs/en/rst/installing/iis.rst | 126 +----------- docs/en/rst/installing/quick-start.rst | 222 +++++++++++++--------- docs/en/rst/installing/web_server.rst | 6 +- 6 files changed, 161 insertions(+), 486 deletions(-) create mode 100644 docs/en/rst/installing/caddy.rst diff --git a/docs/en/rst/installing/apache-windows.rst b/docs/en/rst/installing/apache-windows.rst index c119e1b131..e74961785c 100644 --- a/docs/en/rst/installing/apache-windows.rst +++ b/docs/en/rst/installing/apache-windows.rst @@ -3,134 +3,4 @@ Apache on Windows ################# -Bugzilla supports all versions of Apache 2.2.x and 2.4.x. - -Installing -========== - -Download the Apache HTTP Server as a :file:`.zip` archive either from the -`Apache Lounge website `_ or from the -`Apache Haus website `_. - -Unzip the archive into :file:`C:\\Apache24`. If you move it elsewhere, then -you must edit several variables in :file:`httpd.conf`, including ``ServerRoot`` -and ``DocumentRoot``. - -You must now edit the Apache configuration file :file:`C:\\Apache24\\conf\\httpd.conf` -and do the following steps: - -#. Uncomment ``LoadModule cgi_module modules/mod_cgi.so`` at the beginning of the - file to enable CGI support. -#. Uncomment ``AddHandler cgi-script .cgi`` to register :file:`.cgi` files - as CGI scripts. For this handler to work, you must create a key in the - Windows registry named ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with - the default value pointing to the full path of :file:`perl.exe` with a ``-T`` - parameter. For example :file:`C:\\Perl\\bin\\perl.exe -T` if you use ActivePerl, - or :file:`C:\\Strawberry\\perl\\bin\\perl.exe -T` if you use Strawberry Perl. -#. Add an Alias and a Directory for Bugzilla: - -.. code-block:: apache - - Alias "/bugzilla/" "C:/bugzilla/" - - ScriptInterpreterSource Registry-Strict - Options +ExecCGI +FollowSymLinks - DirectoryIndex index.cgi index.html - AllowOverride All - Require all granted - - -.. warning:: The above block takes a simple approach to access control and is - correct for Apache 2.4. For Apache 2.2, replace ``Require all granted`` - with ``Allow from all``. If you have other access control - requirements, you may need to make further modifications. - -You now save your changes and start Apache as a service. From the Windows -command line (:file:`cmd.exe`): - -:command:`C:\\Apache24\\bin>httpd.exe -k install` - -That's it! Bugzilla is now accessible from http://localhost/bugzilla. - -Apache Account Permissions -========================== - -By default Apache installs itself to run as the SYSTEM account. For security -reasons it's better the reconfigure the service to run as an Apache user. -Create a new Windows user that is a member of **no** groups, and reconfigure -the Apache2 service to run as that account. - -Whichever account you are running Apache as, SYSTEM or otherwise, needs write -and modify access to the following directories and all their subdirectories. -Depending on your version of Windows, this access may already be granted. - -* :file:`C:\\Bugzilla\\data` -* :file:`C:\\Apache24\\logs` -* :file:`C:\\Windows\\Temp` - -Note that :file:`C:\\Bugzilla\\data` is created the first time you run -:file:`checksetup.pl`. - -Logging -======= - -Unless you want to keep statistics on how many hits your Bugzilla install is -getting, it's a good idea to disable logging by commenting out the -``CustomLog`` directive in the Apache config file. - -If you don't disable logging, you should at least disable logging of "query -strings". When external systems interact with Bugzilla via webservices -(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL -(in the query string). Therefore, to avoid storing passwords in clear text -on the server we recommend configuring Apache to not include the query string -in its log files. - -#. Find the following line in the Apache config file, which defines the - logging format for ``vhost_combined``: - - .. code-block:: apache - - LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined - -#. Replace ``%r`` with ``%m %U``. - -(If you have configured Apache differently, a different log line might apply. -Adjust these instructions accordingly.) - -Using Apache with SSL -===================== - -If you want to enable SSL with Apache, i.e. access Bugzilla from -https://localhost/bugzilla, you need to do some extra steps: - -#. Edit :file:`C:\\Apache24\\conf\\httpd.conf` and uncomment these lines: - - * ``LoadModule ssl_module modules/mod_ssl.so`` - * ``LoadModule socache_shmcb_module modules/mod_socache_shmcb.so`` - * ``Include conf/extra/httpd-ssl.conf`` - -#. Create your :file:`.key` and :file:`.crt` files using :file:`openssl.exe` - provided with Apache: - - :command:`C:\\Apache24\\bin>openssl.exe req -x509 -nodes -days 730 -newkey rsa:2048 -keyout server.key -out server.crt` - - :file:`openssl.exe` will ask you a few questions about your location and - your company name to populate fields of the certificate. - -#. Once the key and the certificate for your server are generated, move them - into :file:`C:\\Apache24\\conf` so that their location matches the - ``SSLCertificateFile`` and ``SSLCertificateKeyFile`` variables defined in - :file:`C:\\Apache24\\conf\\extra\\httpd-ssl.conf` (which you don't need to - edit). - -.. note:: This process leads to a self-signed certificate which will generate - browser warnings on first visit. If your Bugzilla has a public DNS - name, you can get a cert from a CA which will not have this problem. - -Restart Apache -============== - -Finally, restart Apache to pick up the changes, either from the Services -console or from the command line: - -:command:`C:\\Apache24\\bin>httpd.exe -k restart` +.. note:: If deploying Bugzilla on Windows, using WSL is recommened. diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst index f98d20df01..1bb17f2b03 100644 --- a/docs/en/rst/installing/apache.rst +++ b/docs/en/rst/installing/apache.rst @@ -5,141 +5,9 @@ Apache ###### -You have two options for running Bugzilla under Apache - mod_cgi (the -default) and mod_perl. mod_perl is faster but takes more resources. You -should probably only consider mod_perl if your Bugzilla is going to be heavily -used. +.. note:: + Previous versions of Bugzilla ran using Apache's ModPerl or as CGI. -These instructions require editing the Apache configuration file, which is: +.. todo:: + Instructions for using Apache as a reverse proxy. -* Fedora/Red Hat: :file:`/etc/httpd/conf/httpd.conf` -* Debian/Ubuntu: :file:`/etc/apache2/apache2.conf` -* Mac OS X: :file:`/etc/apache2/httpd.conf` - -Alternatively, on Debian or Ubuntu, you can instead put the below code into a -separate file in the directory :file:`/etc/apache2/sites-enabled/`. - -In these instructions, when asked to restart Apache, the command is: - -:command:`sudo apachectl start` - -(or run it as root if your OS installation does not use sudo). - -Securing Apache -=============== - -When external systems interact with Bugzilla via webservices -(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL -(in the "query string"). Therefore, to avoid storing passwords in clear text -on the server we recommend configuring Apache to not include the query string -in its log files. - -#. Edit the Apache configuration file (see above). - -#. Find the following line in the above mentioned file, which defines the - logging format for ``vhost_combined``: - - .. code-block:: apache - - LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined - -#. Replace ``%r`` with ``%m %U``. - -#. Restart Apache. - -.. _apache-mod_cgi: - -Apache with mod_cgi -=================== - -To configure your Apache web server to work with Bugzilla while using -mod_cgi, do the following: - -#. Edit the Apache configuration file (see above). - -#. Create a ```` directive that applies to the location - of your Bugzilla installation. In this example, Bugzilla has - been installed at :file:`/var/www/html/bugzilla`. On Mac OS X, use - :file:`/Library/WebServer/Documents/bugzilla`. - -.. code-block:: apache - - - AddHandler cgi-script .cgi - Options +ExecCGI +FollowSymLinks - DirectoryIndex index.cgi index.html - AllowOverride All - - -These instructions allow Apache to run .cgi files found within the Bugzilla -directory; instructs the server to look for a file called :file:`index.cgi` -or, if not found, :file:`index.html` if someone only types the directory name -into the browser; and allows Bugzilla's :file:`.htaccess` files to override -some global permissions. - -On some Linux distributions you will need to enable the Apache CGI -module. On Debian/Ubuntu, this is done with: - -:command:`sudo a2enmod cgi` - -If you find that the webserver is returning the Perl code as text rather -than executing it, then this is the problem. - -.. _apache-mod_perl: - -Apache with mod_perl -==================== - -Some configuration is required to make Bugzilla work with Apache -and mod_perl. - -.. note:: It is not known whether anyone has even tried mod_perl on Mac OS X. - -#. Edit the Apache configuration file (see above). - -#. Add the following information, substituting where appropriate with your - own local paths. - - .. code-block:: apache - - PerlSwitches -w -T - PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl - - .. note:: This should be used instead of the block - shown above. This should also be above any other ``mod_perl`` - directives within the :file:`httpd.conf` and the directives must be - specified in the order above. - - .. warning:: You should also ensure that you have disabled ``KeepAlive`` - support in your Apache install when utilizing Bugzilla under mod_perl - or you may suffer a - `performance penalty `_. - -On restarting Apache, Bugzilla should now be running within the -mod_perl environment. - -Please bear the following points in mind when considering using Bugzilla -under mod_perl: - -* mod_perl support in Bugzilla can take up a HUGE amount of RAM - easily - 30MB per httpd child. The more RAM you can get, the better. mod_perl is - basically trading RAM for speed. At least 2GB total system RAM is - recommended for running Bugzilla under mod_perl. - -* Under mod_perl, you have to restart Apache if you make any manual change to - any Bugzilla file. You can't just reload--you have to actually - *restart* the server (as in make sure it stops and starts - again). You *can* change :file:`localconfig` and the :file:`params` file - manually, if you want, because those are re-read every time you load a page. - -* You must run in Apache's Prefork MPM (this is the default). The Worker MPM - may not work -- we haven't tested Bugzilla's mod_perl support under threads. - (And, in fact, we're fairly sure it *won't* work.) - -* Bugzilla generally expects to be the only mod_perl application running on - your entire server. It may or may not work if there are other applications also - running under mod_perl. It does try its best to play nice with other mod_perl - applications, but it still may have conflicts. - -* It is recommended that you have one Bugzilla instance running under mod_perl - on your server. Bugzilla has not been tested with more than one instance running. diff --git a/docs/en/rst/installing/caddy.rst b/docs/en/rst/installing/caddy.rst new file mode 100644 index 0000000000..ff37ada5a3 --- /dev/null +++ b/docs/en/rst/installing/caddy.rst @@ -0,0 +1,21 @@ + +.. _caddy: + +Caddy +##### + +The Caddy web server has built in support for reverse proxies. + +It also automates the creation of Let's Encrypt certificates for +the hosts specified in the Caddyfile. + +An example Caddyfile for Bugzilla would be: + +.. code-block:: + + hostname { + reverse_proxy 127.0.0.1:3001 + } + +.. note:: + You may need to start the Bugzilla web app using ``MOJO_REVERSE_PROXY=1 ./bugzilla.pl daemon`` when running behind Caddy. diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst index 320b8f73c5..2d3bbac358 100644 --- a/docs/en/rst/installing/iis.rst +++ b/docs/en/rst/installing/iis.rst @@ -3,128 +3,4 @@ Microsoft IIS ############# -Bugzilla works with IIS as a normal CGI application. These instructions assume -that you are using Windows 7 or Windows 10. Procedures for other versions are -probably similar. - -Begin by starting Internet Information Services (IIS) Manager. -:guilabel:`Start` --> :guilabel:`Administrators Tools` --> -:guilabel:`Internet Information Services (IIS) Manager`. Or run the command: - -:command:`inetmgr` - -Create a New Application -======================== - -Expand your :guilabel:`Server` until the :guilabel:`Default Web Site` shows -its children. - -Right-click :guilabel:`Default Web Site` and select -:guilabel:`Add Application` from the menu. - -Unde :guilabel:`Alias`, enter the alias for the website. This is the path -below the domain where you want Bugzilla to appear. - -Under :guilabel:`Physical Path`, enter the path to Bugzilla, -:file:`C:\\Bugzilla`. - -When finished, click :guilabel:`OK`. - -Configure the Default Document -============================== - -Click on the Application that you just created. Double-click on -:guilabel:`Default Document`, and click :guilabel:`Add` underneath the -Actions menu. - -Under :guilabel:`Name`, enter ``index.cgi``. - -All other default documents can be removed for this application. - -.. warning:: Do not delete the default document from the :guilabel:`Default Website`. - -Add Handler Mappings -==================== - -Ensure that you are at the Default Website. Under :guilabel:`IIS`, -double-click :guilabel:`Handler Mappings`. Under :guilabel:`Actions`, click -:guilabel:`Add Script Map`. You need to do this twice. - -For the first one, set the following values (replacing paths if necessary): - -* :guilabel:`Request Path`: ``*.pl`` -* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe "%s" %s`` -* :guilabel:`Name`: ``Perl Script Map`` - -At the prompt select :guilabel:`Yes`. - -.. note:: The ActiveState Perl installer may have already created an entry for - .pl files that is limited to ``GET,HEAD,POST``. If so, this mapping should - be removed, as Bugzilla's .pl files are not designed to be run via a web - server. - -For the second one, set the following values (replacing paths if necessary): - -* :guilabel:`Request Path`: ``*.cgi`` -* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe "%s" %s`` -* :guilabel:`Name`: ``CGI Script Map`` - -At the prompt select :guilabel:`Yes`. - -Bugzilla Application -==================== - -Ensure that you are at the Bugzilla Application. Under :guilabel:`IIS`, -double-click :guilabel:`Handler Mappings`. Under :guilabel:`Actions`, click -:guilabel:`Add Script Map`. - -Set the following values (replacing paths if necessary): - -* :guilabel:`Request Path`: ``*.cgi`` -* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe -x"C:\Bugzilla" -wT "%s" %s`` -* :guilabel:`Name`: ``Bugzilla`` - -At the prompt select :guilabel:`Yes`. - -Now it's time to restart the IIS server to take these changes into account. -From the top-level menu, which contains the name of your machine, click -:guilabel:`Restart` under :guilabel:`Manage Server`. Or run the command: - -:command:`iisreset` - -Enable Rewrite Rules for REST -============================= - -REST URLs are usually of the form http://.../bugzilla/rest/version instead of -http://.../bugzilla/rest.cgi/version. To let IIS redirect rest/ URLs to rest.cgi, -you need to download and install the -`URL Rewrite extension for IIS `_. -Direct download links are available at the bottom of the page for both x86 and -x64 Windows. - -Once installed, you open the IIS Manager again and go to your Bugzilla -Application. From here, double-click :guilabel:`URL Rewrite`. Then click -:guilabel:`Add Rule(s)` under the :guilabel:`Actions` menu and click -:guilabel:`Blank rule` in the :guilabel:`Inbound rules` section. - -Fill the fields as follows. Other fields do not need to be edited. - -* :guilabel:`Name`: ``REST`` -* :guilabel:`Pattern`: ``^rest/(.*)$`` -* :guilabel:`Rewrite URL`: ``rest.cgi/{R:1}`` - -There is no need to restart IIS. Changes take effect immediately. - -Common Problems -=============== - -Bugzilla runs but it's not possible to log in - You've probably configured IIS to use ActiveState's ISAPI DLL -- in other - words you're using PerlEx, or the executable IIS is configured to use is - :file:`PerlS.dll` or :file:`Perl30.dll`. - - Reconfigure IIS to use :file:`perl.exe`. - -IIS returns HTTP 502 errors - You probably forgot the ``-T`` argument to :file:`perl` when configuring the - executable in IIS. +.. todo:: is this obsolete? \ No newline at end of file diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst index 5807587a66..1047237f17 100644 --- a/docs/en/rst/installing/quick-start.rst +++ b/docs/en/rst/installing/quick-start.rst @@ -8,16 +8,22 @@ those who are able to choose their environment. It creates a system using Ubuntu Linux 22.04 LTS, Apache and MariaDB. It requires a little familiarity with Linux and the command line. -Obtain Your Hardware -==================== +.. note:: Harmony's dependencies have major changes from previous + versions of Bugzilla. The libraries are now installed as local + Perl modules via ``carton`` instead as system-wide Debian packages. + +Running On Your Own Hardware +============================ Ubuntu 22.04 LTS Server requires a 64-bit processor. Bugzilla itself has no prerequisites beyond that, although you should pick -reliable hardware. You can also probably use any 64-bit virtual machine -or cloud instance that you have root access on. +reliable hardware. + +.. todo:: + What is reliable hardware? Install the OS -============== +-------------- Get `Ubuntu Server 22.04 LTS `_ and follow the `installation instructions @@ -35,45 +41,60 @@ Here are some tips: Reboot when the installer finishes. Become root -=========== +----------- ssh to the machine as the 'bugzilla' user, or start a console. Then: :command:`sudo su` +Running on a VPS (Virtual Private Server) +========================================= + +.. todo:: + Also need sizing for this + +Creating a VPS +-------------- + +Create a new VPS instance using Ubuntu 22.04 (LTS) for AMD64 architectures. + +Choose an instance of at least 1GB memory and sufficient disc for the MariaDB +instance, an SSD is preferred. + +Root Access +----------- + +Depending on your provider, you may be creating a user in the ``sudoers`` group, +or providing a public key to a SSH certificate you create on your computer which +will you allow you to connect to the VPS as root, which you will need in the +following steps. + +.. warning:: Do not set a password for root on your VPS server. Either use an SSH + key to connect as root, or log in as an unprivileged user in the ``sudoers`` + group. + +Become root +----------- + +Switch to the root user, either by logging in as an unprivileged user, and running +the command: + +:command:`sudo su` + +or logging in as root using a SSH key. + Install Prerequisites ===================== -:command:`apt install git nano` - -:command:`apt install apache2 build-essential mariadb-server -libcgi-pm-perl libdigest-sha-perl libtimedate-perl libdatetime-perl -libdatetime-timezone-perl libdbi-perl libdbix-connector-perl libtemplate-perl -libemail-address-perl libemail-sender-perl libemail-mime-perl -liburi-perl liblist-moreutils-perl libmath-random-isaac-perl -libjson-xs-perl libgd-perl libchart-perl libtemplate-plugin-gd-perl -libgd-text-perl libgd-graph-perl libmime-tools-perl libwww-perl -libxml-twig-perl libnet-ldap-perl libauthen-sasl-perl -libnet-smtp-ssl-perl libauthen-radius-perl libsoap-lite-perl -libxmlrpc-lite-perl libjson-rpc-perl libtest-taint-perl -libhtml-parser-perl libhtml-scrubber-perl libencode-perl -libencode-detect-perl libemail-reply-perl -libhtml-formattext-withlinks-perl libtheschwartz-perl -libdaemon-generic-perl libapache2-mod-perl2 libapache2-mod-perl2-dev -libfile-mimeinfo-perl libio-stringy-perl libcache-memcached-perl -libfile-copy-recursive-perl libfile-which-perl libdbd-mysql-perl -perlmagick lynx graphviz python3-sphinx rst2pdf` - -This will take a little while. It's split into two commands so you can do -the next steps (up to step 7) in another terminal while you wait for the -second command to finish. If you start another terminal, you will need to -:command:`sudo su` again. - -Configure MariaDB -================= +As root, run the following: -The following instructions use the simple :file:`nano` editor, but feel -free to use any text editor you are comfortable with. +:command:`apt install git nano build-essential mariadb-server libmariadb-dev perlmagick graphviz python3-sphinx rst2pdf carton` + +Configure MySQL +=============== + +The following instructions use the simple :file:`nano` editor you installed +in the previous step, but use any text editor you are comfortable with. :command:`nano /etc/mysql/mariadb.conf.d/50-server.cnf` @@ -89,42 +110,16 @@ Create a database ``bugs`` for Bugzilla: :command:`mysql -u root -e "CREATE DATABASE IF NOT EXISTS bugs CHARACTER SET = 'utf8'"` -Then, add a user to MariaDB for Bugzilla to use: +Then, add a user to MySQL for Bugzilla to use: :command:`mysql -u root -e "GRANT ALL PRIVILEGES ON bugs.* TO bugs@localhost IDENTIFIED BY '$db_pass'"` Replace ``$db_pass`` with a strong password you have generated. Write it down. You should make ``$db_pass`` different to your password. -Restart MariaDB: - -:command:`service mariadb restart` - -Configure Apache -================ - -:command:`nano /etc/apache2/sites-available/bugzilla.conf` +Restart MySQL: -Paste in the following and save: - -.. code-block:: apache - - Alias /bugzilla /var/www/webapps/bugzilla - - AddHandler cgi-script .cgi - Options +ExecCGI - DirectoryIndex index.cgi index.html - AllowOverride All - - -This configuration sets up Bugzilla to be served on your server under ``/bugzilla`` path. -For more in depth setup instructions, refer to :ref:`Apache section of this documentation `. - -:command:`a2ensite bugzilla` - -:command:`a2enmod cgi headers expires rewrite` - -:command:`service apache2 restart` +:command:`service mysql restart` Download Bugzilla ================= @@ -135,10 +130,20 @@ Get it from our Git repository: :command:`cd /var/www/webapps` -:command:`git clone --branch release-X.X-stable https://github.com/bugzilla/bugzilla bugzilla` +:command:`git clone https://github.com/bugzilla/harmony.git bugzilla` + +Install Bugzilla +================ + +In the same directory you cloned Bugzilla to, run: + +:command:`perl Makefile.PL` + +:command:`make cpanfile GEN_CPANFILE_ARGS="-D better_xff -D jsonrpc -D xmlrpc -D mysql"` + +:command:`carton install` -(where "X.X" is the 2-digit version number of the stable release of Bugzilla -that you want - e.g. 5.0) +The ``carton`` command will take some time to run. Check Setup =========== @@ -146,23 +151,28 @@ Check Setup Bugzilla comes with a :file:`checksetup.pl` script which helps with the installation process. It will need to be run twice. The first time, it generates a config file (called :file:`localconfig`) for the database -access information, and the second time (step 10) -it uses the info you put in the config file to set up the database. - -:command:`cd /var/www/webapps/bugzilla` +access information. :command:`./checksetup.pl` Edit :file:`localconfig` ======================== +Now you can edit the ``localconfig`` created in the previous step. + :command:`nano localconfig` You will need to set the following values: -* Line 29: set ``$webservergroup`` to ``www-data`` -* Line 67: set ``$db_pass`` to the password for the ``bugs`` user you created - in MariaDB a few steps ago +.. todo:: + is ``$webservergroup`` still needed? + +* :param:`$db_pass`: + :paramval:`the password for the bugs user you created in MariaDB a few steps ago` +* :param:`$urlbase`: + :paramval:`http://localhost:3001/` or :paramval:`http://:3001/` +* :param:`$canonical_urlbase`: + :paramval:`the value you set in $urlbase` Check Setup (again) =================== @@ -171,14 +181,31 @@ Run the :file:`checksetup.pl` script again to set up the database. :command:`./checksetup.pl` -It will ask you to give an email address, real name and password for the -first Bugzilla account to be created, which will be an administrator. -Write down the email address and password you set. +.. todo:: + ./checksetup.pl does not ask for an admin account address and password. + There's an option to promote an existing account to an administrator, + but it doesn't create an account. And you need an admin user to to able + to log in to set up email for account creation. + +Start Server +============ + +The server is started using the ``bugzilla.pl`` script. + +:command:`./bugzilla.pl daemon` + +Will start start Bugzilla as a web app on port 3001. Test Server =========== -:command:`./testserver.pl http://localhost/bugzilla` +.. todo:: + Is this still relevant? I see errors for: + TEST-WARNING Failed to find the GID for the 'httpd' process, unable to validate webservergroup. + Use of uninitialized value $response in pattern match (m//) at ./testserver.pl line 105. + Use of uninitialized value $response in pattern match (m//) at ./testserver.pl line 108. + +:command:`./testserver.pl http://localhost:3001/bugzilla` All the tests should pass. You will get a warning about failing to run ``gdlib-config``; just ignore it. @@ -190,7 +217,7 @@ Access Via Web Browser Access the front page: -:command:`lynx http://localhost/bugzilla` +:command:`lynx http://localhost:3001/` It's not really possible to use Bugzilla for real through Lynx, but you can view the front page to validate visually that it's up and running. @@ -198,9 +225,9 @@ can view the front page to validate visually that it's up and running. You might well need to configure your DNS such that the server has, and is reachable by, a name rather than IP address. Doing so is out of scope of this document. In the mean time, it is available on your local network -at ``http:///bugzilla``, where ```` is (unless you -have a complex network setup) the address starting with 192 displayed when -you run :command:`hostname -I`. +at ``http:///``, where ```` is (unless you +have a complex network setup) the address starting with 192 or 10 displayed +when you run :command:`hostname -I`. Accessing Bugzilla from the Internet ==================================== @@ -233,25 +260,34 @@ Click the :guilabel:`Parameters` link on the page it gives you, and set the following parameters in the :guilabel:`Required Settings` section: * :param:`urlbase`: - :paramval:`http:///bugzilla/` or :paramval:`http:///bugzilla/` + :paramval:`http:///` or :paramval:`http:///` * :param:`ssl_redirect`: :paramval:`on` if you set up an SSL certificate Click :guilabel:`Save Changes` at the bottom of the page. -There are several ways to get Bugzilla to send email. The easiest is to -use Gmail, so we do that here so you have it working. Visit -https://gmail.com and create a new Gmail account for your Bugzilla to use. -Then, open the :guilabel:`Email` section of the Parameters using the link -in the left column, and set the following parameter values: +In order to send bugmail and enable signups for users, you must have: + +* A domain that your Bugzilla instance will send mail from. +* An SMTP host + +The first is usually the domain or subdomain of your Bugzilla hostname. +You will need to set up MX records for the host or service +at the domain name service provider for that domain, please check with +your email provider's documentation. + +The second is a SMTP server you or your organization uses, or a mail +delivery service such as SendGrid or MailGun. + +To configure your Bugzilla installation to send mail, open the Email section +of the Parameters using the link in the left column, and set the following values: * :param:`mail_delivery_method`: :paramval:`SMTP` -* :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com` -* :param:`smtpserver`: :paramval:`smtp.gmail.com:465` -* :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com` -* :param:`smtp_password`: :paramval:`new_gmail_password` +* :param:`mailfrom`: :paramval:`user@domain` +* :param:`smtpserver`: :paramval:`smtp.hostname:465` +* :param:`smtp_username`: :paramval:`username` +* :param:`smtp_password`: :paramval:`password` * :param:`smtp_ssl`: :paramval:`On` Click :guilabel:`Save Changes` at the bottom of the page. -And you're all ready to go. :-) diff --git a/docs/en/rst/installing/web_server.rst b/docs/en/rst/installing/web_server.rst index 42f9a00b7e..354d1443ef 100644 --- a/docs/en/rst/installing/web_server.rst +++ b/docs/en/rst/installing/web_server.rst @@ -3,11 +3,15 @@ Web Server ########## -Bugzilla requires a web server to run CGI scripts. It supports the following: +Bugzilla runs as a web app, but for production use, you will want +to proxy it through a web server. .. toctree:: :maxdepth: 1 apache apache-windows + caddy iis + nginx + -- 2.47.2