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>GForge Installation Guide</title>
17 <title>Hardware Requirements</title>
19 Hardware requirements are dependent on the number of users that will use the system and how active those users are.
22 For instance, an installation of GForge hosts over 450 users and over 140 projects on a single CPU Pentium 2.4GHz machine with 512 MB of RAM.
25 You can find additionnal information about hardware used by several installations of GForge in the <ulink url="http://gforge.org/docman/view.php/1/52/gforge-sites.html">GForge sites list maintained by Tom Copeland</ulink>.
29 <title>Software Requirements</title>
31 GForge should work correctly on any system configured like this:
34 <listitem><para>Linux Operating System</para></listitem>
35 <listitem><para><ulink url="http://www.postgresql.org/">PostgreSQL</ulink> 7.3 or later</para></listitem>
36 <listitem><para><ulink url="http://www.apache.org/">Apache</ulink> 1.3.22 or later</para></listitem>
37 <listitem><para><ulink url="http://www.openssl.org/">openssl</ulink> 0.9.4 or later</para></listitem>
38 <listitem><para><ulink url="http://www.openssl.org/">mod_ssl</ulink> 2.4.10 or later (included in Apache 2.0 and later)</para></listitem>
39 <listitem><para><ulink url="http://www.php.net/">PHP</ulink> 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>
40 <listitem><para>php-pgsql (enable it with <literal>--with-pgsql</literal> when building PHP, or install it as package)</para></listitem>
41 <listitem><para>php-mbstring (enable it with <literal>--with-mbstring</literal> when building PHP, or install it as package)</para></listitem>
47 <listitem><para><ulink url="http://turck-mmcache.sourceforge.net">Turck MMCache</ulink> or <ulink url="http://www.php-accelerator.co.uk/">PHP Accelerator</ulink> or any other PHP accelerator (highly recommended)</para></listitem>
48 <listitem><para><ulink url="http://www.gnu.org/software/mailman/">GNU Mailman</ulink> and <ulink url="http://www.python.org/">Python</ulink> (Mailing list support)</para></listitem>
49 <listitem><para><ulink url="http://jabberd.jabberstudio.org/">Jabberd</ulink> (Jabber support)</para></listitem>
50 <listitem><para><ulink url="http://www.aditus.nu/jpgraph/">JPGraph</ulink> (Gantt Charting and Graphing Support)</para></listitem>
51 <listitem><para><ulink url="http://www.perl.org/">Perl</ulink>, <ulink url="http://dbi.perl.org/">DBI module</ulink> and associated <literal>DBD::Pg</literal>.</para></listitem>
54 Successful installations and operations have been done using the following systems:
58 <para>RedHat Enterprise Linux 3 with bundled packages except for a compiled GNU Mailman</para>
61 <para>RedHat Linux 9 with bundled packages except for a compiled GNU Mailman</para>
66 <title>Installation</title>
68 <title>Overview</title>
69 <para>GForge has a lot of different pieces touching a lot of different components in the system. Cronjobs are required to maintain the system, touching lots of files on a daily and hourly basis, including <filename>/etc/*</filename> system files.</para>
70 <para>The plugins that now manage the CVS and SVN functionality have made installation slightly harder because even more files have to be moved into place during installation.</para>
71 <para>The manual installation of GForge is documented below. Be sure to follow each step carefully, check the forums for frequently asked questions, and ask your Apache, Mailman, and PostgreSQL installation questions in the corresponding mailing lists rather than on the GForge forums where little help is available.</para>
74 <title>Installing on Debian</title>
76 You can simply add lines found at <ulink url="http://people.debian.org/~bayle/"/> or <ulink url="http://roland.mas.free.fr/"/> 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.
79 Note that GForge is now part of official Debian, and so you can find it in all debian mirrors all other the planet. From scratch install snapshot are also available for a guided installation.
83 <title>Installing on RPM-based systems</title>
84 <para>Guillaume Smet makes <ulink url="http://people.openwide.fr/~gsmet/gforge/rpm/">RPM packages for installing GForge</ulink>. If you are using Fedora Core or Red Hat Enterprise Linux, you may want to try them.</para>
87 <title>Installing GForge</title>
89 <title>Directory Layout</title>
90 <para>Instructions below assume that gforge is unpacked into <filename class="directory">/var/www/gforge</filename>. There are some other directories where GForge stores files. In this installation guide, they are put in <filename class="directory">/var/www</filename> too.</para>
92 <para>If you want to be <ulink url="http://www.pathname.com/fhs/">FHS</ulink>-compliant, GForge should be unpacked into <filename class="directory">/usr/local/lib/gforge</filename>, and directories for storing files should be in <filename class="directory">/var/local/lib/gforge</filename>.</para>
96 <title>Unpacking</title>
97 <para>To install GForge, follow these steps (as root):</para>
99 # <userinput>bzip2 -dc gforge-4.1.tar.bz2 | tar xvf -</userinput>
100 # <userinput>mv gforge-4.1 /var/www/gforge</userinput>
104 <title>GForge Config File</title>
105 <para>In the GForge distribution, you will find <filename>etc/local.inc</filename>. Copy it to <filename>/etc/gforge/local.inc</filename> and edit all of the settings. In later sections, there is more information about specific configuration settings. Usually, you will want to make it readable only by webserver user (see <xref linkend="web-server"/> for <replaceable>apache-user</replaceable>):</para>
107 # <userinput>mkdir /etc/gforge</userinput>
108 # <userinput>cp /var/www/gforge/etc/local.inc /etc/gforge</userinput>
109 # <userinput>chown -R root: /etc/gforge</userinput>
110 # <userinput>chmod -R 644 /etc/gforge</userinput>
111 # <userinput>chown <replaceable>apache-user</replaceable> /etc/gforge/local.inc</userinput>
112 # <userinput>chmod 600 /etc/gforge/local.inc</userinput>
116 <title>Configuring GForge</title>
118 <listitem><para>Login as <literal>root</literal> user</para></listitem>
120 <para>Create a directory <filename class="directory">/etc/gforge</filename></para>
123 <para>Copy the file <filename>local.inc.example</filename> from <filename class="directory">/var/www/gforge/etc/</filename> to <filename class="directory">/etc/gforge/</filename> </para>
126 <para>Open <filename>/etc/gforge/local.inc</filename>, configuring the following basic parameters:</para>
129 <para>Database configuration:</para>
131 $sys_dbhost="localhost" # some folks suggest setting this to "", your mileage may vary
134 $sys_dbpasswd="gforge"
135 $sys_server="postgres"
139 <para>Change the value of the <varname>$sys_upload_dir</varname> to:</para>
140 <programlisting>$sys_upload_dir='/var/www/download/';</programlisting>
143 <para>Change the value of the <varname>$sys_urlroot</varname> to:</para>
144 <programlisting>$sys_urlroot="/var/www/gforge/www/";</programlisting>
147 <para>The directives <varname>$sys_default_domain</varname> and <varname>$sys_fallback_domain</varname> should contain the domain of your server, e.g. <literal>gforge.org</literal>.</para>
155 <title>Configuring the Database (PostgreSQL)</title>
157 <title>Initialization of PostgreSQL</title>
158 <para>In some distributions, PostgreSQL database cluster is not initialised. Consult distribution documentation for more information. If database cluster is not created, you can do so by running:</para>
160 # <userinput>su - postgres</userinput>
161 $ <userinput>initdb</userinput>
164 <para>This will wipe out any existing PostgreSQL databases!</para>
169 <title>PostgreSQL Authentication Configuration</title>
170 <para>The <literal>postgres</literal> PostgreSQL user is used only during installation. Usually, it can connect via UNIX socket without password when invoked by <literal>postgresql</literal> system account. Check by running this:</para>
172 # <userinput>su - postgres</userinput>
173 $ <userinput>psql template1</userinput>
175 <para>If connection fails, add the following line to <filename>pg_hba.conf</filename>:</para>
177 local all postgres ident sameuser
179 <para>GForge uses <literal>gforge</literal> PostgreSQL user to connect to <literal>gforge</literal> database by using password. (You can change that name by editing <filename>local.inc</filename>.) In order this to work, assure that you have the following line in your <filename>pg_hba.conf</filename>:</para>
181 host gforge gforge 127.0.0.1 255.255.255.255 md5
183 <para>This line assumes that GForge will always use local PostgreSQL database (<literal>localhost</literal>). If this is not the case, consult PostgreSQL manual for ways to allow connection.</para>
184 <para>The following option should be set in <filename>postgresql.conf</filename> because connection to <literal>localhost</literal> uses TCP/IP:</para>
188 <para>After all these changes to PostgreSQL configuration files are made, PostgreSQL should be restarted. This depends on the distribution. In Debian, it's like this:</para>
190 # <userinput>/etc/init.d/postgresql restart</userinput>
194 <title>Importing Database</title>
195 <para>Create GForge database user:</para>
197 # <userinput>su - postgres</userinput>
198 $ <userinput>psql template1</userinput>
199 template1=# <userinput>CREATE USER gforge NOCREATEUSER NOCREATEDB</userinput>
200 template1-# <userinput>PASSWORD '<replaceable>gforge-password</replaceable>';</userinput>
202 <para>Create GForge database:</para>
204 template1=# <userinput>CREATE DATABASE gforge OWNER gforge ENCODING 'UNICODE';</userinput>
206 <para>Add PL/pgSQL support using the commands:</para>
208 # <userinput>su - postgres</userinput>
209 $ <userinput>createlang plpgsql gforge</userinput>
211 <para>Finally, install the database:</para>
213 $ <userinput>cd /var/www/gforge/db</userinput>
214 $ <userinput>psql -a -U gforge gforge -f gforge.sql &> /tmp/gforge.sql.log</userinput>
219 <title>Configuring PHP</title>
220 <para>The cronjobs require PHP CLI or PHP CGI to be installed and the <filename>php.ini</filename> file to be properly configured with your <varname>include_path</varname>. In some systems, one configuration is used for mod_php and PHP CLI (e.g. <filename>/etc/php.ini</filename> in Fedora Core). In others, there are separate configurations (e.g. <filename>/etc/php4/apache/php.ini</filename> and <filename>/etc/php4/cli/php.ini</filename> in Debian). In the latter case, both configuration files should have correct <literal>include_path</literal>. Check what <filename>php.ini</filename> is used by PHP CLI by running <command>php4 -i | fgrep php.ini</command>.</para>
221 <para>In addition, you may have to symlink <filename>/usr/bin/php</filename> to <filename>/usr/bin/php4</filename>, which is where the cronjobs expect your PHP CLI to be located.</para>
224 <para>Verify the version of PHP installed on your system: <command>php -v</command></para>
226 <listitem><para>Open <filename>/etc/php.ini</filename>.</para></listitem>
228 <para>If the PHP version you're using is 4.2.0 or later, enable the <literal>register_globals</literal> variable:</para>
230 register_globals = On
234 <para>Ensure that file uploads are allowed:</para>
240 <para>Add magic quotes to form fields passed to PHP:</para>
242 magic_quotes_gpc = On
246 <para>and configure the <literal>include_path</literal> directive as follows (on one line):</para>
248 include_path=".:/var/www/gforge:/var/www/gforge/www/include:/etc/gforge"
253 <para>If you want to use other applications on the server hosting your GForge, you may be interested in having GForge specific configuration in the GForge vhost directive.</para>
255 <title>gforge.conf vhost configuration</title>
256 <programlisting><![CDATA[
258 DocumentRoot /var/www/gforge/www
259 ServerName gforge.company.com
260 ErrorDocument 404 /404.php
261 php_value include_path ".:/var/www/gforge/:/var/www/gforge/www/include/:/etc/gforge/"
262 php_flag register_globals On
263 php_flag magic_quotes_gpc On
264 php_flag file_uploads On
265 AddDefaultCharset UTF-8
268 ForceType application/x-httpd-php
271 ForceType application/x-httpd-php
278 <para>To run scripts in command line, you need to invoke the PHP interpreter with the <literal>-f</literal> flag, e.g.:</para>
280 # php -f cronjobs/mailing_lists_create.php
284 <section id="web-server">
285 <title>Configuring the Web Server (Apache)</title>
288 <para>Open <filename>/etc/httpd/conf/httpd.conf</filename> or better create a <filename>gforge.conf</filename> file in <filename class="directory">/etc/httpd/conf.d/</filename>. These files and directories may have different names depending on distribution.</para>
289 <para>You may want to copy <filename>etc/gforge-httpd.conf.example</filename> to <filename>/etc/httpd/conf.d/gforge.conf</filename> and edit it, instead of entering manually the examples below.</para>
291 <listitem><para>Create the primary virtual host and fill the rest of the directives in it:</para>
292 <programlisting><![CDATA[
293 NameVirtualHost 192.168.1.1
294 <VirtualHost 192.168.1.1>
295 ServerName gforge.company.com
296 ServerAdmin webmaster@gforge.company.com
298 # Put the rest of the directives here.
304 <para>Change the <literal>DocumentRoot</literal> to point to the <filename class="directory">www</filename> directory:</para>
306 DocumentRoot "/var/www/gforge/www"
310 <para>Create a <literal>Directory</literal> directive following the <literal>DocumentRoot</literal> as follows:</para>
311 <programlisting><![CDATA[
312 <Directory "/var/www/gforge/www">
313 Options Indexes FollowSymLinks
317 ErrorDocument 404 /404.php
321 <listitem><para>If you wish to set up a server with HTTPS, you need to configure the <literal>VirtualHost:443</literal> section of <filename>httpd.conf</filename>.</para></listitem>
323 <para>Add several new filenames to the <literal>DirectoryIndex</literal> directive:</para>
325 DirectoryIndex index.html index.php
329 <para>Configuring PHP for Apache</para>
330 <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>
333 <para>Configuring PHP for Apache 1.3</para>
336 <para>Open <filename>/etc/httpd/conf/httpd.conf</filename> or <filename>/etc/httpd/conf.d/gforge.conf</filename> and put the rest of the directives in the primary virtual host.</para>
339 <para>Insert the following instructions after the <literal>DocumentRoot</literal> directive:</para>
340 <programlisting><![CDATA[
342 ForceType application/x-httpd-php
345 ForceType application/x-httpd-php
348 <para>Ensure the following lines are present and not commented out in <filename>/etc/httpd/conf/httpd.conf</filename>:</para>
350 LoadModule php_module modules/libphp.so
357 <para>Configuring PHP for Apache 2.0</para>
358 <para>For newer versions of Apache 2.0 (RedHat 9 or above), please follow Apache 1.3 instructions above.</para>
361 <para>Open <filename>/etc/httpd/conf.d/php.conf</filename> and put the rest of the directives in the primary virtual host.</para>
364 <para>Change the existing <literal>Files</literal> directive to:</para>
365 <programlisting><![CDATA[
370 LimitRequestBody 2097152
374 The <literal>LimitRequestBody</literal> 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 <literal>upload_max_filesize</literal> directive in <filename>php.ini</filename>.
378 <para>Add the following lines:</para>
379 <programlisting><![CDATA[
398 <para>Restart the Apache server: <command>/etc/init.d/httpd restart</command></para>
402 <title>Project webs</title>
403 <para>Each project can have its own vhost. Module <literal>vhost_alias</literal> should be enabled and the following directives should be added to <filename>httpd.conf</filename>:</para>
404 <programlisting><![CDATA[
406 # WARNING - security is degraded by having this
407 # on the same machine as the primary GForge
409 <VirtualHost 192.168.1.1>
410 ServerName projects.gforge.company.com
411 ServerAlias *.gforge.company.com
412 DocumentRoot /var/www/homedirs/groups
413 VirtualDocumentRoot /var/www/homedirs/groups/%1
414 <Directory /var/www/homedirs/groups>
417 # WARNING - turning on php will allow any user
418 # to upload a php file to your server, and include
419 # the gforge local.inc file and get your password to
420 # connect to the database and have total control.
427 DirectoryIndex index.html index.htm
433 <title>Configuring Mail Transport Agent (Any)</title>
435 Add the following line to <filename>/etc/aliases</filename> and run <command>newaliases</command>:
442 <title>File Release System (FRS)</title>
444 Create a directory (e.g. <filename class="directory">/var/lib/gforge/download</filename>) and make it owned by the webserver user (e.g. <literal>apache</literal>). Usually <command>chown -R apache:apache /var/lib/gforge/download</command> will do the trick. This directory will be referenced in the GForge Config File <filename>/etc/gforge/local.inc</filename> as <varname>$sys_upload_dir</varname>.
448 <title>Configuring GNU Mailman</title>
449 <para>GNU Mailman is used to help manage the GForge mailing lists. Mailman is frequently installed in <filename class="directory">/var/mailman/</filename> and the sample vhost shown below will work with this setup without any changes.</para>
450 <para>Cronjobs for Mailman are located in <filename>cronjobs/mail/*</filename>.</para>
451 <para><filename>cronjobs/mail/mailing_lists_create.php</filename> is used obviously to create new mailing lists. You may have to edit the file to change the location of the mailman <filename class="directory">bin/</filename> directory.</para>
452 <para>For all problems with mailman installation and use, contact the mailman mailing lists for help.</para>
453 <para>To install it:</para>
456 <para>Install a GNU Mailman package or compile it</para>
459 <para><command>su</command> to <literal>root</literal> and set the Mailman password by using the <command>mmsitepass</command> command</para>
462 <para>Create directory <filename class="directory">/var/www/mailman/</filename>.</para>
465 <para>Create in <filename>httpd.conf</filename> virtual host for Mailman, adjusting <literal>ScriptAlias</literal> and <literal>Alias</literal> directives:</para>
466 <programlisting><![CDATA[
467 <VirtualHost 192.168.1.1>
468 ServerName lists.gforge.company.com
469 ServerAdmin mailman@lists.gforge.company.com
470 DocumentRoot /var/www/mailman
471 DirectoryIndex index.php index.cgi index.html index.htm
472 ScriptAlias /mailman/ /var/mailman/cgi-bin/
473 Alias /pipermail/ /var/mailman/archives/public/
478 <para>Run the script <filename>gforge/cronjobs/mail/mailing_lists_create.php</filename> (with <command>php -f</command>). This creates any lists that are already in the database.</para>
483 <title>Cron Jobs</title>
485 Cron jobs are in the <filename class="directory">cronjobs/</filename> directory and the <filename>README</filename> file contains a sample crontab. This gives you the basic cronjobs for updating certain statistics and data on the site.
488 <filename class="directory">cronjobs/cvs-cron/</filename> contains scripts useful for creating blank cvs trees and managing the <filename>/etc/groups</filename>, <filename>/etc/passwd</filename> and <filename>/etc/shadow</filename> files. See <filename>cronjobs/README.root</filename> for more info.
491 <filename class="directory">cronjobs/mail/</filename> contains files useful for the creation of new mailing lists in mailman and creating the <filename>/etc/aliases</filename> file.
495 # cp /etc/aliases /etc/aliases.org
496 # cp /etc/shadow /etc/shadow.org
497 # cp /etc/passwd /etc/passwd.org
498 # cp /etc/group /etc/group.org
502 The following command will blow away any existing root crontab:
506 # crontab cronjobs/crontab.in
508 <para>Now edit the paths to the cron scripts by setting the value of <varname>GFORGE</varname> and <varname>PHP</varname> variables:</para>
514 The <filename>cronjobs/cvs-cron/usergroup.php</filename> cron script will meddle with your <filename>/etc/passwd</filename>, <filename>/etc/group</filename>, and <filename>/etc/shadow</filename> files. By default, this cron will save these files with a <literal>.new</literal> extension. You will have to edit the cron script to remove the <literal>.new</literal> extension, but you must make sure that it is properly generating your files or your server could be unusable.
519 <title>Verifying the Installation</title>
520 <para>To verify if everything was installed correctly, use the browser and connect to GForge. You should see the GForge homepage.</para>
522 <para>If you get an <computeroutput>Error: Could Not Connect to Database</computeroutput>, check if you have followed all installation instructions for the database. Also, you can experiment with making the settings in <filename>pg_hba.conf</filename> a bit more trusting - for example, change the last work of the second line from <literal>md5</literal> to <literal>trust</literal>.</para>
526 <title>Creating the Admin User</title>
527 <para>Site admins are anyone who is an admin of <literal>group_id</literal>=1.</para>
529 <listitem><para>Connect to GForge and register a new account.</para></listitem>
530 <listitem><para>Insert a valid email address; this will be used for the account confirmation.</para></listitem>
531 <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>
533 <para>Verify in Account Maintenance the user id of the user registered.</para>
534 <para>Usually this is 102, but you can verify this by running the following SQL query via the PostgreSQL <command>psql</command> utility:</para>
536 $ psql -U gforge gforge
537 gforge=> SELECT user_id FROM users WHERE user_name='<replaceable>YOUR USER NAME</replaceable>';
541 <para>Now set up the newly added user to be a GForge administrator:</para>
543 gforge=> INSERT INTO user_group (user_id,group_id,admin_flags) VALUES (102,1,'A');
548 <para>Once you have set up this user as an administrator, you can use GForge web interface to add more administrators.</para>
552 <title>Optional Features</title>
554 <title>JPGraph</title>
555 <para>PHP must be compiled with <literal>--with-gd</literal>, or appropriate package must be installed. Extra fonts for JPGraph are not necessary. Be sure your <filename>/etc/gforge/local.inc</filename> file contains the proper path to the <filename class="directory">jpgraph/src/</filename> directory.</para>
556 <para>Manual installation can be done like this:</para>
558 # tar -xzf jpgraph-1.17.tar.gz
559 # mkdir /var/www/jpgraph
560 # mv jpgraph-1.17/src/* /var/www/jpgraph
562 <para>When you get your preferred version of JPGraph installed, you will have to edit one setting in <filename>jpgraph.php</filename>:</para>
564 DEFINE("USE_CACHE", false);
567 <para>Be careful with JPGraph license: versions > 1.5.2 are not free (as in free speech).</para>
572 <para>If you want to use some of the Perl scripts that access the database, you'll need the <literal>DBI</literal> and <literal>DBD::Pg</literal> Perl modules. On Red Hat systems (and variants), you can get them by installing the <literal>libdbi</literal> and <literal>libdbd-pgsql</literal> packages. On Debian systems (and variants), the packages are called <literal>libdbi-perl</literal> and <literal>libdbd-pg-perl</literal>.</para>
573 <para>You'll also need to install <filename>utils/include.pl</filename> to <filename class="directory">/usr/lib/gforge/lib/</filename>, and put some configuration variables into <filename class="directory">/etc/gforge/local.pl</filename>. In particular, you'll need something like the following in <filename>local.pl</filename>:</para>
575 $sys_default_domain = 'gforge.company.com' ;
576 $sys_dbhost = '192.168.12.34' ;
577 $sys_dbname = 'gforge' ;
578 $sys_dbuser = 'gforge' ;
579 $sys_dbpasswd = 'p455w0rd' ;
583 <title>Jabber Support</title>
584 <para>GForge supports the sending of messages to jabber accounts. To accomplish this, you must have a user account setup on the jabber server that gforge can connect to and send messages.</para>
585 <para>Once you have that user account, server, and password set up, just edit <filename>/etc/gforge/local.inc</filename> and add the information to the jabber section.</para>
588 <title>Peer Ratings</title>
589 <para>Add yourself, and any others you wish, to the <quote>Peer Ratings</quote> project, which should be at <literal>/projects/peerrating/</literal> on the website. Make yourself an admininistrator of the project, and then proceed to <quote>rate</quote> other users on the website.</para>
590 <para>Members of the <quote>Peer Ratings</quote> project, who are administrator of the project, become the first trusted users. This is the only way to prime the pump for the peer ratings system.</para>
595 <title>Plugins</title>
597 <para>From GForge 4.0, plugins are necessary as source code management is now provided by plugins (SCM* plugins).</para>
599 <para>For each plugin you can find an <filename>INSTALL</filename> file in the plugin tarball.</para>
603 <title>Overview</title>
604 <para>CVS is now managed via the scmcvs plugin which is included in the <filename class="directory">plugins/</filename> directory in the tarball downloaded from gforge.org. Most of the files in scmcvs are intended for auto-installation on Debian systems and <emphasis role="strong">do not apply</emphasis> to the majority of users. The scmcvs plugin is activated by default in the <filename>gforge.sql</filename> database and all that you have to do is move the <filename>scmcvs/etc/plugins/*</filename> files to <filename>/etc/gforge/plugins/*</filename> and possibly modify the files slightly. In addition, the <filename>scmcvs/www/*</filename> files should be placed in <filename>gforge/www/plugins/scmcvs/*</filename>.</para>
605 <para>Cronjobs for CVS are included in <filename>cronjobs/crontab.in</filename>, but are commented out by default for your security. <filename>cronjobs/cvs-cron/*</filename> contains the files that are executed hourly to build permissions and create blank cvs trees. Make sure these files are executed as root, and have proper execution bits set. Each of these cronjobs has configuration parameters which you may have to edit manually for your specific system.</para>
608 <title>Installation</title>
610 #Create default location for CVS repositories
613 # Optional - Set up basic index.php file for CVS vhost if desired
615 cp /var/www/gforge/cronjobs/cvs-cron/www/* /var/www/cvs/
617 #copy the scmcvs plugin config to /etc/gforge/
618 cp -R /var/www/gforge/plugins/scmcvs/etc/plugins/ /etc/gforge/
620 #make sure the cvs crons are executable
621 cd /var/www/gforge/cronjobs/cvs-cron/
624 <para>You will likely have to edit <filename>/etc/gforge/plugins/scmcvs/cvsweb.conf</filename> to change the cvsroot location:</para>
626 'gforge' => ['GForge-CVS', '/home/chroot/cvsroot/'],
630 <title>Configuring CVS</title>
632 <para>Since GForge 4.0, CVS is integrated by plugin. Look at the plugins section below for more information.</para>
634 <para>GForge uses CVS via <literal>pserver</literal> for anonymous read only access and <literal>ext</literal> for developers to commit to the repositories. To set it up:</para>
635 <para>Download and install the latest CVS package for your distribution.</para>
636 <para>Ensure the following info is in <filename>/etc/services</filename>:</para>
638 $ grep cvspserver /etc/services
639 cvspserver 2401/tcp # CVS client/server operations
640 cvspserver 2401/udp # CVS client/server operations
642 <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>
651 server = /usr/bin/cvs
652 server_args = -f --allow-root=/path/to/my/cvsroot pserver
655 <para>Now add an <literal>anonymous</literal> user to your system with a blank password, or one of <literal>anonymous</literal></para>
658 <title>Configuring CVSWeb</title>
660 <para>Since GForge 4.0, a specific version of CVSWeb is bundled in GForge SCM CVS plugin. You don't need to install CVSWeb anymore.</para>
661 <para>The following instructions are for GForge < 4.0.</para>
664 You can download the latest official CVSWeb release from <ulink url="http://www.freebsd.org/projects/cvsweb.html"/> but you should consider using the one bundled in GForge SCMCVS plugin.
666 <para>Copy the tar.gz file into a tmp directory and unzip it:</para>
668 tar -zxvf cvsweb.tar.gz
670 <para>CVSWeb consists of a Perl script (<filename>cvsweb.cgi</filename>), a configuration file (<filename>cvsweb.conf</filename>), and some icons (<filename>back.gif</filename>, <filename>dir.gif</filename>, etc).</para>
672 <listitem><para>Copy the <filename>cvsweb.cgi</filename> script into Apache's <filename class="directory">cgi-bin</filename> directory</para></listitem>
673 <listitem><para>Copy the <filename>cvsweb.conf</filename> file into Apache's configuration directory (such as <filename class="directory">/etc/httpd/conf.d/</filename> on RedHat 9)</para></listitem>
674 <listitem><para>Edit <filename>cvsweb.conf</filename></para></listitem>
675 <listitem><para>Change <varname>%CVSROOT</varname> hash to include your repositories - note you'll need to have created a repository first, of course.</para></listitem>
676 <listitem><para>Change the <varname>$cvstreedefault</varname> variable to point to a default repository</para></listitem>
677 <listitem><para>With GForge specific CVSWeb, you don't need to add manually projects' repositories.</para></listitem>
678 <listitem><para>Edit <filename>cvsweb.cgi</filename></para></listitem>
679 <listitem><para>Change the <varname>$config</varname> variable to point the <filename>cvsweb.conf</filename> file</para></listitem>
680 <listitem><para>Change the <varname>$PATH</varname> variable in <filename>cvsweb.conf</filename> to point to the directory that contains <command>rlog</command></para></listitem>
682 <para>Possible problems:</para>
685 <para><computeroutput>Error: Configuration not found</computeroutput> - edit <filename>cvsweb.cgi</filename> and point <varname>$config</varname> to the <filename>cvsweb.conf</filename> file</para>
688 <para><computeroutput>Error: Failed to spawn GNU rlog</computeroutput> - ensure <command>rlog</command> is in the directory pointed to by <varname>$ENV{'PATH'}</varname></para>
691 <para>Create in <filename>httpd.conf</filename> virtual host for viewing of CVSWeb:</para>
692 <programlisting><![CDATA[
693 <VirtualHost 192.168.1.1>
694 ServerName cvs.gforge.company.com
695 ServerAdmin webmaster@cvs.gforge.company.com
696 DocumentRoot /var/www/cvs
697 DirectoryIndex index.php cvsweb.cgi index.html index.htm
705 <title>Overview</title>
706 <para>SVN is also managed via plugin – the scmsvn plugin is included and activated by default in GForge. As with scmcvs, you have to move the <filename>scmcvs/etc/plugins/*</filename> files to <filename>/etc/gforge/plugins/*</filename> and may have to make minor modifications for your specific setup.</para>
707 <para>There are two ways to manage SVN – one is to have SVN over DAV and the other is to have SVN over SSH just as you do with CVS. If you choose to use DAV, you will need the <filename class="libraryfile">mod_auth_gforge</filename> library compiled and installed in your apache and the appropriate virtual host settings in your <filename>httpd.conf</filename>. <filename class="libraryfile">mod_auth_gforge</filename> is available from gforge.org. The cronjobs to manage SVN are in <filename class="directory">cronjobs/dav-svn/</filename> and so are sample <filename>httpd.conf</filename> virtual host settings. Each of these cronjobs has configuration parameters which you may have to edit manually for your specific system.</para>
708 <para>Configuring svnserv for svn-over-ssh:
711 <para><ulink url="http://svnbook.red-bean.com/en/1.0/ch06s03.html" /></para>
714 <para><ulink url="http://www.logemann.org/day/archives/000099.html" /></para>
717 <para><ulink url="http://bitworking.org/news/Getting_subversion_svn_ssh____to_work_with_PuTTY" /></para>
723 <title>Installation</title>
725 #Create default location for SVN repositories
728 # Optional - Set up some basic files for SVN-over-DAV only
730 cp /var/www/gforge/cronjobs/dav-svn/www/* /var/www/svn/
732 #copy the scmsvn config files to /etc/gforge/
733 cp -R gforge/plugins/scmsvn/etc/plugins/scmsvn/ /etc/gforge/plugins/
738 <title>CVSTracker Overview</title>
739 <para>The cvstracker plugin allows for some integration between CVS commits and the bug tracker and task manager. So, for example, when you commit, you can reference bug and task IDs in your commit message and have the commit linked to the corresponding bug and task.</para>
740 <para>See the <filename>plugins/cvstracker/README</filename> file for details. This plugin is enabled by default in the <filename>gforge.sql</filename> database file. As with the other plugins, you may manually place the config files in <filename class="directory">/etc/gforge/plugins/cvstracker/</filename> and uncomment the cronjob in <filename>crontab.in</filename>.</para>
741 <para>You will also have to copy the <filename>newcommit.php</filename> file to your gforge <filename class="directory">www/plugins/cvstracker/</filename> dir</para>
744 <title>Installation</title>
746 #copy the cvstracker config files to /etc/gforge/
747 cd /var/www/gforge/plugins/cvstracker/
748 cp -R etc/plugins/cvstracker/ /etc/gforge/plugins/
749 cp -R www/ /var/www/gforge/www/plugins/cvstracker/
754 <title>Upgrading Existing Install</title>
755 <para>You will upgrade your database from a prior version by applying each database schema change, in order, and applying it only once. Only apply the schema changes in the <filename class="directory">db/</filename> folder that are dated <emphasis>after</emphasis> your existing installation.</para>
756 <para>There may also be migration scripts that have to be run. In the <filename class="directory">db/</filename> folder, look for php scripts and run them.</para>
758 <para>You have to apply database schema changes and to run migration scripts in the right order.</para>
762 <title>Most Common Problems</title>
763 <para>Q: I get a blank page when I visit http://gforge.company.com/</para>
764 <para>A: Most often you are missing the php-pgsql library that lets PHP talk to the postgres database. Find a php-pgsql RPM or recompile php to have pgql support.</para>
765 <para>If you're sure you have php-pgsql support, you can edit common/include/database.php and remove the @ symbol from this line:</para>
769 <para>So that it looks like:</para>
773 <para>This will let debug output dump to the screen and may let you find the problem. Search the forums for more solutions.</para>
775 <para>Q: <quote>Error Occurred In the Logger</quote> or other database permission problems</para>
776 <para>A: As stated in the installation instructions, the database must be created, owned, and accessed by the gforge user. This user is the only one who will have total acess to all the tables. Any other user would have to be specifically granted permissions with the GRANT commands in postgres.</para>
778 <para>Q: Reporting or time tracking doesn't work</para>
780 <para>A: Go to the reporting tab and scroll down so you can choose <quote>Initialize/Rebuild Reporting Tables</quote></para>
782 <para>You may also be missing GD support or be missing JPGraph or have it installed improperly. The <filename class="directory">jpgraph/src/</filename> directory should be specified accurately in your <filename class="directory">local.inc</filename> file, and you should include a <filename>/</filename> at the end of the path specified. In addition, you should modify <filename>jpgraph.php</filename> to set <literal>USE_CACHE=false</literal>.</para>
784 <para>Q: How do I upgrade my database?</para>
785 <para>A: As stated above, you must apply the changes that are listed in date order in the <filename class="directory">db/</filename> directory to your database. Only the changes that are not already in your old <filename class="directory">db/</filename> directory should be applied, and they should be applied and checked <emphasis>in order</emphasis>.</para>
787 <para>Q: I'm getting an error about BaseLanguage.class not being found.</para>
788 <para>A: Make sure your localization path is correctly specified in the local.inc file and that it is readable <emphasis>and</emphasis> writable by the apache user.</para>
790 <para>Q: When I click on <quote>/projects/</quote> or <quote>/users/</quote> links, I get the source code instead of the page I expected.</para>
791 <para>A: As shown in the example <filename>httpd.conf</filename> files above, you may have to switch to using the <literal><Files></literal> or <literal><Location></literal> directives depending on your server version.</para>
793 <para>Q: How do I backup GForge?</para>
794 <para>A: The only proper way to backup the gforge database is with <command>pg_dump</command>. Any attempt to backup the filesystem while pgsql is running will result in a useless and corrupt backup. You can backup CVS trees using <command>tar</command> as long as they are not actively and heavily used during the backup. Mailman and the FRS uploads dir can also be backed up with <command>tar</command>.</para>
796 <para>Q: Any time i enter an apostrophe in a text box, i get a parse error</para>
797 <para>A: As stated in the instructions above, you should have <literal>magic_quotes_gpc=On</literal> in your <filename>php.ini</filename> file.</para>
799 <para>Q: Large uploads into FRS or the doc manager fail.</para>
800 <para>A: Apache and the <filename>php.ini</filename> file need to have upload limits and possibly memory limits increased.</para>