3.2. Linux
**********

Some Linux distributions include Bugzilla and its dependencies in
their package management systems. If you have root access, installing
Bugzilla on any Linux system could be as simple as finding the
Bugzilla package in the package management application and installing
it. There may be a small bit of additional configuration required.

If you are installing your machine from scratch, Quick Start (Ubuntu
Linux 22.04) may be the best instructions for you.


3.2.1. Install Packages
=======================

Use your distribution's package manager to install Perl, your
preferred database engine (MySQL or MariaDB if in doubt), and a
webserver (Apache if in doubt). Some distributions even have a
Bugzilla package, although that will vary in age.

The commands below will install those things and some of Bugzilla's
other prerequisites as well. If you find a package doesn't install or
the name is not found, just remove it from the list and reissue the
command. If you want to use a different database or webserver,
substitute the package names as appropriate.


3.2.1.1. Fedora, CentOS Stream and RHEL
---------------------------------------

The following command will install Fedora's packaged version of
Bugzilla:

**dnf install bugzilla httpd mariadb-server**

Then, you can skip to configuring your database. It may be useful to
know that Fedora stores the Bugzilla files in "/usr/share/bugzilla",
so that's where you'll run "checksetup.pl".

If you want to install a version of Bugzilla from the Bugzilla project
or have it on RHEL or CentOS, you will need to do the following
instead:

On CentOS Stream and RHEl, add the Fedora EPEL repo, in the way
described in the installation instructions.

Run the following to install the base Bugzilla dependencies:

**dnf install git httpd httpd-devel mariadb-devel gcc mariadb-server
mod_perl mod_perl-devel 'perl(autodie)' 'perl(CGI)'
'perl(Date::Format)' 'perl(DateTime)' 'perl(DateTime::TimeZone)'
'perl(DBI)' 'perl(DBD::mysql)' 'perl(DBIx::Connector)'
'perl(Digest::SHA)' 'perl(Email::MIME)' 'perl(Email::Sender)'
'perl(fields)' 'perl(JSON::XS)' 'perl(List::MoreUtils)'
'perl(Math::Random::ISAAC)' 'perl(Memoize)' 'perl(Safe)'
'perl(Template)' 'perl(URI)'**

On Fedora, all the optional dependencies are available:

**dnf install gd-devel graphviz patchutils 'perl(Apache2::SizeLimit)'
'perl(Authen::Radius)' 'perl(Authen::SASL)' 'perl(Cache::Memcached)'
'perl(Chart::Lines)' 'perl(Daemon::Generic)' 'perl(Email::Reply)'
'perl(Encode)' 'perl(Encode::Detect)' 'perl(File::Copy::Recursive)'
'perl(File::MimeInfo::Magic)' 'perl(File::Which)' 'perl(GD)'
'perl(GD::Graph)' 'perl(GD::Text)' 'perl(HTML::FormatText::WithLinks)'
'perl(HTML::Parser)' 'perl(HTML::Scrubber)' 'perl(IO::Scalar)'
'perl(JSON::RPC)' 'perl(LWP::UserAgent)' 'perl(MIME::Parser)'
'perl(mod_perl2)' 'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)'
'perl(PatchReader)' 'perl(SOAP::Lite)'
'perl(Template::Plugin::GD::Image)' 'perl(Test::Taint)'
'perl(TheSchwartz)' 'perl(XMLRPC::Lite)' 'perl(XML::Twig)'**

On CentOS Stream and RHEL with EPEL, some modules are missing in the
repositories, so use the following instead:

**dnf install gd-devel graphviz patchutils 'perl(Apache2::SizeLimit)'
'perl(Authen::Radius)' 'perl(Authen::SASL)' 'perl(Cache::Memcached)'
'perl(Encode)' 'perl(Encode::Detect)' 'perl(File::Copy::Recursive)'
'perl(File::MimeInfo::Magic)' 'perl(File::Which)' 'perl(GD)'
'perl(GD::Graph)' 'perl(GD::Text)' 'perl(HTML::Parser)'
'perl(HTML::Scrubber)' 'perl(IO::Scalar)' 'perl(JSON::RPC)'
'perl(LWP::UserAgent)' 'perl(MIME::Parser)' 'perl(mod_perl2)'
'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)' 'perl(SOAP::Lite)'
'perl(Test::Taint)' 'perl(XMLRPC::Lite)' 'perl(XML::Twig)'**

and install the missing optional modules with:

**cd /var/www/html/bugzilla/ && ./install-module.pl Chart::Lines
Daemon::Generic Email::Reply HTML::FormatText::WithLinks PatchReader
Template::Plugin::GD::Image TheSchwartz**

If you plan to use a database other than MariaDB, you will need to
also install the appropriate packages for that.


3.2.1.2. Ubuntu and Debian
--------------------------

You can install required packages with: **apt install apache2 build-
essential git libcgi-pm-perl libdatetime-perl libdatetime-timezone-
perl libdbi-perl libdbix-connector-perl libdigest-sha-perl libemail-
address-perl libemail-mime-perl libemail-sender-perl libjson-xs-perl
liblist-moreutils-perl libmath-random-isaac-perl libtemplate-perl
libtimedate-perl liburi-perl libmariadb-dev-compat libdbd-mysql-perl
mariadb-server**

If you plan to use a database other than MariaDB, you will need to
also install the appropriate packages for that (in the command above,
the packages required for MariaDB are "libdbd-mysql-perl",
"libmariadb-dev-compat" and "mariadb-server").

You can install optional packages with: **apt install graphviz
libapache2-mod-perl2 libapache2-mod-perl2-dev libauthen-radius-perl
libauthen-sasl-perl libcache-memcached-perl libchart-perl libdaemon-
generic-perl libemail-reply-perl libencode-detect-perl libencode-perl
libfile-copy-recursive-perl libfile-mimeinfo-perl libfile-which-perl
libgd-dev libgd-graph-perl libgd-perl libgd-text-perl libhtml-
formattext-withlinks-perl libhtml-parser-perl libhtml-scrubber-perl
libio-stringy-perl libjson-rpc-perl libmime-tools-perl libnet-ldap-
perl libnet-smtp-ssl-perl libsoap-lite-perl libtemplate-plugin-gd-perl
libtest-taint-perl libtheschwartz-perl libwww-perl libxmlrpc-lite-perl
libxml-twig-perl**

There is no Ubuntu package for "PatchReader" and so you will have to
install that module outside the package manager if you want it.


3.2.1.3. Gentoo
---------------

**emerge -av bugzilla**

will install Bugzilla and all its dependencies. If you don't have the
vhosts USE flag enabled, Bugzilla will end up in
"/var/www/localhost/bugzilla".

Then, you can skip to configuring your database.


3.2.1.4. openSUSE
-----------------

**zypper in bugzilla**

has been available in the openSUSE Leap repositories since 15.2 and is
in the openSUSE Tumbleweed repositories, also comes with an optional
"bugzilla-apache" package, that allows you to skip to configuring your
database


3.2.2. Perl
===========

Test which version of Perl you have installed with:

   $ perl -v

Bugzilla requires at least Perl 5.14.0.


3.2.3. Bugzilla
===============

The best way to get Bugzilla is to check it out from git:

**git clone --branch release-X.X-stable
https://github.com/bugzilla/bugzilla**

Run the above command in your home directory, replacing "X.X" with the
2-digit version number of the stable release of Bugzilla that you want
- e.g. "4.4".

If that's not possible, you can download a tarball of Bugzilla.

Place Bugzilla in a suitable directory, accessible by the default web
server user (probably "apache" or "www-data"). Good locations are
either directly in the web server's document directory (often
"/var/www/html") or in "/usr/local", either with a symbolic link to
the web server's document directory or an alias in the web server's
configuration.

Warning:

  The default Bugzilla distribution is NOT designed to be placed in a
  "cgi-bin" directory. This includes any directory which is configured
  using the "ScriptAlias" directive of Apache.


3.2.4. Perl Modules
===================

Bugzilla requires a number of Perl modules. You can install these
globally using your system's package manager, or install Bugzilla-only
copies. At times, Bugzilla may require a version of a Perl module
newer than the one your distribution packages, in which case you will
need to install a Bugzilla-only copy of the newer version.

At this point you probably need to become "root", e.g. by using
**su**. You should remain as root until the end of the install. This
can be avoided in some circumstances if you are a member of your
webserver's group, but being root is easier and will always work.

To check whether you have all the required modules, run:

**./checksetup.pl --check-modules**

You can run this command as many times as necessary.

If you have not already installed the necessary modules, and want to
do it system-wide, invoke your package manager appropriately at this
point. Alternatively, you can install all missing modules locally
(i.e. just for Bugzilla) like this:

**./install-module.pl --all**

Or, you can pass an individual module name:

**./install-module.pl <modulename>**


3.2.5. Web Server
=================

Any web server that is capable of running CGI scripts can be made to
work. We have specific configuration instructions for the following:

* Apache


3.2.6. Database Engine
======================

Bugzilla supports MySQL (or MariaDB, its compatible counterpart),
PostgreSQL, Oracle and SQLite as database servers. You only require
one of these systems to make use of Bugzilla. MySQL or MariaDB are
most commonly used. SQLite is good for trial installations as it
requires no setup. Configure your server according to the instructions
below:

* MySQL

* PostgreSQL

* Oracle

* SQLite


3.2.7. localconfig
==================

You should now change into the Bugzilla directory and run
"checksetup.pl", without any parameters:

**./checksetup.pl**

"checksetup.pl" will write out a file called "localconfig". This file
contains the default settings for a number of Bugzilla parameters, the
most important of which are the group your web server runs as, and
information on how to connect to your database.

Load this file in your editor. You will need to check/change
"$db_driver" and "$db_pass", which are respectively the type of the
database you are using and the password for the "bugs" database user
you have created. "$db_driver" can be either "mysql", "Pg"
(PostgreSQL), "Oracle" or "Sqlite". All values are case sensitive.

Set the value of "$webservergroup" to the group your web server runs
as.

* Fedora/Red Hat: "apache"

* Debian/Ubuntu: "www-data"

* Mac OS X: "_www"

* Windows: ignore this setting; it does nothing

The other options in the "localconfig" file are documented by their
accompanying comments. If you have a non-standard database setup, you
may need to change one or more of the other "$db_*" parameters.

Note:

  If you are using Oracle, "$db_name" should be set to the SID name of
  your database (e.g. "XE" if you are using Oracle XE).


3.2.8. checksetup.pl
====================

Next, run "checksetup.pl" an additional time:

**./checksetup.pl**

It reconfirms that all the modules are present, and notices the
altered localconfig file, which it assumes you have edited to your
satisfaction. It compiles the UI templates, connects to the database
using the "bugs" user you created and the password you defined, and
creates the "bugs" database and the tables therein.

After that, it asks for details of an administrator account. Bugzilla
can have multiple administrators - you can create more later - but it
needs one to start off with. Enter the email address of an
administrator, his or her full name, and a suitable Bugzilla password.

"checksetup.pl" will then finish. You may rerun "checksetup.pl" at any
time if you wish.


3.2.9. Success
==============

Your Bugzilla should now be working. Check by running:

**./testserver.pl http://<your-bugzilla-server>/**

If that passes, access "http://<your-bugzilla-server>/" in your
browser - you should see the Bugzilla front page. Of course, if you
installed Bugzilla in a subdirectory, make sure that's in the URL.

Next, do the Essential Post-Installation Configuration.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.
