From Gentoo Wiki
Jump to:navigation Jump to:search
This article refers to the Bugzilla web application. Go here for the Gentoo Bugzilla guide.
Some of the information in this article may have drifted out of sync with current practices. Please help out by checking over the content (how to get started).
This article has been flagged for not conforming to the wiki guidelines (use of 2nd person pronouns). Please help out, if possible.

Bugzilla is a web application for tracking bugs.


USE flags

USE flags for www-apps/bugzilla Bugzilla is the Bug-Tracking System from the Mozilla project

apache2 Add Apache2 support
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
mysql Add mySQL Database support
postgres Add support for the postgresql database
sqlite Add support for sqlite - embedded sql database
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
vhosts Add support for installing web-based applications into a virtual-hosting environment


You may want first to emerge app-admin/webapp-config and configure it to your liking. Then emerge www-apps/bugzilla:

root #emerge --ask www-apps/bugzilla



Install dev-db/mysql but prefer a 5.x version [1], then create a user for the bugzilla database:

root #mysql -u root -p
mysql> CREATE USER 'bugs'@'localhost' IDENTIFIED BY '$db_pass';
TO bugs@localhost IDENTIFIED BY '$db_pass';
mysql> \q


Once PostgreSQL is installed and set up on the system, install bugzilla with USE=postgres, then create a user and a database for bugzilla to use:

root #su - postgres
postgrescreateuser -U postgres -dRSP bugs

Edit the following configuration file and add the following line (adjust according to PostgeSQL version):

FILE /etc/postgresql-15/pg_hba.conf
host   all    bugs  md5

Then restart the database server:

root #/etc/init.d/postgresql restart


root #rc-service postgresql-15 restart


Change directory to /var/www/localhost/htdocs/bugzilla, then execute checksetup.pl:

root #cd /var/www/localhost/htdocs/bugzilla
root #./checksetup.pl

The first execution produces a localconfig file, in which you have to put the information about the database you use. The comments in that files are self-explanatory. Next, re-run checksetup.pl, which will create the database, configure bugzilla and create the admin user.



Add bugzilla to the default vhost:

FILE /etc/apache2/vhosts.d/default_vhost.include
<Directory "/var/www/localhost/htdocs/bugzilla">
  AddHandler cgi-script .cgi
  Options +ExecCGI +FollowSymLinks
  DirectoryIndex index.cgi index.html
  AllowOverride All

Or alternatively define another vhost, which will make bugzilla directly available at

FILE /etc/apache2/vhosts.d/bugzilla_vhost.conf
<VirtualHost *:80>
    ServerName localhost
    DocumentRoot "/var/www/localhost/htdocs/bugzilla"
    <Directory "/var/www/localhost/htdocs/bugzilla">
        AddHandler cgi-script .cgi
        Options +ExecCGI +FollowSymLinks
        DirectoryIndex index.cgi index.html
        AllowOverride All
        Require all granted
    <IfModule mpm_peruser_module>
        ServerEnvironment apache apache
    CustomLog /var/log/apache2/bugzilla_access.log combined
    ErrorLog /var/log/bugzilla_error.log

Then restart the web server:

root #/etc/init.d/apache2 restart

Web end

Finally, point a web browser to or depending on your configuration. Log in with your admin account and bugzilla will invite you to proceed to the essential post-installation configuration [2].


Before upgrading, one should make backup the application and its database. Note that one cannot downgrade bugzilla. To upgrade bugzilla one can use app-admin/webapp-config [3]. Upgrade is done automatically if the package is emerged without the vhosts flag. Finally you should always run checksetup.pl after upgrading to apply database changes and set file permissions [4].

Upgrades can also be done by hand as follows, which applies if you installed your bugzilla application to /var/www/localhost/htdocs/bugzilla, you may replace this location accordingly. Before emerging bugzilla, move your bugzilla directory:

root #mv /var/www/localhost/htdocs/bugzilla /var/www/localhost/htdocs/bugzilla-old

Then emerge bugzilla:

root #emerge -av www-apps/bugzilla

Next, copy the directories data, lib (may be empty) and template/en/custom (may not exist) from your previous installation to your new installation, together with the previous localconfig file. Then run checksetup.pl:

root #cp /var/www/localhost/htdocs/bugzilla-old/data /var/www/localhost/htdocs/bugzilla/
root #cp -r /var/www/localhost/htdocs/bugzilla-old/lib /var/www/localhost/htdocs/bugzilla/
root #cp -r /var/www/localhost/htdocs/bugzilla-old/template/en/custom var/www/localhost/htdocs/bugzilla/
root #cp /var/www/localhost/htdocs/bugzilla-old/localconfig var/www/localhost/htdocs/bugzilla/
root #cd /var/www/localhost/htdocs/bugzilla/
root #./checksetup.pl

After having ascertained that the new installation works as expected, you may delete your old bugzilla directory.


If after executing checksetup.pl you get something like:

root #/var/www/localhost/htdocs/bugzilla/checksetup.pl
Undefined subroutine utf8::SWASHNEW called at Bugzilla/Util.pm line 104. 
Compilation failed in require at Bugzilla/Mailer.pm line 21,  line 755.
BEGIN failed--compilation aborted at Bugzilla/Mailer.pm line 21,  line 755.
Compilation failed in require at Bugzilla/Auth.pm line 22,  line 755.
BEGIN failed--compilation aborted at Bugzilla/Auth.pm line 22,  line 755.
Compilation failed in require at Bugzilla.pm line 23,  line 755.
BEGIN failed--compilation aborted at Bugzilla.pm line 23,  line 755.
Compilation failed in require at ./checksetup.pl line 75,  line 755.

Try and comment this line [5] [6].

FILE /var/www/localhost/htdocs/bugzilla/Bugzilla/Util.pm
$var =~ tr/\x{202a}-\x{202e}//d;

Then re-execute checksetup.pl.

More documentation

You can find more documentation on the official bugzilla documentation page [7].


  1. https://bugzilla.mozilla.org/show_bug.cgi?id=1604051 [MySQL 8 Compatibility]
  2. https://bugzilla.readthedocs.io/en/5.0/installing/essential-post-install-config.html [Essential Post-Installation Configuration]
  3. Webapp-config
  4. https://bugs.gentoo.org/124282 [Update causes internal error]
  5. Mozilla bug 1588175 - Undefined subroutine utf8::SWASHNEW called at Bugzilla/Util.pm line 109.
  6. Perl issue 17271 - Safe.pm
  7. https://bugzilla.readthedocs.io/en/5.0/index.html [Bugzilla Documentation]