-------------------------------------------------------------------------------
Mantis - a php based bugtracking system
Copyright (C) 2000  Kenzaburo Ito - kenito@300baud.org
-------------------------------------------------------------------------------

INSTALLATION

The following details the basic steps for installation on any system.  The
instructions may seem unix-centric but should work fine on Windows systems.

Barring complications, it should take you about 10-20 minutes to install,
configure, and be using Mantis.

Amandeep Jawa has provided an alternative and more detailed installation
document.  Use a browser and open doc/installation.html.

# --- Requirements ----------

* MySQL database
* PHP 3.0.13 or newer
* a webserver

# --- Summary ---------------

1. Tranfer files
2. Uncompress files
3. Generate database tables
4. Edit configuration file
5. PHP File extensions
6. Login

******************************************************************************

1. First, transfer the file to your webserver using whatever method you like
best (ftp, scp, etc).  You will need to telnet/ssh into the server machine for
the next steps.

2. Next, untar/gunzip it to the directory that you want.
The usual command is (1 step):

	tar zxvf <filename.tar.gz>

OR  (2 steps):

	gunzip <filename.tar.gz>
	tar xvf <filename.tar>

Winzip, Stuffit, and other programs should also be able to handle
decompression of the archive.

At this point you may want to rename the directory to something simpler like
'mantis'.  You will use the mv command to rename a directory (Windows users
substitute the "ren" command or use explorer).

mv <directoryname> mantis

If you are upgrading see the UPGRADING document.

2a.  Decide what sort of password encryption you will use.  You must do this
at install time. Currently, you can choose from:

* MD5 (the default method)
* plain text
* crypt

Plain is the least secure and passwords are stored without encryptoin.

MD5 should be supported on all installs of PHP.  MD5 is the default method.

Crypt may not be installed on non-Unix operating systems

MD5 and crypt are one-way algorithms: you will not be able to retrive the
original passwords.  Conversely administrators cannot see what your password
is.

*** NOTE: crypt was the default format before 0.17.0. MD5 is now the default
method.  You cannot switch methods in the middle of a working project and
expect users to still login.

2b.  Once you have chosen whch method to use, you will need to change into the
sql/ subdirectory and locate the "db_generate.sql" file.  Open up
"db_generate.sql" and go to the bottom of the file and replace the 4th value
in the last line with your chosen method. The 3 formats the password is stored
in are located just above the last few lines of the file.  MD5 is the default
method.

I'm sorry this is so primitive; a more mature method will soon be found.

3. Next we will create the necessary database tables.  Make sure you have
created the database ahead of time.  You should know your mysql username and
password as well.

Run the following command:

mysql -u<username> -p<password> <databasename> < db_generate.sql

You could also cut and paste the sql statements from db_generate.sql into a
package like phpMyAdmin or into your terminal window.

eg. Your username is bob, password is mypass, database name is bugtracker.

mysql -ubob -pmypass bugtracker < db_generate.sql

You may require an additional host parameter if your SQL server is on another
machine.  eg.  Your server is sqlserver

mysql -h sqlserver -ubob -pmypass bugtracker < db_generate.sql

* WARNING: A DEFAULT ADMINISTRATOR level account is created.  The account name
and password are administrator / root.  Use this when you first login to
Mantis. Immediately go to Manage and create at least one administrator level
account.  Immediately after that 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.

4. The next part involves configuring the installtion to work with your
specific setup.

In the default/ directory is the config_inc1.php and config_inc2.php files.
These contains all the global variable settings that you can set.  Do not edit
these files.  You will be using them as a reference instead.

config_inc1.php contains most of the options that you would want to configure.

config_inc2.php contains mostly names of files that are required.  You
probably will not have to override these settings except to specify a top or
bottom page to include.

Here are the important files for configuration:

mantis/config_inc.php.sample
mantis/default/config_inc1.php
mantis/default/config_inc2.php

Rename config_inc.php.sample to config_inc.php

Open the file in an editor and edit the values to match your settings.  The
sample file contains only essential settings.  There are many more that
you can use to customize your Mantis installation.  See the customization.html
file for in depth explanations.

The file will overwrite the default values with those necessary for setup.
The default config_inc1.php file has some comments which will help explain
the variables.  You can always add/overwrite more globals in this file as
well.

You can load up admin_check.php3 to see if you set things up correctly.

*** NOTE: admin_check sometimes reports the value of register_globals
incorrectly.  Create a page with this line in it: <? phpinfo() ?>, save it
with a ,php extension and load it up in your web browser.  It will, among a
multitude of other things, have the correct value of register_globals that you
are using.

5. Mantis now uses only .php files.

If your webserver is configured for other extensions (.PHP3, .PHTML) then you
will have to have the administrator add support for .PHP files.  This should
be a trivial modification.

Documentation can be found at: http://www.php.net/manual/en/installation.php

6.  Login to the 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 bug reports.

That should be it.  You're off and running.  For some help on custom editing
of the site please read the CUSTOMIZATION file.

-------------------------------------------------------------------------------
### Upgrading ###
-------------------------------------------------------------------------------

See the files: UPGRADING and db_upgrade.sql

-------------------------------------------------------------------------------
### Troubleshooting ###
-------------------------------------------------------------------------------

See TROUBLESHOOTING

-------------------------------------------------------------------------------
### Useful links ###
-------------------------------------------------------------------------------

http://www.php.net/        -  excellent documentation.
http://www.phpwizard.net/  -  an excellent web front end to mysql.
http://www.phpbuilder.net/ -  good help forums.
http://www.mysql.com/      -  good documentation.
http://www.apache.org/     -  you should be able to find what you need.