Bugzilla:Win32Install: Difference between revisions

If you want a single-package installer that will install Apache, MySQL, Perl, and Bugzilla all at once and configure them all for you, check out the [[Bugzilla:Win32InstallPackages|Windows Install Packages]].  

If you prefer to do everything yourself, the below instructions explain how to manually configure Bugzilla on Windows.  

== Installing Bugzilla on Microsoft Windows ==

'''Original author: [http://bugzilla.glob.com.au/ Byron Jones]'''

Bugzilla version 2.18 was the first release that runs unmodified on Windows. This document guides you step by step through the installation process.  

Note that there are a few things that don't work very well on Windows, such as mod_perl.  

=== Bugzilla ===

There's two main methods to getting the Bugzilla source - from CVS or in a tarball. The best method for fetching Bugzilla is to grab it directly from CVS, as this will allow for simple upgrades, even if you have customised Bugzilla.  

Read the [http://www.bugzilla.org/releases/3.2/release-notes.html Release Notes] before you do anything.  

==== Installing Bugzilla From CVS ====

Download the CVSNT client from [http://www.cvsnt.org/] (2.15 Meg).  

Run the installation, you'll only need to install the '''Command line client''' and the '''Password Server (:pserver:) Protocol'''. Once the install has completed, log out and log in again to pick up the changes to the PATH.  

Note: this document assumes you want to install Bugzilla into '''C:\Bugzilla'''.  

Open the command line, and cd to the '''parent''' of the directory you want to install Bugzilla into. As we'll be installing Bugzilla into '''C:\Bugzilla''', the current directory must be '''C:\'''.  

  C:\>'''set CVSROOT=:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot'''

  C:\>'''cvs login'''

  Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401:/cvsroot

  CVS password: '''anonymous'''

  C:\>'''cvs checkout -d Bugzilla -rBugzilla_Stable Bugzilla'''

==== Upgrading From CVS ====

If you've already installed an earlier version of Bugzilla from CVS or from a TarBall, updating is easy. Even if you've made customisations, CVS is smart enough to merge. If CVS needs help merging, it displays a C in the first column of its report. You need to resolve such conflicts manually.  

  C:\Bugzilla>'''cvs update -R -d -rBugzilla_Stable'''

==== Installing Bugzilla From the TarBall ====

Download Bugzilla from [http://bugzilla.org/download.html] (2.4 Meg).  

Bugzilla ships as a Tarball, which has the extension .tar.gz. Any decent Windows archive tool should be able to extract tarballs.  

Extract the archive to the directory of your choice. For the remainder of this document I will assume that you have extracted Bugzilla into '''C:\Bugzilla'''.  

==== Upgrading From TarBall ====

If you installed Bugzilla from the TarBall, the simplest way to upgrade is to follow the '''CVS Upgrading''' instructions.  

=== MySQL ===

==== Download MySQL ====

Download the MySQL "Windows Essentials" installer from [http://dev.mysql.com/downloads/mysql/4.1.html#Windows http://dev.mysql.com/downloads/mysql/4.1.html] (14.1 Meg).  

MySQL 5.x is now stable enough and can be used.  

==== Install ====

and edit  

max_allowed_packet to 4M&nbsp; <br>unter there add<br>ft_min_word_len = 2 <br><br>  

==== Create Bugs Database User ====

Use the '''mysql''' command line utility to create a MySQL account for Bugzilla.  

Note in the following example 'sockmonkey' is my password for the bugs account:  

  C:\mysql\bin&gt;'''mysql --user=root -p mysql'''

  Enter password: '''********'''

  Welcome to the MySQL monitor.  Commands end with&nbsp;; or \g.

  mysql&gt; '''GRANT ALL PRIVILEGES ON bugs.* TO 'bugs'@'localhost' IDENTIFIED BY 'sockmonkey';'''

  mysql&gt; '''quit'''

If you are running MySQL 4.1, you may encounter the '''Client does not support authentication protocol requested by server''' error message. To fix this, once the user has been created you will have to reset the password using OLD_PASSWORD:  

  C:\mysql\bin&gt;'''mysql --user=root -p mysql'''

  Enter password: '''********'''

  Welcome to the MySQL monitor.  Commands end with&nbsp;; or \g.

  mysql&gt; '''set password for 'bugs'@'localhost' = OLD_PASSWORD('sockmonkey');'''

  mysql&gt; '''quit'''

=== ActiveState Perl ===

==== Download ActiveState Perl 5.8.1 or Higher ====

Download the ActiveState Perl 5.8.1 or Higher MSI from: http://activestate.com/Products/Download/Download.plex?id=ActivePerl (12.5 Meg).  

Note that Bugzilla requires ActiveState Perl 5.8.1 as it needs CGI.pm version 2.93 or higher. 5.8.0 ships with CGI.pm version 2.81, 5.8.1 ships with CGI.pm version 3.00.  

There is [https://bugzilla.mozilla.org/show_bug.cgi?id=281920 a bug in Time::Local 1.10], which is shipped with ActiveState Perl 5.8.6, that will cause warnings to be generated at the top of every buglist. It's a good idea to avoid version 5.8.6 (version 5.8.4 works without issue).  

==== Install ====

ActiveState Perl uses a standard Windows Installer. Install, sticking with the defaults, which will install Perl into '''C:\Perl'''.  

Note: Installing Perl into a directory that contains a space (eg "C:\Program Files") will break the Template-Toolkit installer.  

Once the install has completed, log out and log in again to pick up the changes to the PATH.  

==== Upgrading Existing Installs ====

If you already have ActiveState Perl installed, now's a good time to ensure you're running the latest version of ActiveState Perl, along with the latest versions of the modules.  

To upgrade ActiveState Perl, follow the directions at: [http://aspn.activestate.com/ASPN/docs/ActivePerl/install.html#upgrade_56 http://aspn.activestate.com/ASPN/docs/ActivePerl/install.html]  

To upgrade your modules, simply run '''ppm upgrade'''

==== Create Temp Directory ====

On Windows, Perl has a hard time of locating the correct directory to write its temporary files (CGI.pm, File::Spec). Basically it has a list of paths hard coded to use, instead of querying Windows for the correct path.  

To avoid problems, create the '''C:\Temp''' directory (it has to be on drive C) and ensure SYSTEM has write and modify access.  

Bugzilla requires a number of perl modules to be installed. They are available in the ActiveState repository and the following additional repositories:<br>Perl 5.8.x:<br>&nbsp;&nbsp;&nbsp;'''http://theoryx5.uwinnipeg.ca/ppms/'''<br>Perl 5.10.x:<br>&nbsp;&nbsp;&nbsp;'''http://cpan.uwinnipeg.ca/PPMPackages/10xx/''' and<br>&nbsp;&nbsp;&nbsp;'''http://trouchelle.com/ppm10/'''<br>  

=== Apache ===

It is recommended that you run Bugzilla with the Apache web server. If you want to use IIS to run Bugzilla, there are [http://www.bugzilla.org/docs/2.20/html/configuration.html#http-iis configuration instructions] in the Bugzilla documentation.  

==== Download Apache 2.x ====

Download the Apache HTTP Server version 2.x or high from: http://httpd.apache.org/download.cgi (5.8 Meg).  

==== Install ====

Yet another standard Windows Installer. Just follow the prompts, making sure you Install for All Users. Be aware the Apache will always install itself into an '''Apache2''' directory under what ever path you specify. The default install path will be displayed as '''C:\Program Files\Apache Group''' which will result in Apache being installed to '''C:\Program Files\Apache Group\Apache2'''. This gets me every time.  

For the remainder of this document I will assume you installed Apache into the default location, '''C:\Program Files\Apache Group\Apache2'''.  

If you are already running IIS, you must configure apache to run on a port other than 80, however you aren't asked the port to listen on at install time. Choose '''All Users''' (which says port 80), and we'll change the port later.  

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 user that is a member of '''no''' groups, and reconfigure the Apache2 service to run as that account.  

==== Grant write access for Apache account ====

By default Apache will run as the SYSTEM account. This account needs write and modify access to the following directorys, and all their subdirectories. Depending on your version of Windows, this access may already be granted.  

*C:\Bugzilla\data  

*C:\Program Files\Apache Group\Apache2\logs  

*C:\Temp  

Note that '''C:\Bugzilla\data''' is created the first time you run '''checksetup.pl'''.  

==== Configure Port and DocumentRoot ====

Edit '''C:\Program Files\Apache Group\Apache2\conf\httpd.conf''' with your [http://www.vim.org/ favourite text editor].  

To change the port that Apache runs on (listens on, or binds to), edit the '''Listen''' option.  

  '''Listen 80'''

 

Change the '''DocumentRoot''' setting to point to '''C:\Bugzilla'''. Note there are two locations in '''httpd.conf''' that need to be updated. Note you need to use / instead of \ as a path separator.  

  '''DocumentRoot "C:/Bugzilla"'''

    Options FollowSymLinks

    AllowOverride None

  '''&lt;Directory "C:/Bugzilla"&gt;'''

==== Configure CGI ====

To enable CGI support in Apache, you need to enable the CGI handler, by uncommenting the '''AddHandler cgi-script .cgi''' line.  

  '''AddHandler cgi-script .cgi'''

And allow .cgi scripts in the Bugzilla directory by adding the '''ExecCGI''' option. We also need to allow Bugzilla's .htaccess file to restrict access to sensitive documents by allowing it to override the defaults. This involves changing '''AllowOverride None''' to '''AllowOverride All'''.  

Apache also needs to know to use Perl to execute .cgi files, via the '''ScriptInterpreterSource''' directive.  

  '''   Options Indexes FollowSymLinks ExecCGI'''

  '''   AllowOverride All'''

    Order allow,deny

    Allow from all

  '''#

     ScriptInterpreterSource Registry-Strict'''

You also should add '''index.cgi''' to the '''DirectoryIndex''' list.  

  '''DirectoryIndex index.html index.html.var index.cgi'''

In order for '''ScriptInterpreterSource Registry-Strict''' to work, you also need to add an entry to the Registry so Apache will use Perl to execute .cgi files.  

Create a key '''HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command''' with the default value of the full path of perl.exe with a -T parameter. For example '''C:\Perl\bin\perl.exe -T'''

[[Image:Bugzilla-Regedit.png|100px|Regedit]]  

==== Disable 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.  

  '''#CustomLog logs/access.log common'''

==== Restart Apache ====

Finally, restart Apache to get it pick up the changes.  

  C:\&gt;'''net stop apache2'''

  C:\&gt;'''net start apache2'''

=== Extras ===

While Bugzilla 2.20 has built in support for SMTP servers, it doesn't (yet) support SMTP authentication or debugging of SMTP errors.  

If you require SMTP authentiation (including POP before SMTP), you can use [http://www.glob.com.au/sendmail/ Glob's sendmail wrapper]. Download and install as per the instructions on that site.  

If you enable logging in Sendmail, you need to ensure that your Apache account has write access to '''C:\usr\lib'''.  

=== Configure Bugzilla ===

==== checksetup.pl ====

Run '''checksetup.pl'''. This will check your Perl modules and create '''localconfig'''.  

  C:\&gt;'''cd bugzilla'''

  C:\bugzilla&gt;'''perl checksetup.pl'''

    http://www.apache.org/dyn/closer.cgi/perl/win32-bin/ppms/

    ppm rep add apache http://www.apache.org/dist/perl/win32-bin/ppms/

==== Edit localconfig ====

Open '''C:\Bugzilla\localconfig''' in your favourite text editor to configure Bugzilla.  

You have to tell Bugzilla how to access your database. If you used bugs/bugs, you'll only have to set '''db_pass'''.  

  '''$db_pass = 'sockmonkey';'''

==== checksetup.pl ====

Run '''checksetup.pl''' again. This time it will build your database tables and initialise Bugzilla.  

  Enter the e-mail address of the administrator: '''byron@example.com'''

  You entered 'byron@example.com'.  Is this correct? [Y/n] '''y'''

  Enter the real name of the administrator: '''Byron Jones'''

  Enter a password for the administrator account: '''beef'''

  Please retype the password to verify: '''beef'''

 

 

 

 

==== Parameters ====

You should now be able to log into to Bugzilla using the account '''checksetup.pl''' just created. Point your web browser to &gt;http://localhost/, choose '''Log in to an existing account''', and login.  

In the page footer, choose '''Parameters'''.  

Put in your email address as the '''maintainer'''.  

  '''byron@example.com'''

Put in the URL to Bugzilla in the '''urlbase''' field. This URL will be used in emails, so don't use localhost.  

  '''http://bugzilla.example.com/'''

Download and install WebDot from http://www.graphviz.org/Download_windows.php. Put the complete path to dot.exe in '''webdotbase'''.  

  '''C:/Program Files/ATT/Graphviz/bin/dot.exe'''

=== Scheduled Tasks ===

==== collectstats.pl ====

Add a Scheduled Task to run '''collectstats.pl''' nightly.  

'''Step-by-step for Windows XP:'''

#Control Panel --&gt; Scheduled Tasks --&gt; Add Scheduled Task  

#Next  

#Browse  

#Find '''perl.exe''' (normally '''C:\Perl\bin\perl.exe''')  

#Give it a name, such as "Bugzilla Collect Stats"  

#Perfom the task daily at your desired time  

#If you're running Apache as a user, not as SYSTEM, enter that user here. Otherwise you're best off creating an account that has write access to the Bugzilla directory and using that  

#Tick "Open Advanced Properties.." and click Finish  

#Append the script name to the end of the "Run" field. eg '''C:\Perl\bin\perl.exe C:\Bugzilla\collectstats.pl'''

==== whineatnews.pl ====

Add a Scheduled Task to run '''whineatnews.pl''' nightly.  

The steps for setting up '''whineatnews.pl''' are as per '''collectstats.pl'''

==== Backing up Bugzilla ====

You may want to backup the entire Bugzilla directory. It's small and you'll get all your settings and customisations on your backup media.  

The most important component of Bugzilla to backup is the Bugzilla Database. It contains all your Bugs, Users, Attachments, pretty well everything. Like most databases, backups with MySql are performed by generating a dump of the database and backing up the dump.  

Schedule the '''mysqldump''' utility to create the dump, and add the resulting file to your backup media. You'll find MySql's '''mysqldump''' documentation at http://dev.mysql.com/doc/mysql/en/mysqldump.html.  

==== Congratulations, the Bugzilla installation process is complete! ====