File: stepbystep.html

package info (click to toggle)
bugzilla 2.16.7-7sarge2
links: PTS
area: main
in suites: sarge
size: 4,696 kB
ctags: 492
sloc: perl: 20,289; xml: 6,856; sh: 338; makefile: 211; python: 172
file content (1773 lines) | stat: -rw-r--r-- 32,410 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Step-by-step Install</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="The Bugzilla Guide - 2.16.7 Release"
HREF="index.html"><LINK
REL="UP"
TITLE="Installation"
HREF="installation.html"><LINK
REL="PREVIOUS"
TITLE="Installation"
HREF="installation.html"><LINK
REL="NEXT"
TITLE="Optional Additional Configuration"
HREF="extraconfig.html"></HEAD
><BODY
CLASS="section"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Bugzilla Guide - 2.16.7 Release</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="installation.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 4. Installation</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="extraconfig.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="stepbystep"
>4.1. Step-by-step Install</A
></H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN430"
>4.1.1. Introduction</A
></H2
><P
>Bugzilla has been successfully installed under Solaris, Linux,
      and Win32. Win32 is not yet officially supported, but many people
      have got it working fine.
      Please see the 
      <A
HREF="win32.html"
>Win32 Installation Notes</A
>
      for further advice on getting Bugzilla to work on Microsoft
      Windows.</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN434"
>4.1.2. Package List</A
></H2
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> If you are running the very most recent
        version of Perl and MySQL (both the executables and development
        libraries) on your system, you can skip these manual installation 
        steps for the Perl modules by using Bundle::Bugzilla; see
        <A
HREF="stepbystep.html#bundlebugzilla"
>Using Bundle::Bugzilla instead of manually installing Perl modules</A
>.
        </P
></TD
></TR
></TABLE
></DIV
><P
>The software packages necessary for the proper running of
      Bugzilla (with download links) are: 
      <P
></P
><OL
TYPE="1"
><LI
><P
>&#13;    <A
HREF="http://www.mysql.com/"
TARGET="_top"
>MySQL database server</A
>
    (3.22.5 or greater)
  </P
></LI
><LI
><P
>&#13;    <A
HREF="http://www.perl.org"
TARGET="_top"
>Perl</A
>
    (5.005 or greater, 5.6.1 is recommended if you wish to
    use Bundle::Bugzilla)
  </P
></LI
><LI
><P
>Perl Modules (minimum version):
  <P
></P
><OL
TYPE="a"
><LI
><P
>&#13;        <A
HREF="http://www.template-toolkit.org"
TARGET="_top"
>Template</A
>
        (v2.07)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/AppConfig/"
TARGET="_top"
>AppConfig 
        </A
>
        (v1.52)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz"
TARGET="_top"
>Text::Wrap</A
> 
        (v2001.0131)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://search.cpan.org/search?dist=File-Spec"
TARGET="_top"
>File::Spec 
        </A
>
        (v0.8.2)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/Data/"
TARGET="_top"
>Data::Dumper 
        </A
> 
        (any)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/Mysql/"
TARGET="_top"
>DBD::mysql
        </A
> 
        (v1.2209)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/DBI/"
TARGET="_top"
>DBI</A
> 
        (v1.13)
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/Date/"
TARGET="_top"
>Date::Parse
        </A
> 
        (any)
      </P
></LI
><LI
><P
>&#13;        CGI::Carp 
        (any)
      </P
></LI
></OL
>
  and, optionally:
  <P
></P
><OL
TYPE="a"
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/GD/"
TARGET="_top"
>GD</A
>
        (v1.19) for bug charting
      </P
></LI
><LI
><P
>&#13;        <A
HREF="http://www.cpan.org/modules/by-module/Chart/"
TARGET="_top"
>Chart::Base 
        </A
>
        (v0.99c) for bug charting
      </P
></LI
><LI
><P
>&#13;        XML::Parser 
        (any) for the XML interface
      </P
></LI
><LI
><P
>&#13;        MIME::Parser 
        (any) for the email interface
      </P
></LI
></OL
>          
  </P
></LI
><LI
><P
>&#13;    The web server of your choice. 
    <A
HREF="http://www.apache.org/"
TARGET="_top"
>Apache</A
> 
    is highly recommended.
  </P
></LI
></OL
>

      <DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>It is a good idea, while installing Bugzilla, to ensure that there
        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.</P
></TD
></TR
></TABLE
></DIV
>

      <DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Linux-Mandrake 8.0 includes every
        required and optional library for Bugzilla. The easiest way to
        install them is by using the 
        <TT
CLASS="filename"
>urpmi</TT
>

        utility. If you follow these commands, you should have everything you
        need for Bugzilla, and 
        <TT
CLASS="filename"
>checksetup.pl</TT
>

        should not complain about any missing libraries. You may already have
        some of these installed.</P
><P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>urpmi perl-mysql</B
>
          </TD
></TR
><TR
><TD
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>urpmi perl-chart</B
>
          </TD
></TR
><TR
><TD
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>urpmi perl-gd</B
>
          </TD
></TR
><TR
><TD
>&#13;          <SAMP
CLASS="prompt"
>bash#</SAMP
>

          <B
CLASS="command"
>urpmi perl-MailTools</B
>

          (for Bugzilla email integration)</TD
></TR
><TR
><TD
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>urpmi apache-modules</B
>
          </TD
></TR
></TBODY
></TABLE
><P
></P
></TD
></TR
></TABLE
></DIV
>
      </P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="install-mysql"
>4.1.3. MySQL</A
></H2
><P
>Visit the MySQL homepage at 
      <A
HREF="http://www.mysql.com"
TARGET="_top"
>www.mysql.com</A
>
      to grab and install the latest stable release of the server. 
      </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> Many of the binary
        versions of MySQL store their data files in 
        <TT
CLASS="filename"
>/var</TT
>.
        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 <TT
CLASS="filename"
>configure</TT
>
         if you build MySQL from source yourself.</P
></TD
></TR
></TABLE
></DIV
><P
>If you install from something other than an RPM or Debian 
      package, you will need to add <TT
CLASS="filename"
>mysqld</TT
>
      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. 
      </P
><P
>Change your init script to start 
      <TT
CLASS="filename"
>mysqld</TT
>
      with the ability to accept large packets. By default, 
      <TT
CLASS="filename"
>mysqld</TT
>
      only accepts packets up to 64K long. This limits the size of
      attachments you may put on bugs. If you add 
      <VAR
CLASS="option"
>-O max_allowed_packet=1M</VAR
>
      to the command that starts 
      <TT
CLASS="filename"
>mysqld</TT
>
      (or <TT
CLASS="filename"
>safe_mysqld</TT
>), 
      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.</P
><P
>If you plan on running Bugzilla and MySQL on the same machine,
      consider using the 
      <VAR
CLASS="option"
>--skip-networking</VAR
>
      option in the init script. This enhances security by preventing
      network access to MySQL.</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="install-perl"
>4.1.4. Perl</A
></H2
><P
>Any machine that doesn't have Perl on it is a sad machine indeed.
      Perl can be got in source form from 
      <A
HREF="http://www.perl.com"
TARGET="_top"
>perl.com</A
> for the rare 
      *nix systems which don't have it. 
      Although Bugzilla runs with all post-5.005
      versions of Perl, 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 5.6.1.</P
><DIV
CLASS="tip"
><A
NAME="bundlebugzilla"
></A
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>You can skip the following Perl module installation steps by
        installing 
        <SPAN
CLASS="productname"
>Bundle::Bugzilla</SPAN
>

        from 
        <A
HREF="glossary.html#gloss-cpan"
><I
CLASS="glossterm"
>CPAN</I
></A
>, 
        which installs all required modules for you.</P
><P
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>perl -MCPAN -e 'install "Bundle::Bugzilla"'</B
>
          </SAMP
>
        </P
><P
>Bundle::Bugzilla doesn't include GD, Chart::Base, or
        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.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="perl-modules"
>4.1.5. Perl Modules</A
></H2
><P
> 
      All Perl modules can be found on the
      <A
HREF="http://www.cpan.org"
TARGET="_top"
>Comprehensive Perl 
      Archive Network</A
> (CPAN). The
      CPAN servers have a real tendency to bog down, so please use mirrors.
    </P
><P
>Quality, general Perl module installation instructions can be
      found on the CPAN website, but the easy thing to do is to just use the
      CPAN shell which does all the hard work for you.
      To use the CPAN shell to install a module: 
      </P
><P
>&#13;        <SAMP
CLASS="computeroutput"
>&#13;          <SAMP
CLASS="prompt"
>bash#</SAMP
>
          <B
CLASS="command"
>perl -MCPAN -e 'install "&#60;modulename&#62;"'</B
>
        </SAMP
>
      </P
><P
>&#13;      To do it the hard way: 
      </P
><P
>Untar the module tarball -- it should create its own
      directory</P
><P
>CD to the directory just created, and enter the following
      commands: 
      <P
></P
><OL
TYPE="1"
><LI
><P
>&#13;            <SAMP
CLASS="computeroutput"
>&#13;              <SAMP
CLASS="prompt"
>bash#</SAMP
>

              <B
CLASS="command"
>perl Makefile.PL</B
>
            </SAMP
>
          </P
></LI
><LI
><P
>&#13;            <SAMP
CLASS="computeroutput"
>&#13;              <SAMP
CLASS="prompt"
>bash#</SAMP
>

              <B
CLASS="command"
>make</B
>
            </SAMP
>
          </P
></LI
><LI
><P
>&#13;            <SAMP
CLASS="computeroutput"
>&#13;              <SAMP
CLASS="prompt"
>bash#</SAMP
>

              <B
CLASS="command"
>make test</B
>
            </SAMP
>
          </P
></LI
><LI
><P
>&#13;            <SAMP
CLASS="computeroutput"
>&#13;              <SAMP
CLASS="prompt"
>bash#</SAMP
>

              <B
CLASS="command"
>make install</B
>
            </SAMP
>
          </P
></LI
></OL
>
      </P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Many people complain that Perl modules will not install for
        them. Most times, the error messages complain that they are missing a
        file in 
        <SPAN
CLASS="QUOTE"
>"@INC"</SPAN
>. 
        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 
        <EM
>are</EM
>
        the local UNIX sysadmin, please consult the newsgroup/mailing list
        for further assistance or hire someone to help you out.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN580"
>4.1.5.1. DBI</A
></H3
><P
>The DBI module is a generic Perl module used the
      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
      module, but Perl's MakeMaker system simplifies the C compilation
      greatly.</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN583"
>4.1.5.2. Data::Dumper</A
></H3
><P
>The Data::Dumper module provides data structure persistence for
      Perl (similar to Java's serialization). It comes with later
      sub-releases of Perl 5.004, but a re-installation just to be sure it's
      available won't hurt anything.</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN586"
>4.1.5.3. MySQL-related modules</A
></H3
><P
>The Perl/MySQL interface requires a few mutually-dependent Perl
      modules. These modules are grouped together into the the
      Msql-Mysql-modules package.</P
><P
>The MakeMaker process will ask you a few questions about the
      desired compilation target and your MySQL installation. For most of the
      questions the provided default will be adequate, but when asked if your
      desired target is the MySQL or mSQL packages, you should
      select the MySQL related ones. Later you will be asked if you wish to
      provide backwards compatibility with the older MySQL packages; you
      should answer YES to this question. The default is NO.</P
><P
>A host of 'localhost' should be fine and a testing user of 'test'
      with a null password should find itself with sufficient access to run
      tests on the 'test' database which MySQL created upon installation.
      </P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN591"
>4.1.5.4. TimeDate modules</A
></H3
><P
>Many of the more common date/time/calendar related Perl modules
      have been grouped into a bundle similar to the MySQL modules bundle.
      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.
      </P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN594"
>4.1.5.5. GD (optional)</A
></H3
><P
>The GD library was written by Thomas Boutell a long while ago to
      programatically generate images in C. Since then it's become the
      defacto standard for programatic image construction. The Perl bindings
      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
      so you must install it if you want any of the graphing to work.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The Perl GD library requires some other libraries that may or
        may not be installed on your system, including 
        <CODE
CLASS="classname"
>libpng</CODE
>
        and 
        <CODE
CLASS="classname"
>libgd</CODE
>. 
        The full requirements are listed in the Perl GD library README.
        If compiling GD fails, it's probably because you're
        missing a required library.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN601"
>4.1.5.6. Chart::Base (optional)</A
></H3
><P
>The Chart module provides Bugzilla with on-the-fly charting
      abilities. It can be installed in the usual fashion after it has been
      fetched from CPAN. 
      Note that earlier versions that 0.99c used GIFs, which are no longer
      supported by the latest versions of GD.</P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="AEN604"
>4.1.5.7. Template Toolkit</A
></H3
><P
>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.  However, there are
      known problems with XS Stash and Perl 5.005_02 and lower.  If you
      wish to use these older versions of Perl, please use the regular
      stash.</P
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN607"
>4.1.6. HTTP Server</A
></H2
><P
>You have a freedom of choice here - Apache, Netscape or any other
      server on UNIX would do. You can run the web server on a
      different machine than MySQL, but need to adjust the MySQL 
      <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>
      user permissions accordingly. 
      <DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>We strongly recommend Apache as the web server to use. The
        Bugzilla Guide installation instructions, in general, assume you are
        using Apache. If you have got Bugzilla working using another webserver,
        please share your experiences with us.</P
></TD
></TR
></TABLE
></DIV
>
      </P
><P
>You'll want to make sure that your web server will run any file
      with the .cgi extension as a CGI and not just display it. If you're
      using Apache that means uncommenting the following line in the httpd.conf
      file: 
      <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>AddHandler cgi-script .cgi</PRE
></FONT
></TD
></TR
></TABLE
>
      </P
><P
>With Apache you'll also want to make sure that within the
      httpd.conf file the line: 
      <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;Options ExecCGI
AllowOverride Limit
      </PRE
></FONT
></TD
></TR
></TABLE
>

      is in the stanza that covers the directories into which you intend to
      put the bugzilla .html and .cgi files.

        <DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>AllowOverride Limit allows the use of a Deny statement in the
          .htaccess file generated by checksetup.pl</P
><P
>Users of older versions of Apache may find the above lines 
          in the srm.conf and access.conf files, respecitvely.</P
></TD
></TR
></TABLE
></DIV
>
      </P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>There are important files and directories that should not be a
        served by the HTTP server - most files in the 
        <SPAN
CLASS="QUOTE"
>"data"</SPAN
>
        and 
        <SPAN
CLASS="QUOTE"
>"shadow"</SPAN
>
        directories and the 
        <SPAN
CLASS="QUOTE"
>"localconfig"</SPAN
>
        file. You should configure your HTTP server to not serve 
        these files. Failure to do so will expose critical passwords and
        other data. Please see 
        <A
HREF="extraconfig.html#htaccess"
>.htaccess files and security</A
>
        for details on how to do this for Apache; the checksetup.pl
        script should create appropriate .htaccess files for you.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN626"
>4.1.7. Bugzilla</A
></H2
><P
>You should untar the Bugzilla files into a directory that you're
      willing to make writable by the default web server user (probably 
      <SPAN
CLASS="QUOTE"
>"nobody"</SPAN
>). 
      You may decide to put the files in the main web space for your
      web server or perhaps in 
      <TT
CLASS="filename"
>/usr/local</TT
>
      with a symbolic link in the web space that points to the Bugzilla
      directory.</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>If you symlink the bugzilla directory into your Apache's HTML
        heirarchy, you may receive 
        <SPAN
CLASS="errorname"
>Forbidden</SPAN
>
        errors unless you add the 
        <SPAN
CLASS="QUOTE"
>"FollowSymLinks"</SPAN
>
        directive to the &#60;Directory&#62; entry for the HTML root
        in httpd.conf.</P
></TD
></TR
></TABLE
></DIV
><P
>Once all the files are in a web accessible directory, make that
      directory writable by your webserver's user. This is a temporary step
      until you run the post-install 
      <TT
CLASS="filename"
>checksetup.pl</TT
>
      script, which locks down your installation.</P
><P
>Lastly, you'll need to set up a symbolic link to 
      <TT
CLASS="filename"
>/usr/bonsaitools/bin/perl</TT
>
      for the correct location of your Perl executable (probably 
      <TT
CLASS="filename"
>/usr/bin/perl</TT
>). 
      Otherwise you must hack all the .cgi files to change where they look
      for Perl. This can be done using the following Perl one-liner, but 
      I suggest using the symlink approach to avoid upgrade hassles.
      </P
><P
> 
        <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>perl -pi -e
        's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm
        processmail syncshadowdb</PRE
></FONT
></TD
></TR
></TABLE
>

        Change <TT
CLASS="filename"
>/usr/bin/perl</TT
> to match the location
        of Perl on your machine.
      </P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN643"
>4.1.8. Setting Up the MySQL Database</A
></H2
><P
>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
      a high quality bug tracker.</P
><P
>First, you'll want to fix MySQL permissions to allow access from
      Bugzilla. For the purpose of this Installation section, the Bugzilla
      username will be 
      <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>, and will have minimal permissions. 
      </P
><P
>Begin by giving the MySQL root user a password. MySQL passwords are limited
      to 16 characters. 
      <P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>mysql -u root mysql</B
>
          </SAMP
>
        </TD
></TR
><TR
><TD
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
>

            <B
CLASS="command"
>UPDATE user SET Password=PASSWORD('&#60;new_password&#62;')
            WHERE user='root';</B
>
          </SAMP
>
        </TD
></TR
><TR
><TD
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
>

            <B
CLASS="command"
>FLUSH PRIVILEGES;</B
>
          </SAMP
>
        </TD
></TR
></TBODY
></TABLE
><P
></P
>

      From this point on, if you need to access MySQL as the MySQL root user,
      you will need to use 
      <B
CLASS="command"
>mysql -u root -p</B
>

      and enter &#60;new_password&#62;. Remember that MySQL user names have
      nothing to do with Unix user names (login names).</P
><P
>Next, we use an SQL <B
CLASS="command"
>GRANT</B
> command to create a 
      <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>

      user, and grant sufficient permissions for checksetup.pl, which we'll
      use later, to work its magic. This also restricts the 
      <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>
      user to operations within a database called 
      <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>, and only allows the account to connect from 
      <SPAN
CLASS="QUOTE"
>"localhost"</SPAN
>. 
      Modify it to reflect your setup if you will be connecting from
      another machine or as a different user.</P
><P
>Remember to set &#60;bugs_password&#62; to some unique password.</P
><P
>If you are using MySQL 4.0 or newer, enter:
      <P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
>

            <B
CLASS="command"
>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
            ALTER,CREATE,DROP,LOCK TABLES,CREATE TEMPORARY
            TABLES,REFERENCES ON bugs.* TO bugs@localhost
            IDENTIFIED BY '&#60;bugs_password&#62;';</B
>
          </SAMP
>
        </TD
></TR
><TR
><TD
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
>

            <B
CLASS="command"
>FLUSH PRIVILEGES;</B
>
          </SAMP
>
        </TD
></TR
></TBODY
></TABLE
><P
></P
>
      </P
><P
>If you are using an older version of MySQL,
        the LOCK TABLES and CREATE TEMPORARY TABLES permissions
        need to be removed from the list:
        <P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>&#13;            <SAMP
CLASS="computeroutput"
>&#13;              <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
>

              <B
CLASS="command"
>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
              ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost
              IDENTIFIED BY '&#60;bugs_password&#62;';</B
>
            </SAMP
>
          </TD
></TR
><TR
><TD
>&#13;            <SAMP
CLASS="computeroutput"
>&#13;              <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
>

              <B
CLASS="command"
>FLUSH PRIVILEGES;</B
>
            </SAMP
>
          </TD
></TR
></TBODY
></TABLE
><P
></P
>
      </P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN690"
>4.1.9. <TT
CLASS="filename"
>checksetup.pl</TT
></A
></H2
><P
>Next, run the magic checksetup.pl script. (Many thanks to 
      <A
HREF="mailto:holgerschurig@nikocity.de"
TARGET="_top"
>Holger Schurig </A
> 
      for writing this script!) 
      This script is designed to make sure your MySQL database and other
      configuration options are consistent with the Bugzilla CGI files. 
      It will make sure Bugzilla files and directories have reasonable
      permissions, set up the 
      <TT
CLASS="filename"
>data</TT
>
      directory, and create all the MySQL tables. 
      <P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>&#13;          <SAMP
CLASS="computeroutput"
>&#13;            <SAMP
CLASS="prompt"
>bash#</SAMP
>

            <B
CLASS="command"
>./checksetup.pl</B
>
          </SAMP
>
        </TD
></TR
></TBODY
></TABLE
><P
></P
>

      The first time you run it, it will create a file called 
      <TT
CLASS="filename"
>localconfig</TT
>.</P
><P
>This file contains a variety of settings you may need to tweak
      including how Bugzilla should connect to the MySQL database.</P
><P
>The connection settings include: 
      <P
></P
><OL
TYPE="1"
><LI
><P
>server's host: just use 
          <SPAN
CLASS="QUOTE"
>"localhost"</SPAN
>
          if the MySQL server is local</P
></LI
><LI
><P
>database name: 
          <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>
          if you're following these directions</P
></LI
><LI
><P
>MySQL username: 
          <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>
          if you're following these directions</P
></LI
><LI
><P
>Password for the 
          <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>
          MySQL account; (&#60;bugs_password&#62;) above</P
></LI
></OL
>
      </P
><P
>Once you are happy with the settings, 
      <TT
CLASS="filename"
>su</TT
> to the user
      your web server runs as, and re-run 
      <TT
CLASS="filename"
>checksetup.pl</TT
>. (Note: on some security-conscious
      systems, you may need to change the login shell for the webserver 
      account before you can do this.)
      On this second run, it will create the database and an administrator
      account for which you will be prompted to provide information.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The checksetup.pl script is designed so that you can run it at
        any time without causing harm. You should run it after any upgrade to
        Bugzilla.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN722"
>4.1.10. Mail Transfer Agent (MTA)</A
></H2
><P
>Bugzilla is dependent on the availability of an e-mail system for its user
      authentication and for other tasks. </P
><P
>On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will suffice.
      Sendmail, Postfix, qmail and Exim are examples of common MTAs. Sendmail is the 
      original Unix MTA, but the others are easier to configure, and therefore many people
      replace Sendmail with Postfix or Exim. They are drop-in replacements, so that Bugzilla
      will not distinguish between them.</P
><P
>Consult the manual for the specific MTA you choose for detailed installation
      instructions. Each of these programs will have their own configuration files where you must
      configure certain parameters to ensure that the mail is delivered properly. They
      are implemented as services, and you should ensure that the MTA is in the
      auto-start list of services for the machine.</P
><P
>If a simple mail sent with the command-line 'mail' program succeeds, then
      Bugzilla should also be fine.</P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN728"
>4.1.11. Configuring Bugzilla</A
></H2
><P
>&#13;      You should run through the parameters on the Edit Parameters page
      (link in the footer) and set them all to appropriate values. 
      They key parameters are documented in <A
HREF="parameters.html"
>Section 5.1</A
>.
      </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="installation.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="extraconfig.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Installation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="installation.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Optional Additional Configuration</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>