<?xml version="1.0"?>
<document>

  <properties>
    <author email="reinhard@spisser.it">Reinhard Spisser</author>
    <author email="tom@infoether.com">Tom Copeland</author>
    <title>Installation</title>
  </properties>

  <body>

<section name="Hardware requirements">
<p>
Hardware Requirements are largely dependent on the number of users that will use the system. A previous version of the software, SourceForge 2.5, has been running successfully for over a year on a Linux system based on a Pentium 133Mhz, 64MB Ram and 30 registered users.
</p>
</section>
<section name="Software requirements">
<p>
GForge should work correctly on any system configured like this:
<ol>
<li>Linux Operating System</li>
<li>Postgres 7.1 or later</li>
<li>Apache 1.3.22 or later</li>
<li>openssl >0.9.4</li>
<li>mod_ssl >2.4.10</li>
<li>PHP 4.0.4 or later</li>
<li>php_pgsql 4.0.4</li>
</ol>
</p>
<p>
Successful installations and operations have been done using the following systems:
</p>
<p>
RedHat Linux 8.0 with the following software configured (already bundled with RH8):
<ol>
<li>Postgres 7.2.2</li>
<li>Apache 2.0.40</li>
<li>openssl 0.9.6b</li>
<li>mod_ssl 2.0.40</li>
<li>PHP 4.2.2</li>
<li>php_pgsql 4.2.2</li>
</ol>
</p>
<p>
RedHat Linux 7.3:
<ol>
<li>Postgres 7.2-1</li>
<li>Apache 1.3.27</li>
<li>openssl 0.9.6b</li>
<li>mod_ssl 2.0.40</li>
<li>PHP 4.1.2</li>
<li>php_pgsql 4.1.2</li>
</ol>
</p>
    </section>
    <section name="Installation">
<subsection name="Installing the software">
<p>
<b>Note for Debian users</b>:<br/>
Debian Users can simply add <a href="http://people.debian.org/~bayle/">http://people.debian.org/~bayle</a>
 to /etc/apt/sources.list and type "apt-get install gforge" to install a working GForge-3.0 system, thanks to Christian Bayle and the Debian-SF project.
<p/>
To install GForge, follow these steps:
<ol>
<li>Login as root user</li>
<li>cd to <code>/var/www/</code></li>
<li>Extract the content of gforge-3.0b1.tar.bz2 to the current directory:<br/>
<code>
bzip2 -dc gforge-3.0b1.tar.bz2 | tar xvf -
<br/>
</code>

</li>
<li>Now there's a directory /var/www/gforge-3.0b1</li>
<li>Rename this directory to /var/www/gforge-3.0/ - <code>mv /var/www/gforge3.0b1/ /var/www/gforge-3.0</code></li>
</ol>

</p>
</subsection>

<subsection name="Configuring the Web Server">
<p>

<ol>
<li>Open <code> /etc/httpd/conf/httpd.conf </code>:</li>
<li>Change the DocumentRoot to point to the <code>www</code> directory:
<code><br/>
<br/>
DocumentRoot "/var/www/gforge-3.0/www"
<br/>
<br/></code>

</li>
<li>
Change the Directory directive following the DocumentRoot as follows:

<source><![CDATA[
<Directory "/var/www/gforge-3.0/www">
    Options Indexes FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
    ErrorDocument 404 /404.php
</Directory>
]]></source>
<p/>
</li>
<li>Change the ScriptAlias to <code>/var/www/gforge-3.0/cgi-bin</code>
</li>
<li>Change the Directory configuration following the ScriptAlias directive as follows:
<source><![CDATA[
<Directory "/var/www/gforge-3.0/cgi-bin">
    AllowOverride All
    Options None
    Order allow,deny
    Allow from all
</Directory>
]]></source>
<p/>
</li>
<li>If you wish to set up a server with HTTPS, you need to configure the 
<code>VirtualHost:443</code> section of httpd.conf.

</li>

<li>Add several new filenames to the <code>DirectoryIndex</code> directive:<br/>
<code>
DirectoryIndex index.html index.shtml index.cgi index.php
<br/></code>
</li>

<li>Configuring PHP for Apache
<br/>
The configuration for the PHP module for Apache is different for Apache versions 1.3 and 2.0.
Follow the instructions for the version installed on your system.
<ul>
<li>Configuring PHP for Apache 1.3
<br/>
<ol>

<li>Open  <code> /etc/httpd/conf/httpd.conf </code>:</li>

<li> Insert the following instructions after the DocumentRoot directive:

<source>
<![CDATA[
<Location /projects>
  ForceType application/x-httpd-php
</Location>
<Location /users>
  ForceType application/x-httpd-php
</Location> 
]]>
</source>
<p/>
Ensure the following lines are present and not commented out:
<code><br/>
LoadModule php_module	modules/libphp.so<br/>
AddModule mod_php.c
<br/></code>

</li>
</ol>
</li>
<li>Configuring PHP for Apache 2.0
<br/>
<ol>
<li>Open <code>/etc/httpd/conf.d/php.conf</code></li>
<li>Change the existing Files directive to:

<source><![CDATA[
<Files *.php>
    SetOutputFilter PHP
    SetInputFilter PHP
    AcceptPathInfo On
    LimitRequestBody 2097152
</Files>
]]></source>
<p/>

The LimitRequestBody directive allows you to limit the maximum number of bytes of a request (including uploads). The default is
524288 (512Kb). This means that you cannot upload files with a size >512Kb.
With this directive we set it to 2MB. If you wish to set this value higher than 2MB, you must also edit the upload_max_filesize directive in php.conf.

<br/>
</li>
<li>
Add the following lines:
<br/>
<source><![CDATA[
<Files projects>
SetOutputFilter PHP
SetInputFilter PHP
AcceptPathInfo on
</Files>

<Files users>
SetOutputFilter PHP
SetInputFilter PHP
AcceptPathInfo on
</Files>
]]></source>

<p/>
</li>
</ol>
</li>

</ul>
</li>
<li>Restart the Apache server: 
<code>/etc/init.d/httpd restart</code></li>
</ol>
</p>
</subsection>
<subsection name="Configuring the database">
<ol>
<li>Configuring PostgreSQL
<p>Check if your postgres accept connections on TCP/IP sockets. On RedHat 8.0, this is by default disabled.  To verify this, type the following command:
<br/>
<code>
psql -h localhost template1
</code>
<p/>

If you get an error like this:<br/>
<code>
psql: could not connect to server: Connection refused<br/>
        Is the server running on host localhost and accepting<br/>
        TCP/IP connections on port 5432?<br/>
</code>

you need to:
<br/>
cd to:
<code>
/etc/init.d/<br/>
vi postgresql
</code>

<p/>
add the -i option to the pg_ctl command so that the result is:

<br/>
<code>
 su -l postgres -s /bin/sh -c "/usr/bin/pg_ctl -o -i -D $PGDATA -p /usr/bin/postmaster start  &gt; /dev/null 2>&amp;1" &lt; /dev/null
</code>
<p/>
On some systems, PostgreSQL is configured with the ident clause, allowing you only to access to the database if the username/password of your server is identical to the database username/password.  You should either create a user called gforge on your server or disable this feature:
<br/>
<code>
su - postgres<br/>
</code>
open <code>/var/lib/pgsql/data/pg_hba.conf</code> and insert the following lines:
<br></br>
For PostgreSQL 7.3:
<source>
local all all trust
host all all 127.0.0.1 255.255.255.255 crypt
</source>
For PostgreSQL 7.2:
<source>
local all trust
host all 127.0.0.1 255.255.255.255 crypt
</source>

<p/>
and comment out all other directives.
<br/>
Restart the PostgreSQL server as root user:
<br/>
<code>/etc/init.d/postgresql restart</code>
<br/>

Create the database user:
<br/>
<source>
su - postgres
createuser gforge -W 
</source>
<br/>

<br/>
Answer the following two questions:

<source>
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) n
</source>
and insert a password for the user to be created.

<p/>
Create the database using the command:<br/>
<code>
createdb -U gforge gforge<br/>
</code>

<p/>
</p>

</li>

<li>Installing the database

<br/>

Now it's time to install the database. The steps are:

<ol>

<li>cd to <code>/var/www/gforge-3.0/db</code></li>
<li>
<code>
psql -a -U gforge gforge &lt; gforge3.sql > /tmp/gforge.sql.log 2&gt;&amp;1
</code>
<br/>
</li>
</ol>

<b>Mandrake 9 installation notes (thanks to Francois Elie)</b>

<ul>
 <li>Edit /var/lib/pgsql/data/postgresql.conf:<br/>
  <ul>
  <li><code>set tcpip_socket=true</code></li>
  <li><code>local all md5</code></li>
 </ul>
 </li>


 <li>Edit /var/lib/pgsql/data/pg_hba.conf:<br/>
 <ul>
  <li>Set for example access right to</li>
  <li><code>host     all     0.0.0.0   0 0.0.0   md5</code></li>
 </ul>
</li>
</ul>
</li>
<li>Then restart the server <code>/etc/rc.d/init.d/postgresql restart</code></li>

</ol>

</subsection>

<subsection name="Configuring PHP">
<p>
Verify the version of PHP installed on your system:
<br/>
<code>php -v</code>
<ol>
<li>open <code>/etc/php.ini</code></li>
<li>if the PHP version you're using is 4.2.0 or later, enable the register_globals variable:
<br><code>register_globals = On</code></br>
</li>
<li> and configure the include_path directive as follows:
<br/><code>include_path=".:/var/www/gforge-3.0/:/var/www/gforge-3.0/common/include:<br/>
 /var/www/gforge-3.0/www/include:/var/www/gforge-3.0/etc/</code>:
<br/>

</li>
</ol>

</p>
</subsection>

<subsection name="Configuring cvsweb">
<p>First download the latest cvsweb release - 1.112 - from http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/</p>
<p>Copy the tar.gz file into a tmp directory and unzip it:</p>
<source>
tar -zxvf cvsweb-1.112.tar.gz
</source>
<p>cvsweb consists of a Perl script (cvsweb.cgi), a configuration file (cvsweb.conf), and some icons (back.gif, dir.gif, etc).</p>
<ul>
<li>Copy the cvsweb.cgi script into Apache's cgi-bin directory</li>
<li>Copy the cvsweb.conf file into Apache's configuration directory (such as /etc/httpd/conf/ on RedHat 9)</li>
<li>Edit cvsweb.conf</li>
<li>change %CVSROOT hash to include your repositories</li>
<li>change the $cvstreedefault variable to point to a default repository</li>
<li>TODO: can we add the repositories automagically? Or should we tweak cvsweb.cgi?</li>
<li>TODO: should we tweak cvsweb.cgi so it doesn't have a default repository?</li>
<li>Edit cvsweb.cgi</li>
<li>Change the $config variable to point the cvsweb.conf file</li>
<li>Change the $PATH variable to point to the directory that contains rlog</li>
</ul>
<p>Possible problems:
<ul>
<li><code>Error: Configuration not found</code> - edit cvsweb.cgi and point $config to the cvsweb.conf file</li>
<li><code>Error: Failed to spawn GNU rlog</code> - ensure rlog is in the directory pointed to by ENV{'PATH'}</li>
</ul>
</p>
</subsection>


<subsection name="Configuring GForge 3.0">
<p>
<ol>
<li>login as root user</li>
<li>create a directory gforge3-files:
<br/>
<code>mkdir /var/www/gforge3-files</code>

<br/>
Make this directory writeable by Apache<br/>
<code>
chown -R apache.apache /var/www/gforge3-files
</code>
<br/>
This directory will contain all files/patches uploaded to your gforge site.
<br/>
</li>

<li>Create a directory<code> /etc/gforge</code><br/></li>
<li>Copy the file <code>local.inc</code> from <code>/var/www/gforge/etc/</code> to <code>/etc/gforge/</code> </li>
<li>Open <code>/etc/gforge/local.inc</code>, configuring the following basic parameters:
<ol>
<li>
Database configuration:

<source><![CDATA[
$sys_dbhost="localhost"
$sys_dbname="gforge"
$sys_dbuser="gforge"
$sys_dbpasswd="gforge"
$sys_server="postgres"
      ]]></source>

<p/>
</li>
<li>
Change the value of the $sys_upload_dir to:
<code>$sys_upload_dir='/var/www/gforge3-files/';</code>
<br/>
</li>
<li>
Change the value of the $sys_urlroot to:<br/>
<code>$sys_urlroot="/var/www/gforge-3.0/www/";</code>
<br/>
</li>

<li>
The directives 
<code>$sys_default_domain</code> and <code>
$sys_fallback_domain </code>

should contain the domain of your server, e.g. gforge.org.

</li>
</ol>


</li>
<li>Restart Apache:
<code>/etc/init.d/httpd restart</code>
</li>
</ol>
</p>
</subsection>

<subsection name="Configuring GNU Mailman">
<p>GNU Mailman is used to help manage the GForge mailing lists.  To install it:</p>
<p>Install the 2.0.13 RPM (TODO add compilation instructions)</p>
<p>su to root and set the mailman password</p>
<p>Add the following to the httpd.conf</p>
<source>
Alias /pipermail/ /usr/local/mailman/archives/public/
ScriptAlias /mailman/ "/usr/local/mailman/cgi-bin/"
</source>
<p>Run the script <code>gforge/cronjobs/mailing_lists_create.php</code>; this creates any lists that are already in the database.</p>
</subsection>

<subsection name="Configuring CVS">
<p>GForge uses CVS via pserver for anonymous read only access and ext for developers to commit to the repositories.  To set it up:</p>
<p>Download and install the latest CVS RPM</p>
<p>Ensure the following info is in <code>/etc/services</code>:</p>
<source>
[tom@cougaarforge tom]$ cat /etc/services | grep cvspserver
cvspserver      2401/tcp                        # CVS client/server operations
cvspserver      2401/udp                        # CVS client/server operations
[tom@cougaarforge tom]$
</source>
<p>Ensure the following info is in <code>/etc/xinetd.d/cvspserver</code> (if it doesn't exist create a new file with the following text to enable anonymous access):</p>
<source>
[tom@cougaarforge xinetd.d]$ cat /etc/xinetd.d/cvspserver
service cvspserver
{
        disable = no
        socket_type  = stream
        protocol  = tcp
        wait   = no
        user    = root
        server   = /usr/bin/cvs
        server_args  = -f --allow-root=/path/to/my/cvsroot pserver
}
[tom@cougaarforge xinetd.d]$
</source>
<p>Now add an <code>anonymous</code> user to your system with a blank password, or one of <code>anonymous</code></p>
<p>TODO - does the CVSROOT/readers file get added via a cronjob or something?</p>
<p>TODO - any extra notes on setting up dev access?  i.e., uploading of public key and such?</p>
</subsection>
</section>

<section name="Verifying the installation">
<p>
To verify if everything was installed correctly, use the browser and connect to GForge. You should see the GForge homepage.  If you get an error:

<br/>
<code> Could Not Connect to Database:</code>
<br/>
Check if you have followed all installation instructions for the database.
</p>

    </section>
<section name="Creating the admin user">
<p>
Connect to GForge and register a new account.
<br/>


<ol>
<li>Insert a valid email address; this will be used for the account confirmation.<br/>
</li>
<li>Open your e-mail client, wait for the email from GForge site and follow the link that appears on the message.<br/>
</li>
<li>Verify in Account Maintenance the user id of the user registered.<br/>
Usually this is 102, but you can verify this by running the following SQL query via the Postgres <code>psql</code> utility:
<br/>
<code>
psql -c "select user_id from users where user_name='***YOUR USER NAME***'" gforge gforge

</code>
<br/>
</li>
<li>Now set up the newly added user to be a GForge administrator
<code>
<br/>
psql -U gforge -d gforge
<br/>
insert into user_group (user_id,group_id,admin_flags) values (102,1,'A');
<br/>

</code>
</li>
</ol>
</p>
</section>

  </body>
</document>
