Skip to content

bugzilla
bugzilla
Commit 938c535f authored by jake%bugzilla.org's avatar jake%bugzilla.org
Browse files
Options

Bug 191034 - Making the installation chapter a little more generic. Replaced a…

Bug 191034 - Making the installation chapter a little more generic. Replaced a lot of OS Specific hints with links to the OS Specific section.
parent 6d5d6dca
Show whitespace changes
Inline Side-by-side
Showing with 514 additions and 364 deletions
docs/en/xml/Bugzilla-Guide.xml
View file @ 938c535f
...@@ -34,7 +34,7 @@ ...@@ -34,7 +34,7 @@
<!ENTITY bz-ver "2.17.4"> <!ENTITY bz-ver "2.17.4">
<!ENTITY bz-nextver "2.18"> <!ENTITY bz-nextver "2.18">
<!ENTITY bz-date "2003-02-16"> <!ENTITY bz-date "2003-04-23">
<!ENTITY % bz-devel "INCLUDE"> <!ENTITY % bz-devel "INCLUDE">
<!ENTITY bz "http://www.bugzilla.org/"> <!ENTITY bz "http://www.bugzilla.org/">
...@@ -47,7 +47,7 @@ ...@@ -47,7 +47,7 @@
<!ENTITY min-mysql-ver "3.23.41"> <!ENTITY min-mysql-ver "3.23.41">
<!ENTITY min-perl-ver "5.6"> <!ENTITY min-perl-ver "5.6">
<!ENTITY min-template-ver "2.08"> <!ENTITY min-template-ver "2.08">
<!ENTITY min-file-temp-ver "1.804"> <!ENTITY min-file-temp-ver "any">
<!ENTITY min-appconfig-ver "1.52"> <!ENTITY min-appconfig-ver "1.52">
<!ENTITY min-text-wrap-ver "2001.0131"> <!ENTITY min-text-wrap-ver "2001.0131">
<!ENTITY min-file-spec-ver "0.82"> <!ENTITY min-file-spec-ver "0.82">
...@@ -121,7 +121,7 @@ try to avoid clutter and feel free to waste space in the code to make it more re ...@@ -121,7 +121,7 @@ try to avoid clutter and feel free to waste space in the code to make it more re
<para> <para>
This documentation is maintained in DocBook 4.1.2 XML format. This documentation is maintained in DocBook 4.1.2 XML format.
Changes are best submitted as plain text or XML diffs, attached Changes are best submitted as plain text or XML diffs, attached
to a bug filed in the &bzg-bugs; compontent. to a bug filed in the &bzg-bugs; component.
</para> </para>
<![%bz-devel;[ <![%bz-devel;[
<para>This is a development version of this guide. Information in it <para>This is a development version of this guide. Information in it
......
docs/en/xml/glossary.xml
View file @ 938c535f
...@@ -154,10 +154,10 @@ ...@@ -154,10 +154,10 @@
</glossentry> </glossentry>
<glossentry id="gloss-cpan"> <glossentry id="gloss-cpan">
<glossterm> <glossterm>Comprehensive Perl Archive Network</glossterm>
<acronym>CPAN</acronym> <acronym>CPAN</acronym>
</glossterm>
<!-- TODO: Rewrite def for CPAN -->
<glossdef> <glossdef>
<para> <para>
<acronym>CPAN</acronym> <acronym>CPAN</acronym>
...@@ -283,6 +283,16 @@ ...@@ -283,6 +283,16 @@
<glossdiv id="gloss-p"> <glossdiv id="gloss-p">
<title>P</title> <title>P</title>
<glossentry id="gloss-ppm">
<glossterm>Perl Package Manager</glossterm>
<acronym>PPM</acronym>
<glossdef>
<para><ulink url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/"/>
</para>
</glossdef>
</glossentry>
<glossentry> <glossentry>
<glossterm id="gloss-product">Product</glossterm> <glossterm id="gloss-product">Product</glossterm>
...@@ -347,6 +357,17 @@ ...@@ -347,6 +357,17 @@
</para> </para>
</glossdef> </glossdef>
</glossentry> </glossentry>
<glossentry id="gloss-regexp">
<glossterm>Regular Expression</glossterm>
<acronym>regexp</acronym>
<glossdef>
<para>A regular expression is an expression used for pattern matching.
<ulink url="http://perldoc.com/perl5.6/pod/perlre.html#Regular-Expressions">Documentation</ulink>
</para>
</glossdef>
</glossentry>
</glossdiv> </glossdiv>
<glossdiv id="gloss-s"> <glossdiv id="gloss-s">
......
docs/en/xml/installation.xml
View file @ 938c535f
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<chapter id="installation" xreflabel="Bugzilla Installation"> <!-- $Id: installation.xml,v 1.45 2008/04/04 06:46:35 jake%bugzilla.org Exp $ -->
<chapter id="installation">
<title>Installation</title> <title>Installation</title>
<section id="stepbystep" xreflabel="Bugzilla Installation Step-by-step"> <section id="stepbystep">
<title>Step-by-step Install</title> <title>Step-by-step Install</title>
<section id="intstall-into"> <para>Bugzilla has been successfully installed under many different
<title>Introduction</title> operating systems including almost all Unix clones and
<productname class="registered">Microsoft Windows</productname>. Many
operating systems have utilities that make installation easier or quirks
that make it harder. We have tried to collect that information in
<xref linkend="os-specific"/>, so be sure to check out that section before
you start your installation.
</para>
<para>Bugzilla has been successfully installed under Solaris, Linux, <note>
and Win32. Win32 is not yet officially supported, but many people <para>Windows is one of those operating systems that has many quirks
have got it working fine. and is not yet officially supported by the Bugzilla team. If you wish
Please see to install Bugzilla on Windows, be sure to see
<xref linkend="os-win32" /> <xref linkend="os-win32"/>.
for further advice on getting Bugzilla to work on Microsoft </para>
Windows.</para> </note>
</section> <warning>
<para>While installing Bugzilla, it is a good idea to ensure that there
is some kind of firewall between you and the rest of the Internet
as your machine may be insecure for periods during the install. Many
installation steps require an active Internet connection to complete,
but you must take care to ensure that at no point is your machine
vulnerable to an attack.</para>
</warning>
<section id="install-package-list"> <para>This guide assumes that you already have your operating system
<title>Package List</title> installed, network configured, and have administrative access to the
shell on the machine you are installing Bugzilla onto. It is possible to
install and run Bugzilla without administrative access, but you have to
either make sure all the required software is installed or get somebody
with administrative access to install it for you.
</para>
<note> <para>The listing below is a basic step-by-step list. More information
<para> If you are running the very most recent can be found in the sections below. Minimum versions will be
version of Perl and MySQL (both the executables and development included in parenthesis where appropriate.
libraries) on your system, you can skip these manual installation </para>
steps for the Perl modules by using Bundle::Bugzilla; see
<xref linkend="bundlebugzilla" />. <procedure>
<step>
<para><link linkend="install-mysql">Install MySQL</link>
(&min-mysql-ver;)
</para>
</step>
<step>
<para><link linkend="install-perl">Install Perl</link>
(&min-perl-ver;)
</para>
</step>
<step>
<para><link linkend="install-perlmodules">Install Perl Modules</link>
</para>
</step>
<step>
<para><link linkend="install-webserver">Install a Webserver</link>
</para>
</step>
<step>
<para><link linkend="install-bzfiles">Put Bugzilla in the Webspace</link>
</para>
</step>
<step>
<para><link linkend="install-setupdatabase">Setup the MySQL Database</link>
</para>
</step>
</procedure>
<section id="install-mysql">
<title>MySQL</title>
<para>Visit the MySQL homepage at
<ulink url="http://www.mysql.com"/>
to grab and install the latest stable release of the server.
</para> </para>
<note>
<para> Many of the binary
versions of MySQL store their data files in
<filename class="directory">/var</filename>.
On some Unix systems, this is part of a smaller root partition,
and may not have room for your bug database. You can set the data
directory as an option to <filename>configure</filename>
if you build MySQL from source yourself.</para>
</note> </note>
<para>The software packages necessary for the proper running of <para>If you install from something other than a packaging/installation
Bugzilla (with download links) are: system (such as .rpm, .dep, .exe, or .msi) you will need to configure
<orderedlist> your system so the MySQL server daemon will come back up whenever
your machine reboots.
</para>
<para>If you wish to have attachments larger than 64K, you will have to
configure MySQL to accept large packets. This is done by adding the text
in <xref linkend="install-mysql-packets"/> to your
<filename>my.conf</filename> file. There is also a parameter in Bugzilla
for setting the maximum allowable attachment size.
<!-- TODO: xref to a param() page for max attachment size -->
You should set this value to be slightly larger than that parameter.
</para>
<figure id="install-mysql-packets">
<title>Set Max Packet Size in MySQL</title>
<listitem> <programlisting>
<para> [mysqld]
<ulink url="http://www.mysql.com/">MySQL database server</ulink> # Allow packets up to 1M
(&min-mysql-ver; or greater) set-variable = max_allowed_packet=1M
</programlisting>
</figure>
<para>If you are running Bugzilla and MySQL on the same machine, you may
also wish to utilize the <option>skip-networking</option> option as
mentioned in <xref linkend="security-mysql"/> for the added security.
</para> </para>
</listitem> </section>
<listitem> <section id="install-perl">
<para> <title>Perl</title>
<ulink url="http://www.perl.org/">Perl</ulink>
(&min-perl-ver;, 5.6.1 is recommended if you wish to <para>Any machine that doesn't have Perl on it is a sad machine indeed.
use Bundle::Bugzilla) Perl can be got in source form from <ulink url="http://www.perl.com"/>.
There are also binary versions available for many platforms, most of which
are linked to from perl.com.
Although Bugzilla runs with perl &min-perl-ver;,
it's a good idea to be up to the very latest version
if you can when running Bugzilla. As of this writing, that is Perl
version &newest-perl-ver;.</para>
</section>
<section id="install-perlmodules">
<title>Perl Modules</title>
<para>Perl modules can be found using
<glossterm linkend="gloss-cpan">CPAN</glossterm> on Unix based systems or
<glossterm linkend="gloss-ppm">PPM</glossterm> on Win32. The root servers
have a real tendency to bog down, so please use mirrors.
</para> </para>
</listitem>
<listitem> <para>Good instuctions can be found for using each of these services on
their respective websites. The basics can be found in
<xref linkend="install-perlmodules-cpan"/> for CPAN and
<xref linkend="win32-perlmodules"/> for PPM.
</para>
<example id="install-perlmodules-cpan">
<title>Installing perl modules with CPAN</title>
<para>The easy way:
<screen>
<prompt>bash#</prompt> perl -MCPAN -e 'install "&lt;modulename&gt;"'
</screen>
</para>
<para>Or the hard way:
<screen>
<prompt>bash#</prompt> tar xzvf &lt;module&gt;.tar.gz <co id="cpan-moduletar"/>
<prompt>bash#</prompt> cd &lt;module&gt; <co id="cpan-moduledir"/>
<prompt>bash#</prompt> perl Makefile.PL
<prompt>bash#</prompt> make
<prompt>bash#</prompt> make test
<prompt>bash#</prompt> make install
</screen>
<calloutlist>
<callout arearefs="cpan-moduletar">
<para>This assumes that you've already downloaded the
<filename>&lt;module&gt;.tar.gz</filename> to the current working
directory.
</para>
</callout>
<callout arearefs="cpan-moduledir">
<para>The process of untaring the module as defined in
<xref linkend="cpan-moduletar"/> will create the
<filename class="directory">&lt;module&gt;</filename> directory.
</para>
</callout>
</calloutlist>
</para>
</example>
<tip>
<para>Many people complain that Perl modules will not install for
them. Most times, the error messages complain that they are missing a
file in
<quote>@INC</quote>.
Virtually every time, this error is due to permissions being set too
restrictively for you to compile Perl modules or not having the
necessary Perl development libraries installed on your system.
Consult your local UNIX systems administrator for help solving these
permissions issues; if you
<emphasis>are</emphasis>
the local UNIX sysadmin, please consult the newsgroup/mailing list
for further assistance or hire someone to help you out.</para>
</tip>
<!-- TODO: Fix indentation before checkin -->
<para>Perl Modules (minimum version): <para>Perl Modules (minimum version):
<orderedlist> <orderedlist>
<!-- TODO: Don't think we actually care about AppConfig anymore -->
<listitem> <listitem>
<para> <para>
<ulink url="http://www.template-toolkit.org">Template</ulink> <link linkend="install-modules-bundle-bugzilla">Bundle::Bugzilla</link>
(v&min-template-ver;) (Will allow you to skip the rest)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.perldoc.com/perl5.6/lib/File/Temp.html"> <link linkend="install-modules-appconfig">AppConfig</link>
File::Temp</ulink> (&min-appconfig-ver;)
(&min-file-temp-ver;) (Prerequisite for Template)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/AppConfig/">AppConfig <link linkend="install-modules-cgi">CGI</link>
</ulink> (&min-cgi-ver;)
(&min-appconfig-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz">Text::Wrap</ulink> <link linkend="install-modules-data-dumper">Data::Dumper</link>
(&min-text-wrap-ver;) (&min-data-dumper-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://search.cpan.org/search?dist=File-Spec">File::Spec <link linkend="install-modules-date-format">Date::Format</link>
</ulink> (&min-date-format-ver;)
(&min-file-spec-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/Data/">Data::Dumper <link linkend="install-modules-dbi">DBI</link>
</ulink> (&min-dbi-ver;)
(&min-data-dumper-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/Mysql/">DBD::mysql <link linkend="install-modules-dbd-mysql">DBD::mysql</link>
</ulink>
(&min-dbd-mysql-ver;) (&min-dbd-mysql-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/DBI/">DBI</ulink> <link linkend="install-file-spec">File::Spec</link>
(&min-dbi-ver;) (&min-file-spec-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/Date/">Date::Parse <link linkend="install-modules-file-temp">File::Temp</link>
</ulink> (&min-file-temp-ver;)
(&min-date-format-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/CGI/">CGI <link linkend="install-modules-template">Template Toolkit</link>
</ulink> (&min-template-ver;)
(&min-cgi-ver;)
</para> </para>
</listitem> </listitem>
<listitem>
<para>
<link linkend="install-modules-text-wrap">Text::Wrap</link>
(&min-text-wrap-ver;)
</para>
</listitem>
</orderedlist> </orderedlist>
and, optionally: and, optionally:
<orderedlist> <orderedlist>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/GD/">GD</ulink> <link linkend="install-modules-gd">GD</link>
(&min-gd-ver;) for bug charting (&min-gd-ver;) for bug charting
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
GD::Graph <link linkend="install-modules-chart-base">Chart::Base</link>
(&min-gd-graph-ver;) for bug charting (&min-chart-base-ver;) for bug charting
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
GD::Text::Align <link linkend="install-modules-xml-parser">XML::Parser</link>
(&min-gd-text-align-ver;) for bug charting (&min-xml-parser-ver;) for the XML interface
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<ulink url="http://www.cpan.org/modules/by-module/Chart/">Chart::Base <link linkend="install-modules-gd-graph">GD::Graph</link>
</ulink> (&min-gd-graph-ver;) for bug charting
(&min-chart-base-ver;) for bug charting
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
XML::Parser <link linkend="install-modules-gd-text-align">GD::Text::Align</link>
(&min-xml-parser-ver;) for the XML interface (&min-gd-text-align-ver;) for bug charting
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
MIME::Parser <link linkend="install-modules-mime-parser">MIME::Parser</link>
(&min-mime-parser-ver;) for the email interface (&min-mime-parser-ver;) for the email interface
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> </para>
</listitem>
<listitem>
<para>
The web server of your choice.
<ulink url="http://www.apache.org/">Apache</ulink>
is highly recommended.
</para>
</listitem>
</orderedlist>
<warning> <section id="install-modules-bundle-bugzilla">
<para>It is a good idea, while installing Bugzilla, to ensure that there <title>Bundle::Bugzilla</title>
is some kind of firewall between you and the rest of the Internet,
because your machine may be insecure for periods during the install.
Many
installation steps require an active Internet connection to complete,
but you must take care to ensure that at no point is your machine
vulnerable to an attack.</para>
</warning>
<para>If you are running at least perl 5.6.1, you can save yourself a lot
of time by using Bundle::Bugzilla. This bundle contains every module
required to get Bugzilla running. It does not include GD and friends, but
these are not required for a base install and can always be added later
if the need arises.
</para> </para>
</section>
<section id="install-mysql"> <para>Assuming your perl was installed with CPAN (most unix installations
<title>MySQL</title> are), using Bundle::Bugzilla is really easy. Simply follow along with the
commands below.
<para>Visit the MySQL homepage at
<ulink url="http://www.mysql.com"/>
to grab and install the latest stable release of the server.
</para> </para>
<note>
<para> Many of the binary
versions of MySQL store their data files in
<filename>/var</filename>.
On some Unix systems, this is part of a smaller root partition,
and may not have room for your bug database. You can set the data
directory as an option to <filename>configure</filename>
if you build MySQL from source yourself.</para>
</note>
<para>If you install from something other than an RPM or Debian
package, you will need to add <filename>mysqld</filename>
to your init scripts so the server daemon will come back up whenever
your machine reboots. Further discussion of UNIX init sequences are
beyond the scope of this guide.
</para>
<para>Change your init script to start
<filename>mysqld</filename>
with the ability to accept large packets. By default,
<filename>mysqld</filename>
only accepts packets up to 64K long. This limits the size of
attachments you may put on bugs. If you add
<option>-O max_allowed_packet=1M</option>
to the command that starts
<filename>mysqld</filename>
(or <filename>safe_mysqld</filename>),
then you will be able to have attachments up to about 1 megabyte.
There is a Bugzilla parameter for maximum attachment size;
you should configure it to match the value you choose here.</para>
<para>If you plan on running Bugzilla and MySQL on the same machine,
consider using the
<option>--skip-networking</option>
option in the init script. This enhances security by preventing
network access to MySQL.</para>
</section>
<section id="install-perl"> <screen>
<title>Perl</title> <prompt>bash#</prompt> <command>perl -MCPAN -eshell</command> <co id="bundle-cpanconfig"/>
cpan shell -- CPAN exploration and modules installation (v1.63)
<para>Any machine that doesn't have Perl on it is a sad machine indeed. ReadLine support enabled
Perl can be got in source form from
<ulink url="http://www.perl.org"/> for the rare
*nix systems which don't have it.
Although Bugzilla runs with perl &min-perl-ver;,
it's a good idea to be up to the very latest version
if you can when running Bugzilla. As of this writing, that is Perl
version &newest-perl-ver;.</para>
<tip id="bundlebugzilla"
xreflabel="Using Bundle::Bugzilla instead of manually installing Perl modules">
<para>You can skip the following Perl module installation steps by
installing
<productname>Bundle::Bugzilla</productname>
from <prompt>cpan&gt;</prompt>
<glossterm linkend="gloss-cpan">CPAN</glossterm>,
which installs all required modules for you.</para>
<para> </screen>
<computeroutput>
<prompt>bash#</prompt>
<command>perl -MCPAN -e 'install "Bundle::Bugzilla"'</command> <calloutlist>
</computeroutput> <callout arearefs="bundle-cpanconfig">
<para>At this point, unless you've used CPAN on this machine before,
you'll have to go through a series of configuration steps.
</para> </para>
</callout>
<para>Bundle::Bugzilla doesn't include GD, Chart::Base, or </calloutlist>
MIME::Parser, which are not essential to a basic Bugzilla install. If
installing this bundle fails, you should install each module
individually to isolate the problem.</para>
</tip>
</section> </section>
<section id="perl-modules"> <section id="install-modules-appconfig">
<title>Perl Modules</title> <title>AppConfig (&min-appconfig-ver;)</title>
<para>
All Perl modules can be found on the
<ulink url="http://www.cpan.org">Comprehensive Perl
Archive Network</ulink> (CPAN). The
CPAN servers have a real tendency to bog down, so please use mirrors.
</para>
<para>Quality, general Perl module installation instructions can be <para>Dependency for Template Toolkit. We probably don't need to
found on the CPAN website, but the easy thing to do is to just use the specifically check for it anymore.
CPAN shell which does all the hard work for you.
To use the CPAN shell to install a module:
</para> </para>
</section>
<para> <section id="install-modules-cgi">
<computeroutput> <title>CGI (&min-cgi-ver;)</title>
<prompt>bash#</prompt>
<command>perl -MCPAN -e 'install "&lt;modulename&gt;"'</command>
</computeroutput>
</para>
<para> <para>The CGI module parses form elements and cookies and does many
To do it the hard way: other usefule things. It come as a part of recent perl distributions, but
Bugzilla needs a fairly new version.
</para> </para>
<para>Untar the module tarball -- it should create its own <literallayout>
directory</para> 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"/>
<para>CD to the directory just created, and enter the following Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/CGI.html"/>
commands: </literallayout>
<orderedlist> </section>
<listitem>
<para>
<computeroutput>
<prompt>bash#</prompt>
<command>perl Makefile.PL</command> <section id="install-modules-data-dumper">
</computeroutput> <title>Data::Dumper (&min-data-dumper-ver;)</title>
</para>
</listitem>
<listitem> <para>The Data::Dumper module provides data structure persistence for
<para> Perl (similar to Java's serialization). It comes with later
<computeroutput> sub-releases of Perl 5.004, but a re-installation just to be sure it's
<prompt>bash#</prompt> available won't hurt anything.
<command>make</command>
</computeroutput>
</para> </para>
</listitem>
<listitem> <literallayout>
<para> CPAN Download Page: <ulink url="http://search.cpan.org/dist/Data-Dumper/"/>
<computeroutput> PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Data-Dumper.zip"/>
<prompt>bash#</prompt> Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Data/Dumper.html"/>
</literallayout>
</section>
<command>make test</command> <section id="install-modules-date-format">
</computeroutput> <title>TimeDate modules (&min-date-format-ver;)</title>
</para>
</listitem>
<listitem> <para>Many of the more common date/time/calendar related Perl modules
<para> have been grouped into a bundle similar to the MySQL modules bundle.
<computeroutput> This bundle is stored on the CPAN under the name TimeDate.
<prompt>bash#</prompt> The component module we're most interested in is the Date::Format
module, but installing all of them is probably a good idea anyway.
<command>make install</command>
</computeroutput>
</para>
</listitem>
</orderedlist>
</para> </para>
<warning> <literallayout>
<para>Many people complain that Perl modules will not install for CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/>
them. Most times, the error messages complain that they are missing a PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/TimeDate.zip"/>
file in Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/>
<quote>@INC</quote>. </literallayout>
Virtually every time, this error is due to permissions being set too </section>
restrictively for you to compile Perl modules or not having the
necessary Perl development libraries installed on your system.
Consult your local UNIX systems administrator for help solving these
permissions issues; if you
<emphasis>are</emphasis>
the local UNIX sysadmin, please consult the newsgroup/mailing list
for further assistance or hire someone to help you out.</para>
</warning>
<section> <section id="install-modules-dbi">
<title>DBI</title> <title>DBI (&min-dbi-ver;)</title>
<para>The DBI module is a generic Perl module used the <para>The DBI module is a generic Perl module used the
MySQL-related modules. As long as your Perl installation was done MySQL-related modules. As long as your Perl installation was done
correctly the DBI module should be a breeze. It's a mixed Perl/C correctly the DBI module should be a breeze. It's a mixed Perl/C
module, but Perl's MakeMaker system simplifies the C compilation module, but Perl's MakeMaker system simplifies the C compilation
greatly.</para> greatly.</para>
</section>
<section>
<title>Data::Dumper</title>
<para>The Data::Dumper module provides data structure persistence for <literallayout>
Perl (similar to Java's serialization). It comes with later CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/>
sub-releases of Perl 5.004, but a re-installation just to be sure it's PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBI.zip"/>
available won't hurt anything.</para> Documentation: <ulink url="http://dbi.perl.org/doc/"/>
</literallayout>
</section> </section>
<section> <section id="install-modules-dbd-mysql">
<title>MySQL-related modules</title> <title>MySQL-related modules</title>
<para>The Perl/MySQL interface requires a few mutually-dependent Perl <para>The Perl/MySQL interface requires a few mutually-dependent Perl
...@@ -419,24 +459,77 @@ ...@@ -419,24 +459,77 @@
with a null password should find itself with sufficient access to run with a null password should find itself with sufficient access to run
tests on the 'test' database which MySQL created upon installation. tests on the 'test' database which MySQL created upon installation.
</para> </para>
<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"/>
Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pod"/>
</literallayout>
</section> </section>
<section> <section id="install-file-spec">
<title>TimeDate modules</title> <title>File::Spec (&min-file-spec-ver;)</title>
<para>Many of the more common date/time/calendar related Perl modules <para>File::Spec is a perl module that allows file operations, such as
have been grouped into a bundle similar to the MySQL modules bundle. generating full path names, to work cross platform.
This bundle is stored on the CPAN under the name TimeDate.
The component module we're most interested in is the Date::Format
module, but installing all of them is probably a good idea anyway.
</para> </para>
<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"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Spec.html"/>
</literallayout>
</section> </section>
<section> <section id="install-modules-file-temp">
<title>GD (optional)</title> <title>File::Temp (&min-file-temp-ver;)</title>
<para>File::Temp is used to generate a temporary filename that is
guaranteed to be unique. It comes as a standard part of perl
</para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Temp.html"/>
</literallayout>
</section>
<section id="install-modules-template">
<title>Template Toolkit (&min-template-ver;)</title>
<para>When you install Template Toolkit, you'll get asked various
questions about features to enable. The defaults are fine, except
that it is recommended you use the high speed XS Stash of the Template
Toolkit, in order to achieve best performance.
</para>
<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"/>
Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/>
</literallayout>
</section>
<section id="install-modules-text-wrap">
<title>Text::Wrap (&min-text-wrap-ver;)</title>
<para>Text::Wrap is designed to proved intelligent text wrapping.
</para>
<!-- TODO: Text::Wrap doesn't seem to be available from ActiveState -->
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Text-Tabs+Wrap/"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Text/Wrap.html"/>
</literallayout>
</section>
<section id="install-modules-gd">
<title>GD (&min-gd-ver;) [optional]</title>
<para>The GD library was written by Thomas Boutell a long while ago to <para>The GD library was written by Thomas Boutell a long while ago to
programatically generate images in C. Since then it's become the programmatically generate images in C. Since then it's become the
defacto standard for programmatic image construction. The Perl bindings defacto standard for programmatic image construction. The Perl bindings
to it found in the GD library are used on millions of web pages to to it found in the GD library are used on millions of web pages to
generate graphs on the fly. That's what Bugzilla will be using it for generate graphs on the fly. That's what Bugzilla will be using it for
...@@ -452,32 +545,99 @@ ...@@ -452,32 +545,99 @@
If compiling GD fails, it's probably because you're If compiling GD fails, it's probably because you're
missing a required library.</para> missing a required library.</para>
</note> </note>
<tip>
<para>The version of the GD perl module you need is very closely tied
to the <classname>libgd</classname> version installed on your system.
If you have a version 1.x of <classname>libgd</classname> the 2.x
versions of the GD perl module won't work for you.
</para>
</tip>
<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"/>
Documentation: <ulink url="http://stein.cshl.org/WWW/software/GD/"/>
</literallayout>
</section> </section>
<section> <section id="install-modules-chart-base">
<title>Chart::Base (optional)</title> <title>Chart::Base (&min-chart-base-ver;) [optional]</title>
<para>The Chart module provides Bugzilla with on-the-fly charting <para>The Chart module provides Bugzilla with on-the-fly charting
abilities. It can be installed in the usual fashion after it has been abilities. It can be installed in the usual fashion after it has been
fetched from CPAN. fetched from CPAN.
Note that earlier versions that 0.99c used GIFs, which are no longer Note that earlier versions that 0.99c used GIFs, which are no longer
supported by the latest versions of GD.</para> supported by the latest versions of GD.</para>
<!-- TODO: Chart::Base doesn't seem to have any documentation -->
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Chart.zip"/>
</literallayout>
</section> </section>
<section> <section id="install-modules-xml-parser">
<title>Template Toolkit</title> <title>XML::Parser (&min-xml-parser-ver;) [Optional]</title>
<para>When you install Template Toolkit, you'll get asked various <para>XML::Parser is used by the <filename>importxml.pl</filename>
questions about features to enable. The defaults are fine, except script. You only need it if you are going to be importing bugs (such as
that it is recommended you use the high speed XS Stash of the Template for bug moving). XML::Parser requires that the
Toolkit, in order to achieve best performance. <classname>expat</classname> library is already installed on your machine.
</para> </para>
<!-- TODO: XML::Parser - the only PPM I see is XML-Parser-EasyTree.zip;
I'm not sure if it's the same thing or not. -->
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Parser/"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html"/>
</literallayout>
</section> </section>
<section id="install-modules-gd-graph">
<title>GD::Graph (&min-gd-graph-ver;) [Optional]</title>
<para>In addition to GD listed above, the reporting interface of Bugzilla
needs to have the GD::Graph module installed.
</para>
<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"/>
Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/>
</literallayout>
</section> </section>
<section id="sbs-http"> <section id="install-modules-gd-text-align">
<title>GD::Text::Align (&min-gd-text-align-ver;) [Optional]</title>
<para>GD::Text::Align, as the name implies, is used to draw aligned
strings of text. It is needed by the reporting interface.
</para>
<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"/>
Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/>
</literallayout>
</section>
<section id="install-modules-mime-parser">
<title>MIME::Parser (&min-mime-parser-ver;) [Optional]</title>
<para>MIME::Parser is only needed if you want to use the e-mail interface
located in the <filename class="directory">contrib</filename> directory.
</para>
<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"/>
Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/>
</literallayout>
</section>
</section>
<section id="install-webserver">
<title>HTTP Server</title> <title>HTTP Server</title>
<para>You have freedom of choice here, pretty much any web server that <para>You have freedom of choice here, pretty much any web server that
...@@ -490,12 +650,13 @@ ...@@ -490,12 +650,13 @@
<para>We strongly recommend Apache as the web server to use. The <para>We strongly recommend Apache as the web server to use. The
Bugzilla Guide installation instructions, in general, assume you are Bugzilla Guide installation instructions, in general, assume you are
using Apache. If you have got Bugzilla working using another webserver, using Apache. If you have got Bugzilla working using another webserver,
please share your experiences with us.</para> please share your experiences with us by filing a bug in &bzg-bugs;.
</para>
</note> </note>
</section> </section>
<section> <section id="install-bzfiles">
<title>Bugzilla</title> <title>Bugzilla</title>
<para>You should untar the Bugzilla files into a directory that you're <para>You should untar the Bugzilla files into a directory that you're
...@@ -522,94 +683,63 @@ ...@@ -522,94 +683,63 @@
until you run the post-install until you run the post-install
<filename>checksetup.pl</filename> <filename>checksetup.pl</filename>
script, which locks down your installation.</para> script, which locks down your installation.</para>
<caution>
<para>The default Bugzilla distribution is not designed to be placed
in a <filename class="directory">cgi-bin</filename> directory (this
includes any directory which is configured using the
<option>ScriptAlias</option> directive of Apache). This will probably
change as part of
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug
44659</ulink>.
</para>
</caution>
</section> </section>
<section> <section id="install-setupdatabase">
<title>Setting Up the MySQL Database</title> <title>Setting Up the MySQL Database</title>
<para>After you've gotten all the software installed and working you're <para>After you've gotten all the software installed and working you're
ready to start preparing the database for its life as the back end to ready to start preparing the database for its life as the back end to
a high quality bug tracker.</para> a high quality bug tracker.</para>
<para>First, you'll want to fix MySQL permissions to allow access from <para>This first thing you'll want to do is make sure you've given the
Bugzilla. For the purpose of this Installation section, the Bugzilla <quote>root</quote> user a password as suggested in
username will be <xref linkend="security-mysql"/>. For clarity, these instructions will
<quote>bugs</quote>, and will have minimal permissions. assume that your MySQL user for Bugzilla will be <quote>bugs_user</quote>,
the database will be called <quote>bugs_db</quote> and the password for
the <quote>bugs_user</quote> user is <quote>bugs_password</quote>. You
should, of course, substitute the values you intend to use for your site.
</para> </para>
<para>Begin by giving the MySQL root user a password. MySQL passwords are limited <note>
to 16 characters. <para>Most people use <quote>bugs</quote> for both the user and
<simplelist> database name.
<member> </para>
<computeroutput> </note>
<prompt>bash#</prompt>
<command>mysql -u root mysql</command>
</computeroutput>
</member>
<member>
<computeroutput>
<prompt>mysql&gt;</prompt>
<command>UPDATE user SET Password=PASSWORD('&lt;new_password&gt;')
WHERE user='root';</command>
</computeroutput>
</member>
<member>
<computeroutput>
<prompt>mysql&gt;</prompt>
<command>FLUSH PRIVILEGES;</command>
</computeroutput>
</member>
</simplelist>
From this point on, if you need to access MySQL as the MySQL root user,
you will need to use
<command>mysql -u root -p</command>
and enter &lt;new_password&gt;. Remember that MySQL user names have
nothing to do with Unix user names (login names).</para>
<para>Next, we use an SQL <command>GRANT</command> command to create a <para>Next, we use an SQL <command>GRANT</command> command to create a
<quote>bugs</quote> <quote>bugs_user</quote>
user, and grant sufficient permissions for checksetup.pl, which we'll user, and grant sufficient permissions for checksetup.pl, which we'll
use later, to work its magic. This also restricts the use later, to work its magic. This also restricts the
<quote>bugs</quote> <quote>bugs_user</quote>
user to operations within a database called user to operations within a database called
<quote>bugs</quote>, and only allows the account to connect from <quote>bugs_db</quote>, and only allows the account to connect from
<quote>localhost</quote>. <quote>localhost</quote>.
Modify it to reflect your setup if you will be connecting from Modify it to reflect your setup if you will be connecting from
another machine or as a different user.</para> another machine or as a different user.</para>
<para>Remember to set &lt;bugs_password&gt; to some unique password. <screen>
<simplelist> <prompt>mysql&gt;</prompt> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,
<member> DROP,REFERENCES ON bugs_db.* TO bugs_user@localhost
<computeroutput> IDENTIFIED BY 'bugs_password';
<prompt>mysql&gt;</prompt> <prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
</screen>
<command>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost
IDENTIFIED BY '&lt;bugs_password&gt;';</command>
</computeroutput>
</member>
<member>
<computeroutput>
<prompt>mysql&gt;</prompt>
<command>FLUSH PRIVILEGES;</command>
</computeroutput>
</member>
</simplelist>
</para>
<note> <note>
<para>If you are using MySQL 4, the bugs user also needs to be granted <para>If you are using MySQL 4, the bugs user also needs to be granted
the LOCK TABLES and CREATE TEMPORARY TABLES permissions. the <computeroutput>LOCK TABLES</computeroutput> and
<computeroutput>CREATE TEMPORARY TABLES</computeroutput> permissions.
</para> </para>
</note> </note>
</section> </section>
...@@ -622,22 +752,20 @@ ...@@ -622,22 +752,20 @@
<para>Next, run the magic checksetup.pl script. (Many thanks to <para>Next, run the magic checksetup.pl script. (Many thanks to
<ulink url="mailto:holgerschurig@nikocity.de">Holger Schurig</ulink> <ulink url="mailto:holgerschurig@nikocity.de">Holger Schurig</ulink>
for writing this script!) for writing this script!)
This script is designed to make sure your MySQL database and other This script is designed to make sure your perl modules are the correct
version and your MySQL database and other
configuration options are consistent with the Bugzilla CGI files. configuration options are consistent with the Bugzilla CGI files.
It will make sure Bugzilla files and directories have reasonable It will make sure Bugzilla files and directories have reasonable
permissions, set up the permissions, set up the
<filename>data</filename> <filename>data</filename>
directory, and create all the MySQL tables. directory, and create all the MySQL tables.
<simplelist> </para>
<member>
<computeroutput>
<prompt>bash#</prompt>
<command>./checksetup.pl</command> <screen>
</computeroutput> <prompt>bash#</prompt> ./checksetup.pl
</member> </screen>
</simplelist>
<para>
The first time you run it, it will create a file called The first time you run it, it will create a file called
<filename>localconfig</filename>.</para> <filename>localconfig</filename>.</para>
...@@ -654,20 +782,20 @@ ...@@ -654,20 +782,20 @@
<listitem> <listitem>
<para>database name: <para>database name:
<quote>bugs</quote> <quote>bugs_db</quote>
if you're following these directions</para> if you're following these directions</para>
</listitem> </listitem>
<listitem> <listitem>
<para>MySQL username: <para>MySQL username:
<quote>bugs</quote> <quote>bugs_user</quote>
if you're following these directions</para> if you're following these directions</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Password for the <para>Password for the
<quote>bugs</quote> <quote>bugs_user</quote>
MySQL account; (&lt;bugs_password&gt;) above</para> MySQL account; (<quote>bugs_password</quote> above)</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</para> </para>
...@@ -975,7 +1103,7 @@ bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; chars ...@@ -975,7 +1103,7 @@ bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; chars
which can limit connections by ip-address. You may download this module which can limit connections by ip-address. You may download this module
at at
<ulink url="http://www.snert.com/Software/mod_throttle/"/> <ulink url="http://www.snert.com/Software/mod_throttle/"/>.
Follow the instructions to install into your Apache install. Follow the instructions to install into your Apache install.
<emphasis>This module only functions with the Apache web <emphasis>This module only functions with the Apache web
server!</emphasis> server!</emphasis>
...@@ -1034,12 +1162,13 @@ bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; chars ...@@ -1034,12 +1162,13 @@ bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; chars
</para> </para>
</section> </section>
<section id="win32-perl-modules"> <section id="win32-perlmodules">
<title>Perl Modules on Win32</title> <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-package-list"/>. The main difference is that <xref linkend="install-perlmodules"/>. The main difference is that
windows uses <command>ppm</command> instead of CPAN. windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead of
CPAN.
</para> </para>
<programlisting> <programlisting>
......
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