Installing Bugzilla on the Apache Tomcat 6

While Bugzilla is running fine on the traditional Apache server, it is possible to install it on Apache Tomcat (version 6). In the case you already use Tomcat, it might be better not to have two servers running on the machine in order to to reduce the costs of maintaining both of them. This how-to covers steps needed to configure Bugzilla 3.2.6 to run on Tomcat 6 with Ubuntu 10.04 and MySQL 5.

Note: To make the steps educative, we will start with fresh Apache Tomcat installation installed in folder in our home. For production deployment, this is not recommended – you should install and set up Tomcat properly.

Note: Running Bugzilla requires enabled CGI support. CGI scripts are used to execute programs external to the Tomcat JVM. If you are using the Java SecurityManager this will bypass your security policy configuration in catalina.policy.

Get the software

First, it is necessary to install Java, Perl with modules and MySQL Server using the apt-get command:

# In Ubuntu 10.04, you need to add sources with Sun's Java first
sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
sudo apt-get update
sudo apt-get --yes install sun-java6-jdk perl-modules mysql-server

Second, download archives with Bugzilla and Apache Tomcat 6 and then unpack them in appropriate folders. The contents of the archive with the Bugzilla should be extracted directly in the root of the bugzilla webapp folder. Also, create the WEB-INF folder inside the Bugzilla folder.

# create the demo folder in home
cd ~
mkdir demo
cd demo
 
# extract the apache tomcat files
wget http://www.apache.org/dist/tomcat/tomcat-6/v6.0.29/bin/apache-tomcat-6.0.29.tar.gz
gzip -dc apache-tomcat-6.0.29.tar.gz | tar xf -
mv apache-tomcat-6.0.29 apache-tomcat
rm apache-tomcat-6.0.29.tar.gz
 
# extract the bugzilla to webapps folder
cd apache-tomcat/webapps/  
wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-3.6.2.tar.gz
gzip -dc bugzilla-3.6.2.tar.gz | tar xf -
mv bugzilla-3.6.2 bugzilla
rm bugzilla-3.6.2.tar.gz
cd bugzilla
 
#create the WEB-INF and META-INF folder
mkdir WEB-INF
mkdir META-INF

Enabling CGI on Tomcat

By default, Tomcat does not allow execution of the CGI scripts – it is necessary change this. Only the CGI scripts for a single application – just for the Bugzilla – should be enabled.

To enable CGI support, you need to creatre and fix the file ~/demo/apache-tomcat/bugzilla/WEB-INF/web.xml so that it contains the CGI servlet section and CGI servlet-mappings section. It is also a good idea to create a mapping for the folder root to the index.cgi file on the welcome-file-list. After it is modified, the web.xml file should look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">
 
  <servlet>
    <servlet-name>cgi</servlet-name>
    <servlet-class>org.apache.catalina.servlets.CGIServlet</servlet-class>
    <init-param>
      <param-name>debug</param-name>
      <param-value>0</param-value>
    </init-param>
    <init-param>
      <param-name>executable</param-name>
      <param-value>perl -T</param-value>
    </init-param>
    <init-param>
      <param-name>cgiPathPrefix</param-name>
      <param-value></param-value>
    </init-param>
    <load-on-startup>5</load-on-startup>
  </servlet>
 
  <servlet-mapping>
    <servlet-name>cgi</servlet-name>
    <url-pattern>*.cgi</url-pattern>
  </servlet-mapping>
 
  <welcome-file-list>
    <welcome-file>index.cgi</welcome-file>
  </welcome-file-list>
 
</web-app>

Finally, copy the ~/demo/apache-tomcat/conf/context.xml file to the META-INF folder and modify it so that it contains <Context reloadable=“true“ privileged=“true“> instead of just <Context>.

If all steps were performed correctly, the CGI scripts will enabled for the Bugzilla application after the server is started.

Installation of Perl modules

While not all Perl modules are needed for Bugzilla to run, it is easiest to install them all. To install all perl modules, following command must be run:

cd ~/demo/apache-tomcat/webapps/bugzilla
perl install-module.pl --all

Bugzilla Installation

As an initial step of the Bugzilla installation, run the checksetup.pl command for the first time:

cd ~/demo/apache-tomcat/webapps/bugzilla
./checksetup.pl

This run of the checksetup.pl script was not very exhaustive. Since we installed all Perl modules, there should not be any problems with modules. In fact, the only important outcome of running is that a file localconfig is created in the Bugzilla folder. It is now necessary to modify this localconfig file by editing of the following properties:

• $webservergroup – set this to the group of your Linux user
• $db_driver – set this to “mysql” (it should be the default value)
• $db_name – set this to the database name you would like to use, you can leave the default name
• $db_user – set this to the username you will use for accessing MySQL database (or leave the default)
• $db_pass – set a password that will be used for the DB connection

Before the installation process can proceed, you need to configure the MySQL server from the MySQL console. As a basic setup, a new MySQL user must be added specifically for the use with Bugzilla, since it is not a good practice to use the root account for this purpose. Following commands must be performed in the MySQL console to create a new user with appropriate privileges:

mysql –user=root –password=PASSWORD_FOR_MYSQL_ROOT
 
mysql> GRANT SELECT, INSERT,
  UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
  CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
  TO bugs@localhost IDENTIFIED BY '$db_pass';
mysql> FLUSH PRIVILEGES;

Use the exit command to exit the MySQL console.

Now, run the checksetup.pl script again – the installation will proceed completely. New MySQL tables will be created during the process, based on the information you provided in the localconfig file. You will be prompted for an e-mail address, a real name and a password of a Bugzilla administrator too.

Before Bugzilla page can be visited, it is necessary to run the Apache Tomcat 6 server. This can be accomplished by running the startup.sh script in the ~/demo/apache-tomcat/bin folder:

sh ~/demo/apache-tomcat/bin/startup.sh

To test that everything works and CGI scripts are served properly by the server, you can execute the testserver.pl script before opening URL the browser:

cd ~/demo/apache-tomcat/webapps/bugzilla
./testserver.pl http://localhost:8080/bugzilla

At this moment, it should be possible to open the Bugzilla index page in the web browser by typing http://localhost:8080/bugzilla in the web browser address bar.