<chapter id="admin.install">
    <title>Installation</title>

    <para>Following are the steps for a new MantisBT installation:</para>
    <itemizedlist>
        <listitem>
            <para>
                <link linkend="admin.about.download">Download</link>
                Mantis
            </para>
        </listitem>
        <listitem>
            <para>
                Go through MantisBT <link linkend="admin.config">Configuration</link>
                and set the database options + whatever options where you need to
                override the default values.
            </para>
        </listitem>
        <listitem>
            <para>Test your configuration through the admin
                folder
            </para>
        </listitem>
        <listitem>
            <para>Create a new administrator account and remove the
                standard user 'administrator'
            </para>
        </listitem>
    </itemizedlist>

    <section id="admin.install.summary">
        <title>Summary</title>

        <orderedlist>
            <listitem>
                <para>Tranfer files</para>
            </listitem>
            <listitem>
                <para>Uncompress files</para>
            </listitem>
            <listitem>
                <para>Generate database tables</para>
            </listitem>
            <listitem>
                <para>Edit configuration file, if needed</para>
            </listitem>
            <listitem>
                <para>PHP File extensions</para>
            </listitem>
            <listitem>
                <para>Login</para>
            </listitem>
            <listitem>
                <para>Add projects and users</para>
            </listitem>
        </orderedlist>
    </section>


        <section id="admin.install.new">
            <title>New Installations</title>

            <orderedlist>
                <listitem>
                    <para>First, transfer the file to your webserver using whatever
                        method you likebest (ftp, scp, etc). You will need to telnet/ssh
                        into the server machine forthe next steps.
                    </para>
                </listitem>
                <listitem>
                    <para>Next, untar/gunzip it to the directory that you want.The
                        usual command is (1 step):
                        tar zxvf &lt;filename.tar.gz&gt;
                        OR (2 steps):
                        gunzip &lt;filename.tar.gz&gt; tar xvf &lt;filename.tar&gt;
                        Winzip, Stuffit, and other programs should also be able to
                        handledecompression of the archive.At this point you may want to
                        rename the directory to something simpler like 'mantisbt'. You will
                        use the mv command to rename a directory (Windows users substitute
                        the "ren" command or use explorer).
                        mv &lt;directoryname&gt; mantisbt
                    </para>
                </listitem>
                <listitem>
                    <para>Next we will create the necessary database tables and a
                        basic configurationfile.From your web server, access
                        http://yoursite/mantisbt/admin/install.php.  This page will walk through
                        the following steps:

                        <orderedlist>
                            <listitem>
                                <para>check basic parameters for the web server</para>
                            </listitem>
                            <listitem>
                                <para>prompt for the database type and location, and a database
                                    user/passwordpair. For installion, an administrative user/password
                                    pair can also be provided. The operating user requires SELECT,
                                    INSERT, UPDATE, and DELETE privileges. For installation, INDEX,
                                    CREATE, ALTER, and DROP privileges arealso required.
                                </para>
                            </listitem>
                            <listitem>
                                <para>create the database and tables.
                                    WARNING: A DEFAULT ADMINISTRATOR level account is created. The
                                    account name and password are administrator / root.
                                    Use this when you first login to MantisBT. Immediately go to Manage
                                    and create at least one administrator level account. Immediately
                                    after that DISABLE or DELETE the administrator account. You can
                                    recreate it but you should delete the account to prevent the
                                    cookie_string from being used to trick the package. It would be
                                    even better to rename the account or delete it permanently.
                                    REMEMBER: After setting up the package, REMOVE the default
                                    administrator account.
                                </para>
                            </listitem>
                            <listitem>
                                <para>write a basic "config_inc.php file to define the
                                    database.
                                </para>
                            </listitem>
                            <listitem>
                                <para>perform some post installation checks on the
                                    system.
                                </para>
                            </listitem>
                        </orderedlist>

                    </para>
                </listitem>
                <listitem>
                    <para>The next part involves configuring the installation to
                        work with yourspecific setup.Open the file in an editor and add
                        anyother values that are required. There aremany more that you can
                        use to customize your MantisBT installation.
                        See <link linkend="admin.config">Configuration</link> for
                        in depth explanations.The file will overwrite the default values
                        with those necessary for setup.You can load up admin/check.php to
                        see if you set things up correctly.
                        NOTE: check.php sometimes reports the value of
                        register_globalsincorrectly.
                        Create a page with this line in it: &lt;? phpinfo() ?&gt;, save
                        itwith a .php extension and load it up in your web browser. It
                        will, among amultitude of other things, have the correct value of
                        register_globals that youare using.
                    </para>
                </listitem>

                <listitem>
                    <para>MantisBT now uses only .php files.If your webserver is
                        configured for other extensions (.PHP3, .PHTML) then youwill have
                        to have the administrator add support for .PHP files. This shouldbe
                        a trivial modification.Documentation can be found at:
                        http://www.php.net/manual/en/installation.php
                    </para>
                </listitem>

                <listitem>
                    <para>Login to your bugtracker and go to the manage section.
                        Click on the projects link. You will need to ADD a new project. Then
                        EDIT the new project and remember to ADD at least one category.
                        Otherwise you won't be able to add any issues. That should be
                        it. You're off and running.
                    </para>
                </listitem>
            </orderedlist>

        </section>

        <section id="admin.install.requirements">

            <title>Requirements</title>


            <para>The following versions are required for proper operation:</para>
            <informaltable>
                <tgroup cols="3"><tbody>
                        <row>
                            <entry>Package</entry>
                            <entry>Minimum Version</entry>
                            <entry>Tested with</entry>
                        </row>
                        <row>
                            <entry>MySQL</entry>
                            <entry>4.1.x</entry>
                            <entry>5.0.x</entry>
                        </row>
                        <row>
                            <entry>PostgreSQL (experimental)</entry>
                            <entry>7.0</entry>
                            <entry>8.0</entry>
                        </row>
                        <row>
                            <entry>PHP</entry>
                            <entry>5.2.x</entry>
                            <entry>5.2.x</entry>
                        </row>
                        <row>
                            <entry>Web Server</entry>
                            <entry></entry>
                            <entry>Apache 1.3.x, Apache 2.2.x, lighttpd 1.4.x, IIS 6.0</entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>

            <para>MantisBT is designed in a way to work in as many environments as possible.
            Hence the required extensions are minimal and many of them are optional affecting
            only one feature.  The following PHP extensions are the ones used:</para>

            <itemizedlist>
                <listitem>
                    <para>mysqli (or the extension for the DBMS being used) - mandatory.</para>
                </listitem>
                <listitem>
                    <para>Curl - if the Twitter integration feature is required.</para>
                </listitem>
                <listitem>
                    <para>GD - if the graphs feature is required.</para>
                </listitem>
                <listitem>
                    <para>fileinfo - Guesses the MIME type of attachments.
                    This extension is included by default from version 5.3.x
                    of PHP. For older versions of PHP you will need to install
                    the fileinfo PECL extension (this requires root access to
                    the server you're using). Without this extension, file
                    attachment previews and downloads may not work correctly as
                    MantisBT won't be able to send the Content-Type header to a
                    browser requesting an attachment.</para>
                </listitem>
            </itemizedlist>

        </section>

        <section id="admin.install.backups">

            <title>Backups</title>


            <para>It is recommended to backup your MantisBT database on a
                regular basis. This is easy to accomplish using the mysqldump
                command:
                mysqldump -u&lt;username&gt; -p&lt;password&gt; &lt;database
                name&gt; &gt; &lt;output file&gt;
                To restore a backup you will need to have a clean database. Then
                run:
                mysql -u&lt;username&gt; -p&lt;password&gt; &lt;database name&gt;
                &lt; &lt;input file&gt;
                You can also perform both of these tasks using
                <ulink url="http://www.phpmyadmin.net/">phpMyAdmin</ulink>
                A good idea is to make a backup script and run it regularly through
                cron or a task scheduler (for Windows see
                <ulink url="http://www.wincron.com/">WinCron</ulink>
                ).
                Using the current date in the filename can prevent overwriting and
                make cataloguing easier.
                !!! Backups should always be performed before an upgrade !!!
                Make sure to backup MantisBT code (which includes your configs +
                possibly customization), issue attachments / project documents, and
                database contents.
            </para>

        </section>

        <section id="admin.install.uninstall">

            <title>Uninstall</title>


            <para>
                It is recommended that you make an backup in case you wish to use
                your data in the future. See the
                <link linkend="admin.install.backups">Backups</link>
                page for details.
                To uninstall MantisBT:
                <itemizedlist>
                    <listitem>
                        <para>Delete the MantisBT directory and all files and
                            subdirectories.
                        </para>
                    </listitem>
                    <listitem>
                        <para>Drop all MantisBT tables from the database, these can be
                            identified by the configured prefix for the installation. The
                            default prefix is 'mantis'.
                        </para>
                    </listitem>
                    <listitem>
                        <para>Remove any customizations or additions that you may have
                            made.
                        </para>
                    </listitem>
                </itemizedlist>
                If you have the permissions to create/drop databases and you have a
                specific database for MantisBT that does not contain any other data,
                you can drop the whole database.
            </para>

        </section>
</chapter>
