Skip to content

bugzilla
bugzilla
Commit dc4c71e7 authored by travis%sedsystems.ca's avatar travis%sedsystems.ca
Browse files
Options

Bug 239852 - Documentation changes for Windows support

Patch by bruce.armstrong@teamsybase.com, cleaned up by travis@sedsystems.ca r=bugzilla@glob.com.au
parent 0a99f521
Show whitespace changes
Inline Side-by-side
Showing with 266 additions and 101 deletions
docs/xml/installation.xml
View file @ dc4c71e7
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<!-- $Id: installation.xml,v 1.85 2004/12/18 11:52:20 jake%bugzilla.org Exp $ -->
<!-- $Id: installation.xml,v 1.86 2005/01/10 06:31:33 travis%sedsystems.ca Exp $ -->
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
......@@ -639,8 +639,8 @@
<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>
......@@ -795,20 +795,82 @@
<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://&lt;yourdomainname&gt;/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>
&lt;full path to perl.exe &gt;\perl.exe -x&lt;full path to Bugzilla&gt; -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>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>
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>
</section>
......@@ -946,8 +1008,19 @@
<programlisting>5 0 * * * cd &lt;your-bugzilla-directory&gt; ; ./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>
......@@ -1007,14 +1080,21 @@
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 &lt;your-bugzilla-directory&gt; ; ./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">
......@@ -1205,24 +1285,25 @@ AddType text/xml .rdf</screen>
<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>
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>
<para>If after hearing all that, you have enough pain tolerance to attempt
installing Bugzilla on Win32, here are some pointers.
<![%bz-devel;[
Because this is a development version of the guide, these instructions
are subject to change without notice. In fact, the Bugzilla Team hopes
to have Bugzilla reasonably close to "out of
the box" compatibility with Windows by the 2.18 release.
]]>
<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/" />.
The following instructions assume that you are using version
5.8.1 of ActiveState.
</para>
</section>
<section id="win32-perl">
<title>Win32 Perl</title>
......@@ -1237,47 +1318,60 @@ AddType text/xml .rdf</screen>
<section id="win32-perlmodules">
<title>Perl Modules on Win32</title>
<para>Bugzilla on Windows requires the same perl modules found in
<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.
windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead
of CPAN.
</para>
<programlisting>
C:\perl&gt; <command>ppm install &lt;module name&gt;</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>
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>
<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
<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>
change this line in the file Bugzilla/Bugmail.pm:
</para>
<programlisting>
open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") ||
......@@ -1286,7 +1380,11 @@ 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
......@@ -1304,27 +1402,32 @@ $smtp->dataend();
$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
<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
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>
......
docs/xml/modules.xml
View file @ dc4c71e7
......@@ -4,7 +4,8 @@
<section id="modules-manual-instructions">
<title>Instructions</title>
<para>If you need to install Perl modules manually, here's how it's done.
<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>
......@@ -17,127 +18,188 @@
<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>&gt;</prompt> ppm install &lt;filename.ppd&gt;
</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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment