1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "../../../dtd/docbookx.dtd" [
3 <!ENTITY % authors SYSTEM "../entities/authors.ent">
6 <article lang="en-US" id="installation_guide">
8 <title>Installation Guide</title>
15 <title>Hardware requirements</title>
17 Hardware requirements are dependent on the number of users that will use the system and how active those users are. One installation of GForge hosts over 450 users and over 140 projects on a single CPU Pentium 2.4GHz machine with 512 MB of RAM.
21 <title>Software requirements</title>
23 GForge should work correctly on any system configured like this:
26 <listitem><para>Linux Operating System</para></listitem>
27 <listitem><para>Postgres 7.1 or later</para></listitem>
28 <listitem><para>Apache 1.3.22 or later</para></listitem>
29 <listitem><para>openssl >0.9.4</para></listitem>
30 <listitem><para>mod_ssl >2.4.10</para></listitem>
31 <listitem><para>PHP 4.0.4 or later - note that you'll need to have PHP built with the command line interface support, which only comes standard with PHP 4.3 or later</para></listitem>
32 <listitem><para>php-pgsql 4.0.4</para></listitem>
35 Successful installations and operations have been done using the following systems:
38 RedHat Linux 8.0 with the following software configured (already bundled with RH8):
41 <listitem><para>Postgres 7.2.2</para></listitem>
42 <listitem><para>Apache 2.0.40</para></listitem>
43 <listitem><para>openssl 0.9.6b</para></listitem>
44 <listitem><para>mod_ssl 2.0.40</para></listitem>
45 <listitem><para>PHP 4.2.2</para></listitem>
46 <listitem><para>php-pgsql 4.2.2</para></listitem>
52 <listitem><para>Postgres 7.2-1</para></listitem>
53 <listitem><para>Apache 1.3.27</para></listitem>
54 <listitem><para>openssl 0.9.6b</para></listitem>
55 <listitem><para>mod_ssl 2.0.40</para></listitem>
56 <listitem><para>PHP 4.1.2</para></listitem>
57 <listitem><para>php-pgsql 4.1.2</para></listitem>
61 <title>Installation</title>
63 <title>Installing the software</title>
65 <title>Note for Debian users</title>
67 You can simply add lines found at <ulink url="http://people.debian.org/~bayle/">http://people.debian.org/~bayle/</ulink> or <ulink url="http://people.debian.org/~lolando/">http://people.debian.org/~lolando/</ulink> to <filename>/etc/apt/sources.list</filename> and type <command>apt-get install gforge</command> to install a working GForge system, thanks to Christian Bayle and Roland Mas.
70 Note that Gforge is now part of official Debian, and so you can find it in all debian mirrors all other the planet. From scrach install snapshot are also available for a guided installation.
74 To install GForge, follow these steps:
77 <listitem><para>Login as root user</para></listitem>
78 <listitem><para>cd to <filename>/var/www/</filename></para></listitem>
79 <listitem><para>Extract the content of gforge-3.21.tar.bz2 to the current directory:
81 bzip2 -dc gforge-3.21.tar.bz2 | tar xvf -
87 <title>Configuring the Web Server</title>
89 <listitem><para>Open <filename>/etc/httpd/conf/httpd.conf</filename>:</para></listitem>
91 <para>Change the DocumentRoot to point to the <filename>www</filename> directory:</para>
93 DocumentRoot "/var/www/gforge-3.21/www"
97 <para>Change the Directory directive following the DocumentRoot as follows:</para>
98 <programlisting><![CDATA[
99 <Directory "/var/www/gforge-3.21/www">
100 Options Indexes FollowSymLinks
104 ErrorDocument 404 /404.php
108 <listitem><para>Change the ScriptAlias to <filename>/var/www/gforge-3.21/cgi-bin</filename></para></listitem>
110 <para>Change the Directory configuration following the ScriptAlias directive as follows:</para>
111 <programlisting><![CDATA[
112 <Directory "/var/www/gforge-3.21/cgi-bin">
120 <listitem><para>If you wish to set up a server with HTTPS, you need to configure the VirtualHost:443 section of <filename>httpd.conf</filename>.</para></listitem>
122 <para>Add several new filenames to the DirectoryIndex directive:</para>
124 DirectoryIndex index.html index.shtml index.cgi index.php
128 <para>Configuring PHP for Apache</para>
129 <para>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.</para>
132 <para>Configuring PHP for Apache 1.3</para>
135 <para>Open <filename>/etc/httpd/conf/httpd.conf</filename></para>
138 <para>Insert the following instructions after the DocumentRoot directive:</para>
139 <programlisting><![CDATA[
141 ForceType application/x-httpd-php
144 ForceType application/x-httpd-php
147 <para>Ensure the following lines are present and not commented out:</para>
149 LoadModule php_module modules/libphp.so
156 <para>Configuring PHP for Apache 2.0</para>
159 <para>Open <filename>/etc/httpd/conf.d/php.conf</filename></para>
162 <para>Change the existing Files directive to:</para>
163 <programlisting><![CDATA[
168 LimitRequestBody 2097152
172 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.
176 <para>Add the following lines:</para>
177 <programlisting><![CDATA[
196 <para>Restart the Apache server: <command>/etc/init.d/httpd restart</command></para>
201 <title>Configuring the database</title>
204 <para>Configuring PostgreSQL</para>
205 <para>Check to see if your PostgreSQL installation accepts connections on TCP/IP sockets. On RedHat 8.0, this is by default disabled. To verify this, type the following command:</para>
207 $ psql -h localhost template1
209 <para>If you get an error like this:</para>
211 psql: could not connect to server: Connection refused
212 Is the server running on host localhost and accepting
213 TCP/IP connections on port 5432?
215 <para>you need to add the -i option to the pg_ctl command so that the result is:</para>
219 su -l postgres -s /bin/sh -c "/usr/bin/pg_ctl -o -i -D $PGDATA -p /usr/bin/postmaster start > /dev/null 2>&1" < /dev/null
222 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: <command>su - postgres</command>
224 <para>Open <filename>/var/lib/pgsql/data/pg_hba.conf</filename> and insert the following lines:</para>
226 For PostgreSQL 7.3 (note that you can figure out your Postgres version by opening <filename>/etc/init.d/postgresql</filename> and looking for the string PG_VERSION=):
230 host all all 127.0.0.1 255.255.255.255 crypt
232 <para>For PostgreSQL 7.2:</para>
235 host all 127.0.0.1 255.255.255.255 crypt
237 <para>and comment out all other directives.</para>
238 <para>Restart the PostgreSQL server as root user:</para>
239 <screen>/etc/init.d/postgresql restart</screen>
240 <para>Now, initialize the database (if you haven't done so already):</para>
245 <para>Create the database user:</para>
250 <para>Answer the following two questions:</para>
252 Shall the new user be allowed to create databases? (y/n) y
253 Shall the new user be allowed to create more new users? (y/n) n
255 <para>and insert a password (most people use 'gforge') for the user to be created.</para>
256 <para>Create the database using the command:</para>
258 createdb -U gforge gforge
262 <para>Installing the database</para>
263 <para>Now it's time to install the database. The steps are:</para>
266 <para>cd to <filename>/var/www/gforge-3.21/db</filename></para>
270 psql -a -U gforge gforge < gforge3.sql > /tmp/gforge.sql.log 2>&1
275 <title>Mandrake 9-specific installation notes (thanks to Francois Elie)</title>
278 <para>Edit /var/lib/pgsql/data/postgresql.conf:</para>
280 set tcpip_socket=true
285 <para>Edit /var/lib/pgsql/data/pg_hba.conf:</para>
286 <para>Set for example access right to</para>
287 <programlisting>host all 0.0.0.0 0.0.0.0 md5</programlisting>
293 <para>Then restart the server <command>/etc/rc.d/init.d/postgresql restart</command></para>
298 <title>Configuring PHP</title>
300 Verify the version of PHP installed on your system: <command>php -v</command>
303 <listitem><para>open <filename>/etc/php.ini</filename></para></listitem>
305 <para>if the PHP version you're using is 4.2.0 or later, enable the register_globals variable:</para>
307 register_globals = On
311 <para>Ensure that file uploads are allowed:</para>
317 <para>and configure the include_path directive as follows:</para>
319 include_path=".:/var/www/gforge-3.21/:/var/www/gforge-3.21/common/include:
320 /var/www/gforge-3.21/www/include:/var/www/gforge-3.21/etc/"
326 <title>Configuring cvsweb</title>
328 First download the latest cvsweb release - 1.112 - from <ulink url="http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/">http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/</ulink>
330 <para>Copy the tar.gz file into a tmp directory and unzip it:</para>
332 tar -zxvf cvsweb-1.112.tar.gz
334 <para>cvsweb consists of a Perl script (cvsweb.cgi), a configuration file (cvsweb.conf), and some icons (back.gif, dir.gif, etc).</para>
336 <listitem><para>Copy the cvsweb.cgi script into Apache's cgi-bin directory</para></listitem>
337 <listitem><para>Copy the cvsweb.conf file into Apache's configuration directory (such as /etc/httpd/conf.d/ on RedHat 9)</para></listitem>
338 <listitem><para>Edit cvsweb.conf</para></listitem>
339 <listitem><para>change %CVSROOT hash to include your repositories - note you'll need to have created a repository first, of course</para></listitem>
340 <listitem><para>change the $cvstreedefault variable to point to a default repository</para></listitem>
341 <listitem><para>TODO: can we add the repositories automatically? Or should we tweak cvsweb.cgi?</para></listitem>
342 <listitem><para>TODO: should we tweak cvsweb.cgi so it doesn't have a default repository?</para></listitem>
343 <listitem><para>Edit cvsweb.cgi</para></listitem>
344 <listitem><para>Change the $config variable to point the cvsweb.conf file</para></listitem>
345 <listitem><para>Change the $PATH variable in <filename>cvsweb.conf</filename> to point to the directory that contains rlog</para></listitem>
347 <para>Possible problems:</para>
350 <para><errortext>Error: Configuration not found</errortext> - edit cvsweb.cgi and point $config to the cvsweb.conf file</para>
353 <para><errortext>Error: Failed to spawn GNU rlog</errortext> - ensure rlog is in the directory pointed to by ENV{'PATH'}</para>
358 <title>Configuring GForge</title>
360 <listitem><para>login as root user</para></listitem>
362 <para>create a directory gforge3-files:</para>
363 <screen>mkdir /var/www/gforge3-files</screen>
364 <para>Make this directory writeable by Apache</para>
365 <screen>chown -R apache.apache /var/www/gforge3-files</screen>
366 <para>This directory will contain all files/patches uploaded to your gforge site.</para>
369 <para>Create a directory<filename> /etc/gforge</filename></para>
372 <para>Copy the file <filename>local.inc</filename> from <filename>/var/www/gforge-3.21/etc/</filename> to <filename>/etc/gforge/</filename> </para>
375 <para>Open <filename>/etc/gforge/local.inc</filename>, configuring the following basic parameters:</para>
378 <para>Database configuration:</para>
380 $sys_dbhost="localhost" # some folks suggest setting this to "", your mileage may vary
383 $sys_dbpasswd="gforge"
384 $sys_server="postgres"
388 <para>Change the value of the $sys_upload_dir to:</para>
389 <programlisting>$sys_upload_dir='/var/www/gforge3-files/';</programlisting>
392 <para>Change the value of the $sys_urlroot to:</para>
393 <programlisting>$sys_urlroot="/var/www/gforge-3.21/www/";</programlisting>
396 <para>The directives <varname>$sys_default_domain</varname> and <varname>$sys_fallback_domain</varname>should contain the domain of your server, e.g. gforge.org.</para>
401 <para>Restart Apache: <command>/etc/init.d/httpd restart</command></para>
406 <title>Configuring GNU Mailman</title>
407 <para>GNU Mailman is used to help manage the GForge mailing lists. To install it:</para>
408 <para>Install the 2.0.13 RPM (TODO add compilation instructions)</para>
409 <para>su to root and set the mailman password</para>
410 <para>Add the following to the httpd.conf</para>
412 Alias /pipermail/ /usr/local/mailman/archives/public/
413 ScriptAlias /mailman/ "/usr/local/mailman/cgi-bin/"
415 <para>Run the script <command>gforge-3.21/cronjobs/mail/mailing_lists_create.php</command>; this creates any lists that are already in the database. Note that to run the script you need to invoke the PHP interpreter with the <filename>-f</filename> flag, i.e.:</para>
417 php -f mailing_lists_create.php
421 <title>Configuring CVS</title>
422 <para>GForge uses CVS via pserver for anonymous read only access and ext for developers to commit to the repositories. To set it up:</para>
423 <para>Download and install the latest CVS RPM</para>
424 <para>Ensure the following info is in <filename>/etc/services</filename>:</para>
426 [tom@cougaar tom]$ cat /etc/services | grep cvspserver
427 cvspserver 2401/tcp # CVS client/server operations
428 cvspserver 2401/udp # CVS client/server operations
431 <para>Ensure the following info is in <filename>/etc/xinetd.d/cvspserver</filename> (if it doesn't exist create a new file with the following text to enable anonymous access):</para>
440 server = /usr/bin/cvs
441 server_args = -f --allow-root=/path/to/my/cvsroot pserver
444 <para>Now add an <filename>anonymous</filename> user to your system with a blank password, or one of <filename>anonymous</filename></para>
445 <para>TODO - does the CVSROOT/readers file get added via a cronjob or something?</para>
446 <para>TODO - any extra notes on setting up dev access? i.e., uploading of public key and such?</para>
450 <title>Verifying the installation</title>
452 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: <errortext> Could Not Connect to Database:</errortext>, check if you have followed all installation instructions for the database. Also, you can experiment with making the settings in pg_hba.conf a bit more trusting - for example, change the last work of the second line from "md5" to "trust".
457 <title>Creating the admin user</title>
459 Connect to GForge and register a new account.
462 <listitem><para>Insert a valid email address; this will be used for the account confirmation.</para></listitem>
463 <listitem><para>Open your e-mail client, wait for the email from GForge site and follow the link that appears on the message.</para></listitem>
465 <para>Verify in Account Maintenance the user id of the user registered.</para>
466 <para>Usually this is 102, but you can verify this by running the following SQL query via the Postgres <command>psql</command> utility:</para>
468 psql -c "select user_id from users where user_name='***YOUR USER NAME***'" gforge gforge
472 <para>Now set up the newly added user to be a GForge administrator</para>
474 psql -U gforge -d gforge
475 insert into user_group (user_id,group_id,admin_flags) values (102,1,'A');