<!-- $Id: install.install.hlp,v 1.4 2003/07/01 04:12:13 kobudo Exp $ -->
<h1>Installing dotProject</h1>

<h2>Requirements</h2>
<p><b>dotProject</b> requires a functioning web server with integrated PHP and MySQL support, and, of course, a web browser.  Web server implemenations include:</p>

<ul>
	<li><b>LAMP</b>: Linux+Apache+MySQL+PHP</li>
	<li><b>WAMP</b>: Windows+Apache+MySQL+PHP</li>
	<li><b>WIMP</b>: Windows+IIS+MySQL+PHP</li>
</ul>

<br />

<p><b>Web Server</b></p>

<p>Apache (www.apache.org) is recommended to be version 1.3.27.  Apache version 2.x may have some issues as the implementation of the SAPI module with Apache is considered experimental.</p>

<p>Apache 1.3.20+ implementations have been successfully tested on Windows and Linux.</p>

<br />

<p><b>PHP</b></p>

<p>PHP (www.php.net) version 4.1.x or higher is required.  PHP versions earlier than 4.0.x are NO LONGER SUPPORTED.</p>

<p>PHP needs to have the GD library installed to allow the Gantt charts to work.  Use the phpinfo() function on your local (or hosted) system to see if this is compiled/installed with PHP.<p>

<br />

<p><b>MySQL</b></p>

<p>MySQL (www.mysql.com) version 3.23.51 or higher is recommended. You will also need an administration client for MySQL (such as MySQL Command Centre available from the MySQL web site).</p>

<br />

<p><b>Browser</b></p>

<p>You will also need a forth generation browser that supports style sheets and javascript
(IE Version 5.5 or better, Mozilla 1.2, Netscape 7.x, etc).  Many PNG image files are used in dotProject with alpha-transparency.  Later versions of Mozilla and Netscape will render these properly. A patch has been applied to allow IE 6.0 to render these images also.  However, earlier version of IE will not display the background of the images properly.</p>

<br />

<h2>Installing dotProject for the first time</h2>

<ol>
	<li>Download the most recent dotproject tarball from <a href="http://sourceforge.net/projects/dotproject/" target="_blank">http://sourceforge.net/projects/dotproject/</a></li>
        
	<li>Unpack the tarball in your web root directory with a Windows unzip program or on *nix:
	<pre>tar -zxvf dotproject_*.tar.gz</pre>
    [Note: replace the * with the appropriate version.]</li>

	<li>Create the dotproject database in MySQL.
		<ul>
			<li>Create a new mysql database called {dotproject}</li>
			<li>Create a new user called {dotproject}</li>
			<li>Grant access to user {dotproject} on the {dotproject} database.</li>
			<li>Make sure to record the dotproject user's password, {yourpassword}.</li>
			<pre>
    // Customize to match your db_name, db_user, and db_pass.
    mysql> CREATE DATABASE dotproject;
    mysql> GRANT ALL PRIVILEGES ON dotproject.* 
            TO dotproject@localhost IDENTIFIED BY
            "yourpassword" WITH GRANT OPTION;</pre></li>
		</ul>
		</li>
	
	<li>Customize your Database Schema Script [OPTIONAL].
	<p>Open the file dotproject/db/dotproject_100.sql with a text editor
    and edit the last section where the default dotproject Admin
    Account is setup (line 351).</p>
    
    <p>We recommend that you specify a new admin username, password, 
    and email. Save your changes. [Alternatively, this step can 
    be completed in the "User Admin" section of dotproject after
    installation].</p>
	</li>

	<li>Populate the Database.
    Utilize the information from the Database Setup and the provided
    "/db/dotproject_100.sql" script to populate the dotproject database.
    <pre>#mysql -udotproject -pyourpassword dotproject < dotproject/db/dotproject_100.sql </pre>
	</li>
    
	<li>Configuration File Customization. Follow the instructions at the top of the file <code>dotproject/includes/config-dist.php</code></li>

	<li>Point your browser to http://yourdomain.com/dotproject/index.php.  If all is well, you should see a login page. 
	<pre>
Username: admin
Password: passwd</pre>
	</li>

	<li>Admin Password and Adding Other Users
    <p>Click on the "User Admin" button and change the admin password as soon as 
    possible (if not completed in step four above). You may also add other users
    with differing levels of access to your dotproject database.</p>
    
    <p>If you would like to provide an alternative email address for the login 
    screen's "Help! I've forgotten my username and password" mailto link, edit line 
    56 (or thereabouts) of /includes/login.php.  The default entry is:
        &lt;?php echo 'admin@' . $site_domain;?></p>
	</li>

	<li>File Management Configuration.
    
	<p>The File Management Module provides users with an opportunity to upload and
    share files. Several steps are necessary to make sure this module works 
    correctly.</p>

	<ol type="a">
		<li>It is very important that the $dPconfig['root_dir'] variable is set correctly in <code>"includes/config.php"</code>. $dPconfig['root_dir'] must provide the full path to the dotproject installation AND INCLUDE the installation folder name.
		<pre>
$dPconfig['root_dir'] = "/wwwroot/dotproject";  // Example ONE
$dPconfig['root_dir'] = "/var/www/html/dotproject";  // Example TWO
$dPconfig['root_dir'] = "C:/apache/htdocs/dotproject";  // No trailing slash
		</pre>
		</li>

		<li><p>Files Folder Permissions</p>
		<p>In order for the file upload to function, you will need to provide write priviledges to the file upload folder. The "default" file upload folder is named <code>"files"</code> and contains an <code>".htaccess"</code> file to 
        prevent unauthorized access.<p>
		<p>The safe way to the write permission on a POSIX system is via the following.  Determine what user is running the apache web server with the following system command:
		<pre>[user@localhost dotproject]# ps -ef | grep httpd</pre>
		The resulting list will show you the user that is running Apache (probably <code>apache</code>).  Change the owner of the files directory to this user:
		<pre>[user@localhost dotproject]# chown -R apache files/
[user@localhost dotproject]# chmod -R 0700 files/</pre>
		<p>You should not be lazy and just set the permissions on this directory to 777.  While this will work it provides leverage for a malicious attack from a cracker.</p>
		</li>

		<li><p>Troubleshooting</p>
		<p>Failure to specify the proper <code>$root_dir</code> OR failure to provide write permissions on the file upload folder will result in numerous error messages along the lines of:
		<pre>
Warning: Unable to create '{$root_dir}/files/0/{rnd #}': 
	Permission denied in {$root_dir}/dosql/addfile.php on line 17
Warning: Unable to move '/tmp/phpt9SeKp' to '{$root_dir}/files/0/{rnd #}'
	in {$root_dir}/dosql/addfile.php on line 17
Warning: fopen("{$root_dir}/files/0/{rnd #}","r") - No such file 
	or directory in {$root_dir}/dosql/addfile.php on line 51
Warning: Supplied argument is not a valid File-Handle resource in
	{$root_dir}/addfile.php on line 52
Warning: Cannot add header information - headers already sent by (output 
	started at {$root_dir}/dosql/addfile.php:17) in 
	{$root_dir}/dosql/addfile.php on line 92
		</pre>
		<p>Even though you may encounter error messages, there will still be an entry made for the various files in the database. However, the contents of the uploaded files will likely be lost. Instead the "files" will contain error messages that may help with troubleshooting.</p>
		<p>If you find that you are accumulating "file" listings, but your contents of the "files" folder is not changing, then you have probably provided an incorrect <code>$root_dir</code> path.</p>
		<p>You will also want to confirm that your <code>php.ini</code> file is configured to allow file uploading with <code>file_uploads = on</code>.</p>
		<p>You may want to increase your <b>Maximum File Upload Size</b> beyond your <code>php.ini</code> default setting. This procedure is described in the "Troubleshooting Page" of this documentation module.</p>
		</li>

		<li><p>Improving Security</p>
		<p>The default "files" folder contains an ".htaccess" file containing the following:
		</pre>
Options -All
deny from all</pre>
		<p>While this provides basic security, the paranoid can improve security further by:
		<ul>
			<li>Changing the name of the <code>"files"</code> folder to something less obvious.</li>
			<li>Moving the <code>"files"</code> folder outside of the webroot</li>
			<li>Both</li>
		</ul>
        <p>These security improvements will require technical skill, and will make "upgrading" to future versions of dotproject more challenging.</p>
		</li>
	</ol>
	</li>
</ol>
            
<h2>Web trouble ticket email gateway: dotproject/includes/gateway.pl</h2>
<pre>
---------------------------------------------------------------------------
(from the ticketsmith installation)

1.  Have a working perl install, with DBI and the DBD::MySQL bundles installed
2.  Be sure to protect the gateway.pl file.  You basically need to do one 
    of two things, either move it out of a web-accessible place or somehow 
    protect it from being accessed over the web:
    
            <Files "gateway.pl">
                    order deny,allow
                    deny from all
            </Files>
    
    If you don't protect it, one of two things will happen,  either users will be
    able to see the source and thus grab your Ticketsmith MySQL password, or
    something unpredictable will happen when Apache tries  to run it as a CGI
    script.  I don't think this could be harmful, but hey,  you never know.



7.  Edit the top of gateway.pl to fit your setup.


    
9.  Configure your MDA or MTA to pipe mail for your support list to gateway.pl.  For
    example,  here is a sample procmail recipe:

            :0
            * (^To:|^CC:|^Cc:) .*support@foo.bar
            |/path/to/gateway.pl

    You can also set Ticketsmith up directly with sendmail in /etc/aliases: 

            support: "|/path/to/gateway.pl"

    Keep in mind that with sendmail you need to either put gateway.pl in 
    /etc/smrsh or at least symlink to it from that directory so that 
    sendmail will execute it.  If you do this, you'll have to point 
    the /etc/aliases entry to the copy in /etc/smrsh.
</pre>
