<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.72.2.14 2004/12/21 20:43:12 jake%bugzilla.org Exp $ -->
+<!-- $Id: installation.xml,v 1.72.2.15 2005/01/10 06:35:27 travis%sedsystems.ca Exp $ -->
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
<para>
By default, MySQL will limit the size of a table to 4GB.
This limit is present even if the underlying filesystem
- has no such limit or if you are using RAID. To set a higher
- limit, follow these instructions.
+ has no such limit. To set a higher limit, follow these
+ instructions.
</para>
<para>
<section id="http-iis">
<title>Microsoft <productname>Internet Information Services</productname></title>
- <para>If you need, or for some reason even want, to use Microsoft's
- <productname>Internet Information Services</productname> or
- <productname>Personal Web Server</productname> you should be able
- to. You will need to configure them to know how to run CGI scripts.
- This is described in Microsoft Knowledge Base article
- <ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink>
- for <productname>Internet Information Services</productname> and
- <ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink>
- for <productname>Personal Web Server</productname>.
+ <para>
+ If you are running Bugzilla on Windows and choose to use
+ Microsoft's <productname>Internet Information Services</productname>
+ or <productname>Personal Web Server</productname> you will need
+ to perform a number of other configuration steps as explained below.
+ You may also want to refer to the following Microsoft Knowledge
+ Base articles:
+ <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink>
+ <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0,
+ 5.0, and 5.1</quote> (for <productname>Internet Information
+ Services</productname>) and
+ <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink>
+ <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
+ Server on Windows 95/98</quote> (for <productname>Personal Web
+ Server</productname>).
+ </para>
+
+ <para>
+ You will need to create a virtual directory for the Bugzilla
+ install. Put the Bugzilla files in a directory that is named
+ something <emphasis>other</emphasis> than what you want your
+ end-users accessing. That is, if you want your users to access
+ your Bugzilla installation through
+ <quote>http://<yourdomainname>/Bugzilla</quote>, then do
+ <emphasis>not</emphasis> put your Bugzilla files in a directory
+ named <quote>Bugzilla</quote>. Instead, place them in a different
+ location, and then use the IIS Administration tool to create a
+ Virtual Directory named "Bugzilla" that acts as an alias for the
+ actual location of the files. When creating that virtual directory,
+ make sure you add the <quote>Execute (such as ISAPI applications or
+ CGI)</quote> access permission.
+ </para>
+
+ <para>
+ You will also need to tell IIS how to handle Bugzilla's
+ .cgi files. Using the IIS Administration tool again, open up
+ the properties for the new virtual directory and select the
+ Configuration option to access the Script Mappings. Create an
+ entry mapping .cgi to:
+ </para>
+
+ <programlisting>
+<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s
+ </programlisting>
+
+ <para>
+ For example:
+ </para>
+
+ <programlisting>
+c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
+ </programlisting>
+
+ <note>
+ <para>
+ The ActiveState install may have already created an entry for
+ .pl files that is limited to <quote>GET,HEAD,POST</quote>. If
+ so, this mapping should be <emphasis>removed</emphasis> as
+ Bugzilla's .pl files are not designed to be run via a webserver.
+ </para>
+ </note>
+
+ <para>
+ IIS will also need to know that the index.cgi should be treated
+ as a default document. On the Documents tab page of the virtual
+ directory properties, you need to add index.cgi as a default
+ document type. If you wish, you may remove the other default
+ document types for this particular virtual directory, since Bugzilla
+ doesn't use any of them.
</para>
- <para>Also, and this can't be stressed enough, make sure that files such as
- <filename>localconfig</filename> and your <filename class="directory">data</filename>
- directory are secured as described in <xref linkend="security-webserver-access"/>.
+ <para>
+ Also, and this can't be stressed enough, make sure that files
+ such as <filename>localconfig</filename> and your
+ <filename class="directory">data</filename> directory are
+ secured as described in <xref linkend="security-webserver-access"/>.
</para>
</section>
<programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting>
- <para>After two days have passed you'll be able to view bug graphs from
- the Reports page.</para>
+ <para>
+ After two days have passed you'll be able to view bug graphs from
+ the Reports page.
+ </para>
+
+ <para>
+ <note>
+ Windows does not have 'cron', but it does have the Task
+ Scheduler, which performs the same duties. There are also
+ third-party tools that can be used to implement cron, such as
+ <ulink url="http://www.nncron.ru/">nncron</ulink>.
+ </note>
+ </para>
</section>
<section>
which leave their bugs in the NEW or REOPENED state without triaging them.
</para>
<para>
-
- This can be done by
- adding the following command as a daily crontab entry, in the same manner
- as explained above for bug graphs. This example runs it at 12.55am.
+ This can be done by adding the following command as a daily
+ crontab entry, in the same manner as explained above for bug
+ graphs. This example runs it at 12.55am.
</para>
<programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting>
-
+
+ <para>
+ <note>
+ Windows does not have 'cron', but it does have the Task
+ Scheduler, which performs the same duties. There are also
+ third-party tools that can be used to implement cron, such as
+ <ulink url="http://www.nncron.ru/">nncron</ulink>.
+ </note>
+ </para>
</section>
<section id="patch-viewer">
<section id="os-win32">
<title>Microsoft Windows</title>
-
- <para>Making Bugzilla work on Windows is still a painful processes.
- The Bugzilla Team is working to make it easier, but that goal is not
- considered a top priority. If you wish to run Bugzilla, we still
- recommend doing so on a Unix based system such as GNU/Linux. As of this
- writing, all members of the Bugzilla team and all known large installations
- run on Unix based systems.
- </para>
-
- <para>If after hearing all that, you have enough pain tolerance to attempt
- installing Bugzilla on Win32, here are some pointers.
+ <para>
+ Making Bugzilla work on Windows is more difficult than making it
+ work on Unix. For that reason, we still recommend doing so on a Unix
+ based system such as GNU/Linux. That said, if you do want to get
+ Bugzilla running on Windows, you will need to make the following
+ adjustments.
</para>
<section id="win32-perl">
<title>Win32 Perl</title>
-
- <para>Perl for Windows can be obtained from <ulink
- url="http://www.activestate.com/">ActiveState</ulink>. You should be
- able to find a compiled binary at <ulink
- url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/"/>.
+ <para>
+ Perl for Windows can be obtained from
+ <ulink url="http://www.activestate.com/">ActiveState</ulink>.
+ You should be able to find a compiled binary at <ulink
+ url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />.
+ The following instructions assume that you are using version
+ 5.8.1 of ActiveState.
</para>
</section>
<section id="win32-perlmodules">
<title>Perl Modules on Win32</title>
- <para>Bugzilla on Windows requires the same perl modules found in
- <xref linkend="install-perlmodules"/>. The main difference is that
- windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead of
- CPAN.
+ <para>
+ Bugzilla on Windows requires the same perl modules found in
+ <xref linkend="install-perlmodules"/>. The main difference is that
+ windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead
+ of CPAN.
</para>
<programlisting>
C:\perl> <command>ppm install <module name></command>
</programlisting>
- <note>
- <para>The above syntax should work for all modules with the exception
- of Template Toolkit. The <ulink
- url="http://tt2.org/download.html#win32">Template Toolkit website</ulink>
- suggests using the instructions on <ulink
- url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>.
- </para>
-
- <para>The following commands will install the required packages
- missing from the ActivePerl default installation:
- </para>
+ <para>
+ The best source for the Windows PPM modules needed for Bugzilla
+ is probably the the Bugzilla Test Server (aka 'Landfill'), so
+ you should add the Landfill package repository as follows:
+ </para>
- <programlisting>
-<command>ppm repository add oi http://openinteract.sourceforge.net/ppmpackages</command>
-<command>ppm install DBD-mysql</command>
-<command>ppm install Template-Toolkit</command>
-<command>ppm install TimeDate</command>
- </programlisting>
+ <programlisting>
+<command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command>
+ </programlisting>
+ <note>
+ <para>
+ The PPM repository stores modules in 'packages' that may have
+ a slightly different name than the module. If retrieving these
+ modules from there, you will need to pay attention to the information
+ provided when you run <command>checksetup.pl</command> as it will
+ tell you what package you'll need to install.
+ </para>
</note>
+
+ <para>
+ <tip>
+ If you are behind a corporate firewall, you will need to let the
+ ActiveState PPM utility know how to get through it to acccess
+ the repositories by setting the HTTP_proxy system environmental
+ variable. For more information on setting that variable, see
+ the ActiveState documentation.
+ </tip>
+ </para>
</section>
<section id="win32-code-changes">
<title>Code changes required to run on win32</title>
- <para>Bugzilla on win32 is mostly supported out of the box; one remaining issue is
- related to bug email. To make bug email work on Win32 (until
- <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=84876">bug
- 84876</ulink> lands), the
- simplest way is to have the Net::SMTP Perl module installed and
- change this line in the file Bugzilla/Bugmail.pm:</para>
+ <para>
+ Bugzilla on win32 is mostly supported out of the box; one
+ remaining issue is related to bug email. To make bug email
+ work on Win32 (until
+ <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=49893">bug
+ 49893</ulink> lands), the
+ simplest way is to have the Net::SMTP Perl module installed and
+ change this line in the file Bugzilla/Bugmail.pm:
+ </para>
<programlisting>
open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") ||
print SENDMAIL trim($msg) . "\n";
close SENDMAIL;
</programlisting>
- <para>to</para>
+
+ <para>
+ to
+ </para>
+
<programlisting>
use Net::SMTP;
my $smtp_server = 'smtp.mycompany.com'; # change this
$smtp->quit;
</programlisting>
- <para>Don't forget to change the name of your SMTP server and the
- domain of the sending email address (after the '@') in the above
- lines of code.</para>
+ <para>
+ Don't forget to change the name of your SMTP server and the
+ domain of the sending email address (after the '@') in the
+ above lines of code.
+ </para>
</section>
<section id="win32-http">
<title>Serving the web pages</title>
- <para>As is the case on Unix based systems, any web server should be
- able to handle Bugzilla; however, the Bugzilla Team still recommends
- Apache whenever asked. No matter what web server you choose, be sure
- to pay attention to the security notes in <xref linkend="security-webserver-access"/>.
- More information on configuring specific web servers can be found in
- <xref linkend="http"/>.
+ <para>
+ As is the case on Unix based systems, any web server should
+ be able to handle Bugzilla; however, the Bugzilla Team still
+ recommends Apache whenever asked. No matter what web server
+ you choose, be sure to pay attention to the security notes
+ in <xref linkend="security-webserver-access"/>. More
+ information on configuring specific web servers can be found
+ in <xref linkend="http"/>.
</para>
<note>
- <para>If using Apache on windows, you can set the <ulink
- url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
- directive in your Apache config to avoid having
- to modify the first line of every script to contain your path to
- perl instead of <filename>/usr/bin/perl</filename>.
+ <para>
+ If using Apache on windows, you can set the <ulink
+ url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
+ directive in your Apache config to avoid having to modify
+ the first line of every script to contain your path to perl
+ perl instead of <filename>/usr/bin/perl</filename>.
</para>
</note>
<section id="modules-manual-instructions">
<title>Instructions</title>
- <para>If you need to install Perl modules manually, here's how it's done.
- Download the module using the link given in the next section, and then
- apply this magic incantation, as root:
+ <para>
+ If you need to install Perl modules manually, here's how it's done.
+ Download the module using the link given in the next section, and then
+ apply this magic incantation, as root:
</para>
<para>
<prompt>bash#</prompt> make test
<prompt>bash#</prompt> make install</screen>
</para>
+ <note>
+ <para>
+ In order to compile source code under Windows you will need to obtain
+ a 'make' utility. The <command>nmake</command> utility provided with
+ Microsoft Visual C++ may be used. As an alternative, there is a
+ utility called <command>dmake</command> available from CPAN which is
+ written entirely in Perl. The majority of the links given below, however,
+ are to pre-compiled versions of the modules, which can be installed
+ on Windows simply by issuing the following command once you have
+ downloaded the PPD file (which may be packaged within a ZIP file):
+ </para>
+ <para>
+ <screen>
+ <prompt>></prompt> ppm install <filename.ppd>
+ </screen>
+ </para>
+ </note>
</section>
<section id="modules-manual-download">
<title>Download Locations</title>
- <para>Note: some modules are in the core distribution of
- ActiveState Perl for Windows. Others are not available.
- No PPM links have been provided in either of these two cases.
+ <para>
+ <note>
+ Running Bugzilla on Windows requires the use of ActiveState
+ Perl 5.8.1 or higher. Some modules already exist in the core
+ distribution of ActiveState Perl so no PPM link is given.
+ (This is noted where it occurs.)
+ </note>
+ </para>
+
+ <para>
+ AppConfig:
+ <literallayout>
+ CPAN Download Page: <ulink url="http://search.cpan.org/src/ABW/AppConfig-1.56/lib/AppConfig.pm"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/AppConfig.ppd"/>
+ Documentation: <ulink url="http://search.cpan.org/~abw/AppConfig-1.56/lib/AppConfig.pm"/>
+ </literallayout>
</para>
- <para>CGI:
+ <para>
+ CGI:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/CGI.zip"/>
+ PPM Download Link: Part of core distribution.
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/CGI.html"/>
</literallayout>
</para>
- <para>TimeDate:
+ <para>
+ Data-Dumper:
+ <literallayout>
+ CPAN Download Page: <ulink url=http://search.cpan.org/src/ILYAM/Data-Dumper-2.121/Dumper.pm"/>
+ PPM Download Page: Part of core distribution.
+ Documentation: <ulink url="http://search.cpan.org/~ilyam/Data-Dumper-2.121/Dumper.pm"/>
+ </literallayout>
+ </para>
+
+ <para>
+ Date::Format (part of TimeDate):
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/TimeDate.zip"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/TimeDate.ppd"/>
Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/>
</literallayout>
</para>
- <para>DBI:
+ <para>
+ DBI:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBI.zip"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/DBI.ppd"/>
Documentation: <ulink url="http://dbi.perl.org/docs/"/>
</literallayout>
</para>
- <para>DBD::mysql:
+ <para>
+ DBD::mysql:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBD-Mysql.zip"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/DBD-mysql.ppd"/>
Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pm"/>
</literallayout>
</para>
- <para>File::Spec:
+ <para>
+ File::Spec:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
- PPM Download Page: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip"/>
+ PPM Download Page: Part of core distribution.
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Spec.html"/>
</literallayout>
</para>
- <para>File::Temp:
+ <para>
+ File::Temp:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Temp/"/>
+ PPM Download Page: Part of core distribution.
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Temp.html"/>
</literallayout>
</para>
- <para>Template Toolkit:
+ <para>
+ Template-Toolkit:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/>
- PPM Download Link: <ulink url="http://openinteract.sourceforge.net/ppmpackages/5.6/Template-Toolkit.tar.gz"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/Template-Toolkit.ppd"/>
Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/>
</literallayout>
</para>
- <para>Text::Wrap:
+ <para>
+ Text::Wrap:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Text-Tabs+Wrap/"/>
+ PPM Download Link: Part of core distribution.
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Text/Wrap.html"/>
</literallayout>
</para>
- <para>GD:
+ <para>
+ GD:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GD.zip"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/GD.ppd"/>
Documentation: <ulink url="http://stein.cshl.org/WWW/software/GD/"/>
</literallayout>
</para>
- <para>Chart::Base:
- <!-- TODO: Chart::Base doesn't seem to have any documentation -->
+ <title>Optional Modules</title>
+
+ <para>
+ Chart::Base:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/>
+ PPM Download Page: <ulink url="http://landfill.bugzilla.org/ppm/Chart.ppd"/>
+ Documentation: <ulink url="http://search.cpan.org/src/CHARTGRP/Chart-2.3/doc/Documentation.pdf"/>
</literallayout>
</para>
- <para>GD::Graph:
+ <para>
+ GD::Graph:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDGraph.zip"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/GDGraph.ppd"/>
Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/>
</literallayout>
</para>
- <para>GD::Text::Align:
+ <para>
+ GD::Text::Align (part of GD::Text::Util):
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/>
- PPM Download Page: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDTextUtil.zip"/>
+ PPM Download Page: <ulink url="http://landfill.bugzilla.org/ppm/GDTextUtil.ppd"/>
Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/>
</literallayout>
</para>
- <para>MIME::Parser:
+ <para>
+ MIME::Parser (part of MIME-tools):
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/>
- PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/MIME-tools.zip"/>
+ PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/8xx-builds-only/Windows/MIME-tools-5.411a.zip"/>
Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/>
</literallayout>
</para>
- <para>XML::Parser:
+ <para>
+ XML::Parser:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Parser/"/>
+ PPM Download Link: Part of core distribution.
Documentation: <ulink url="http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html"/>
</literallayout>
</para>
- <para>PatchReader:
+ <para>
+ PatchReader:
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/>
+ PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/PatchReader.ppd"/>
Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/>
</literallayout>
</para>
projects / thirdparty / bugzilla.git / commitdiff
