</authorgroup>
</articleinfo>
<section>
- <title>Hardware requirements</title>
+ <title>Hardware Requirements</title>
<para>
Hardware requirements are dependent on the number of users that will use the system and how active those users are.
</para>
</para>
</section>
<section>
- <title>Software requirements</title>
+ <title>Software Requirements</title>
<para>
GForge should work correctly on any system configured like this:
</para>
<orderedlist>
<listitem><para>Linux Operating System</para></listitem>
- <listitem><para><ulink url="http://www.postgresql.org/">PostgreSQL</ulink> 7.1 or later</para></listitem>
- <listitem><para><ulink url="http://www.apache.org/">Apache</ulink> 1.3.22 or later</para></listitem>
+ <listitem><para><ulink url="http://www.postgresql.org/">PostgreSQL</ulink> 8.3 or later (8.1, 8.2 should work)</para></listitem>
+ <listitem><para><ulink url="http://www.apache.org/">Apache</ulink> 2.2 or later</para></listitem>
<listitem><para><ulink url="http://www.openssl.org/">openssl</ulink> 0.9.4 or later</para></listitem>
<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>
- <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>
+ <listitem><para><ulink url="http://www.php.net/">PHP</ulink> 5.2 or later (php4 with the command line interface support and php5.1 should work)</para></listitem>
<listitem><para>php-pgsql (enable it with <literal>--with-pgsql</literal> when building PHP, or install it as package)</para></listitem>
<listitem><para>php-mbstring (enable it with <literal>--with-mbstring</literal> when building PHP, or install it as package)</para></listitem>
</orderedlist>
</para>
<itemizedlist>
<listitem>
- <para>RedHat Enterprise Linux 3 with bundled packages except for a compiled GNU Mailman</para>
- </listitem>
- <listitem>
- <para>RedHat Linux 9 with bundled packages except for a compiled GNU Mailman</para>
+ <para>Debian GNU/Linux 3.1 (Sarge)</para>
</listitem>
<listitem>
- <para>RedHat Linux 8.0 with the following software configured (already bundled with RH8):</para>
- <orderedlist>
- <listitem><para>PostgreSQL 7.2.2</para></listitem>
- <listitem><para>Apache 2.0.40</para></listitem>
- <listitem><para>openssl 0.9.6b</para></listitem>
- <listitem><para>mod_ssl 2.0.40</para></listitem>
- <listitem><para>PHP 4.2.2</para></listitem>
- <listitem><para>php-pgsql 4.2.2</para></listitem>
- </orderedlist>
+ <para>RedHat Enterprise Linux 3 with bundled packages except for a compiled GNU Mailman</para>
</listitem>
<listitem>
- <para>RedHat Linux 7.3:</para>
- <orderedlist>
- <listitem><para>PostgreSQL 7.2-1</para></listitem>
- <listitem><para>Apache 1.3.27</para></listitem>
- <listitem><para>openssl 0.9.6b</para></listitem>
- <listitem><para>mod_ssl 2.0.40</para></listitem>
- <listitem><para>PHP 4.1.2</para></listitem>
- <listitem><para>php-pgsql 4.1.2</para></listitem>
- </orderedlist>
+ <para>RedHat Linux 9 with bundled packages except for a compiled GNU Mailman</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Installation</title>
<section>
- <title>Installing the software</title>
+ <title>Overview</title>
+ <important>
+ <para>The <filename>INSTALL</filename> file in GForge package and <filename>README</filename> files in plugin directories are the authoritive sources for installation instructions and they should have more precedence over this guide.</para>
+ </important>
<note>
- <title>Note for Debian users</title>
- <para>
- You can simply add lines found at <ulink url="http://people.debian.org/~bayle/"/> or <ulink url="http://people.debian.org/~lolando/"/> 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.
- </para>
- <para>
- 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.
- </para>
+ <para>This installation guide is for GForge 4.7.</para>
</note>
+ <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>
+ <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>
+ <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>
+ </section>
+ <section>
+ <title>Installing Gforge on Debian</title>
<para>
- To install GForge, follow these steps:
+ 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.
</para>
- <orderedlist>
- <listitem><para>Login as <literal>root</literal> user</para></listitem>
- <listitem><para>cd to <filename class="directory">/usr/share/</filename></para></listitem>
- <listitem><para>Extract the content of the GForge tarball to the current directory:
- <command>
- bzip2 -dc gforge.tar.bz2 | tar xvf -
- </command></para>
- </listitem>
- </orderedlist>
+ <para>
+ Note that GForge is now part of official Debian, and so you can find it in all debian mirrors all other the planet. Package versions of GForge may lag behind upstream versions. From scratch install snapshot are also available for a guided installation.
+ </para>
+ </section>
+ <section>
+ <title>Installing Gforge on RPM-based systems</title>
+ <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>
</section>
<section>
- <title>Configuring the Web Server</title>
+ <title>Installing GForge oneself on a linux distribution</title>
+ <para>To install GForge, follow these steps (as root):</para>
+ <section>
+ <title>Directory Layout</title>
+ <para>Instructions below assume that gforge is unpacked into <filename class="directory"><replaceable>/opt/gforge</replaceable></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>
+ <note>
+ <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/share/gforge</filename>, and directories for storing files should be in <filename class="directory">/var/lib/gforge</filename> or <filename class="directory">/var/local/gforge</filename>. You may use symbolic links to physically place files in FHS-compliant places and still use directory paths that are presented in this manual.</para>
+ </note>
+ </section>
+ <section>
+ <title>Getting the source</title>
+ <para>There is two ways to get the sources from Gforge : </para>
+ <section>
+ <title>With the tarball available on https://gforge.org/frs/?group_id=1</title>
+ <para>Unpacking : </para>
+ <screen>
+ # <userinput>tar -xjvf gforge-4.7-svn6744.tar.bz2</userinput>
+ # <userinput>cd gforge-4.7-svn6744</userinput>
+ # <userinput>mkdir -p /opt/gforge</userinput>
+ # <userinput>cp -r *<replaceable>/opt/gforge</replaceable></userinput>
+ </screen>
+ </section>
+ <section>
+ <title>Checking out from the SVN repository with tag v4_7 </title>
+ <para>Alternative way to get GForge 4.7 is to check out with tag v4_7 from SVN. This gets latest fixes as well.</para>
+ <screen>
+ $ <userinput>svn checkout --username anonsvn https://svn.gforge.org/svn/gforge/tags/v4_7</userinput>
+
+ $ <userinput>cd gforge/www/plugins</userinput>
+ $ <userinput>ln -s ../../plugins/scmcvs/www scmcvs</userinput>
+ $ <userinput>ln -s ../../plugins/scmsvn/www scmsvn</userinput>
+ $ <userinput>ln -s ../../plugins/cvstracker/www cvstracker</userinput>
+ </screen>
+ <section>
+ <title>Updating checked out Branch_4_5</title>
+ <para>To get latest updates in <literal>Branch_4_5</literal>, run the following commands:</para>
+ <screen>
+ $ <userinput>cd gforge</userinput>
+ $ <userinput>svn -q update</userinput>
+ </screen>
+ <para>To monitor latest changes in GForge, subscribe to <ulink url="http://lists.gforge.org/mailman/listinfo/gforge-commits">gforge-commits mailing list</ulink>.</para>
+ </section>
+ </section>
+ </section>
+ <section>
+ <title>Fixing access rights</title>
+ <para>You may want to make sure that permissions are correct (replace <replaceable>apache-group</replaceable> with the system group used by Apache server):</para>
+ <screen>
+# <userinput>cd /opt/gforge</userinput>
+# <userinput>chown -R root:<replaceable>apache-group</replaceable> .</userinput>
+# <userinput>chmod -R 644 .</userinput>
+# <userinput>find -type d | xargs chmod 755</userinput>
+# <userinput>chmod -R 755 cronjobs</userinput>
+ </screen>
+ </section>
+ <section>
+ <title>GForge Config File</title>
+ <para>In the GForge distribution, you will find <filename>etc/local.inc.example</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> and <replaceable>apache-group</replaceable>):</para>
+<programlisting>
+# <userinput>mkdir /etc/gforge</userinput>
+# <userinput>chown root: /etc/gforge</userinput>
+# <userinput>chmod 755 /etc/gforge</userinput>
+# <userinput>cp <replaceable>/opt/gforge</replaceable>/etc/local.inc.example /etc/gforge/local.inc</userinput>
+# <userinput>chown <replaceable>apache-user</replaceable>:<replaceable>apache-group</replaceable> /etc/gforge/local.inc</userinput>
+# <userinput>chmod 600 /etc/gforge/local.inc</userinput>
+</programlisting>
+ </section>
+ <section>
+ <title>Configuring GForge</title>
+ <para>Open <filename>/etc/gforge/local.inc</filename>, configuring the following basic parameters:</para>
+ <orderedlist>
+ <listitem>
+ <para>Database configuration:</para>
+<programlisting>
+$sys_dbhost="localhost"
+$sys_dbname="gforge"
+$sys_dbuser="gforge"
+$sys_dbpasswd="<replaceable>gforge-password</replaceable>"
+</programlisting>
+ </listitem>
+ <!--<listitem>
+ <para>Change the following basic variables::</para>
+<programlisting>
+$sys_urlroot="<replaceable>/var/www/gforge</replaceable>/www/";
+$sys_themeroot="<replaceable>/var/www/gforge</replaceable>/www/themes/";
+$sys_plugins_path="<replaceable>/var/www/gforge</replaceable>/plugins/";
+</programlisting>
+ </listitem>-->
+ <listitem>
+ <para>The directive <varname>$sys_default_domain</varname> should contain the domain of your server, e.g. <literal>gforge.<replaceable>company.com</replaceable></literal>. You may want to replace all occurences of <replaceable>company.com</replaceable> with company's domain name.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+ <section>
+ <title>Configuring the Database (PostgreSQL)</title>
+ <section>
+ <title>PostgreSQL Requirements</title>
+ <para>You to have installed the following packages for </para>
+ <orderedlist>
+ <listitem>a CentOS or Red Hat 5 or Fedora: postgresql, postgresql-libs, postgresql-server, postgresql-contrib</listitem>
+ <listitem>a Debian: postgresql, postgresql-contrib</listitem>
+ <listitem>a Red Hat 4 : postgresql, postgresql-contrib</listitem>
+ </orderedlist>
+
+ </section>
+ <section>
+ <title>Initialization of PostgreSQL</title>
+ <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>
+<screen>
+# <userinput>su - postgres</userinput>
+$ <userinput>initdb</userinput>
+</screen>
+ <caution>
+ <para>This will wipe out any existing PostgreSQL databases!</para>
+ </caution>
+ </section>
+
+ <section>
+ <title>PostgreSQL Authentication Configuration</title>
+ <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>
+<screen>
+# <userinput>/etc/init.d/postgresql restart</userinput>
+# <userinput>su - postgres</userinput>
+$ <userinput>psql template1</userinput>
+</screen>
+ <para>If connection fails, add the following line to <filename>pg_hba.conf</filename>:</para>
+<screen>
+local all postgres ident sameuser
+</screen>
+<para>If you went just to install postgresql on your server be sure that there is only this line in your <filename>pg_hba.conf</filename> (comment the others)</para>
+<screen>local all all ident sameuser</screen>
+ <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> (before other <literal>host</literal> directives):</para>
+<screen>
+host gforge gforge 127.0.0.1 255.255.255.255 md5
+</screen>
+ <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>
+
+ <!-- <para>The following option should be set in <filename>postgresql.conf</filename> because connection to <literal>localhost</literal> uses TCP/IP:</para>
+<screen>
+tcpip_socket = true
+</screen>-->
+ <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>
+<screen>
+# <userinput>/etc/init.d/postgresql restart</userinput>
+</screen>
+ </section>
+ <section>
+ <title>Importing Database</title>
+ <para>Create GForge database user:</para>
+<screen>
+# <userinput>su - postgres</userinput>
+$ <userinput>psql template1</userinput>
+template1=# <userinput>CREATE USER gforge NOCREATEUSER NOCREATEDB</userinput>
+template1-# <userinput>PASSWORD '<replaceable>gforge-password</replaceable>';</userinput>
+</screen>
+ <para>Create GForge database:</para>
+<screen>
+template1=# <userinput>CREATE DATABASE gforge OWNER gforge ENCODING 'UNICODE';</userinput>
+template1=# <userinput>\q</userinput>
+</screen>
+ <para>Add PL/pgSQL support using the commands:</para>
+<screen>
+<!-- # <userinput>su - postgres</userinput> -->
+$ <userinput>createlang plpgsql gforge</userinput>
+</screen>
+ <para>Finally, install the database:</para>
+<screen>
+$ <userinput>cd <replaceable>/opt/gforge</replaceable>/db</userinput>
+$ <userinput>psql -a -U gforge -W -h localhost -f gforge.sql gforge &> /tmp/gforge.sql.log</userinput>
+$ <userinput>exit</userinput>
+</screen>
+<para>It is required that the postgresql service is up on each reboot</para>
+<screen>
+$ <userinput>chkconfig postgresql on</userinput>
+</screen>
+ <note>
+ <para>You may experience the following errors. They are harmless and you can safely ignore them:</para>
+<screen>
+ERROR: permission denied for language c
+ERROR: must be superuser to create procedural language
+ERROR: permission denied for schema public
+</screen>
+ </note>
+ </section>
+ </section>
+ <section>
+ <title>Configuring DNS Server (BIND)</title>
+ <para>GForge needs its own domain. In example GForge configuration file, it's <literal>gforge.<replaceable>company.com</replaceable></literal>. You should search for <replaceable>company.com</replaceable> in example GForge configuration file and replace it with your domain name.</para>
+ <para>Here some example configuration files for BIND are presented that can help you if you are not familiar with BIND but it's not meant to be complete. Don't ask BIND-related questions in GForge forums, consult documentation that come with your distribution and search in Internet. Distributions put files in different places and so there are no file locations here. The example configuration below is only quick start example and doesn't include reverse mapping.</para>
+ <section>
+ <title>DNS Requirements</title>
+ <para>It's required to have the bind package installed </para>
+ </section>
+
+ <para>New subdomain in <literal>gforge.<replaceable>company.com</replaceable></literal> should be created. In <replaceable>company.com</replaceable> zone file, it may look like that:</para>
+<screen>
+gforge IN NS ns.gforge.<replaceable>company.com</replaceable>.
+ns.gforge IN A <replaceable>1.2.3.4</replaceable>
+</screen>
+ <note>
+ <para>Do not add the latter resource record (<literal>ns.gforge</literal>) if this DNS server serves both <literal><replaceable>company.com</replaceable></literal> and <literal>gforge.<replaceable>company.com</replaceable></literal> zones.</para>
+ </note>
+ <para>New zone file for <literal>gforge.<replaceable>company.com</replaceable></literal> may look like this:</para>
+<screen>
+$TTL 2d
+@ IN SOA gforge.<replaceable>company.com</replaceable>. hostmaster.gforge.<replaceable>company.com</replaceable>. (
+ 1 ; Serial
+ 172800 ; Refresh
+ 900 ; Update retry
+ 2419200 ; Expire
+ 3600 ) ; Negative Cache TTL
+;
+@ IN NS ns.gforge.<replaceable>company.com</replaceable>.
+@ IN A <replaceable>1.2.3.4</replaceable>
+ns IN A <replaceable>1.2.3.4</replaceable>
+
+download IN A <replaceable>1.2.3.4</replaceable>
+shell IN A <replaceable>1.2.3.4</replaceable>
+users IN A <replaceable>1.2.3.4</replaceable>
+lists IN A <replaceable>1.2.3.4</replaceable>
+cvs IN A <replaceable>1.2.3.4</replaceable>
+svn IN A <replaceable>1.2.3.4</replaceable>
+scm IN A <replaceable>1.2.3.4</replaceable>
+ldap IN A <replaceable>1.2.3.4</replaceable>
+jabber IN A <replaceable>1.2.3.4</replaceable>
+</screen>
+ <para>The new zone must be added in main BIND configuration file:</para>
+<screen>
+zone "gforge.<replaceable>company.com</replaceable>" {
+ type master;
+ file "<replaceable>/dist-specific/path/to/zone-file</replaceable>";
+};
+</screen>
+ <para>Of course, changes will take effect after reloading BIND.</para>
+ <para>It is required that the dns service is up on each reboot.</para>
+ <screen>
+$ <userinput>chkconfig named on</userinput>
+ </screen>
+ <!-- <section>
+ <title>Basic but concrete DNS cofiguration on CentOS, Fedora or Red Hat</title>
+ <para>Create the file <filename>/etc/named.conf</filename> and add in :</para>
+ <screen>
+options {
+ directory "/var/named";
+ dump-file "/var/named/data/cache_dump.db";
+ statistics-file "/var/named/data/named_stats.txt";
+};
+include "/etc/rndc.key";
+
+zone "." {
+ type hint;
+ file "/var/named/root.db";
+};
+zone "gforge.company.com" {
+ type master;
+ file "/var/named/gforge.db";
+};
+ </screen>
+ <para>Create the file <filename>/var/named/named.root</filename>and add in :</para>
+ <screen>
+
+ </screen>
+ <para></para>
+ </section>-->
+ </section>
+ <section>
+ <title>Configuring PHP</title>
+ <para>Make sure you have installed <literal>pgsql</literal> and <literal>mbstring</literal> modules.</para>
+ <para>PHP is used in two ways:</para>
<orderedlist>
<listitem>
- <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>.</para>
+ <para><emphasis>Serving Web pages</emphasis>. In this case, PHP is usually used as module and its configuration is in virtual host configuration, as shown later in the document. If you prefer to configure <filename>php.ini</filename>, the following directives are required by GForge:</para>
+<programlisting>
+<!-- register_globals = Off-->
+magic_quotes_gpc = On
+file_uploads = On
+include_path=".:<replaceable>/opt/gforge</replaceable>:<replaceable>/opt/gforge</replaceable>/www/include:/etc/gforge"
+</programlisting>
+ </listitem>
+ <listitem>
+ <para><emphasis>Cron jobs and some scripts</emphasis> require PHP Command-Line Interface (CLI). Scripts are usually invoked with command like this:</para>
+<screen>
+$ <userinput>php5 -f cronjobs/mail/mailing_lists_create.php</userinput>
+</screen>
+ <note>
+ <para>The <literal>-f</literal> is optional when using PHP CLI but it's required when PHP CGI executable is used.</para>
+ </note>
+ <para>You must set <varname>include_path</varname> in PHP CLI <filename>php.ini</filename>, like already shown above. Increase <varname>memory_limit</varname> configuration parameter to at least 32M. To find where <filename>php.ini</filename> is located, use the following command:</para>
+<screen>
+$ <userinput>php5 -i | fgrep php.ini</userinput>
+</screen>
</listitem>
- <listitem><para>Create the primary virtual host and fill the rest of the directives in it:</para>
-<programlisting><![CDATA[
-NameVirtualHost 192.168.1.1
-<VirtualHost 192.168.1.1>
-ServerName gforge.company.com
-ServerAdmin webmaster@gforge.company.com
+ </orderedlist>
+ </section>
+ <section id="web-server">
+ <title>Configuring the Web Server (Apache)</title>
+ <para>Find what system user and group are used by Apache server and change <varname>$sys_apache_user</varname> and <varname>$sys_apache_group</varname> (in GForge configuration) respectively in /etc/gforge/local.inc.</para>
+ <para>You should decide where to put GForge configuration of Apache. It's best if own configuration file that is included by main Apache configuration is used. Consult documentation of your distribution on recommended ways for doing this.</para>
+ <para>You may use <filename>etc/gforge-httpd.conf.example</filename> as template for your configuration. The rest of the section is guide to making GForge virtual host configuration for Apache from scratch. All is inside the following template:</para>
+<programlisting>
+NameVirtualHost <replaceable>1.2.3.4</replaceable>
+<VirtualHost <replaceable>1.2.3.4</replaceable>>
-# Put the rest of the directives here.
+<replaceable># Put the rest of the directives here.</replaceable>
-</VirtualHost>
-]]></programlisting>
- </listitem>
+</VirtualHost>
+</programlisting>
+ <note>
+ <para>Configuring for SSL is not discussed in this guide.</para>
+ </note>
+ <orderedlist>
<listitem>
- <para>Change the <literal>DocumentRoot</literal> to point to the <filename class="directory">www</filename> directory:</para>
+ <para>Set basic virtual host settings:</para>
<programlisting>
-DocumentRoot "/usr/share/gforge/www"
+ServerName gforge.<replaceable>company.com</replaceable>
+ServerAdmin webmaster@gforge.<replaceable>company.com</replaceable>
</programlisting>
</listitem>
<listitem>
- <para>Create a <literal>Directory</literal> directive following the <literal>DocumentRoot</literal> as follows:</para>
-<programlisting><![CDATA[
-<Directory "/usr/share/gforge/www">
- Options Indexes FollowSymLinks
- AllowOverride All
- Order allow,deny
- Allow from all
- ErrorDocument 404 /404.php
-</Directory>
-]]></programlisting>
+ <para>Define log files:</para>
+<programlisting>
+CustomLog "<replaceable>/var/log/gforge</replaceable>/gforge/access.log" combined
+ErrorLog "<replaceable>/var/log/gforge</replaceable>/gforge/error.log"
+</programlisting>
+ <para>Usual practice is to use <command>logrotate</command> on these files. Alternative is to pipe logs to <command>cronolog</command> which will automatically make directory with <filename>access.log</filename> and <filename>error.log</filename> for each day:</para>
+<programlisting>
+CustomLog "|/usr/bin/cronolog <replaceable>/var/log/gforge</replaceable>/gforge/%Y/%m/%d/access.log" combined
+ErrorLog "|/usr/bin/cronolog <replaceable>/var/log/gforge</replaceable>/gforge/%Y/%m/%d/error.log"
+</programlisting>
+ <note>
+ <para>In FHS-compliant install, you may want to use <filename class="directory">/var/local/gforge/log</filename> instead of <filename class="directory">/var/log/gforge</filename>. In any cases, the relevant directories should be created with appropriate permissions.</para>
+ </note>
</listitem>
- <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>
<listitem>
- <para>Add several new filenames to the <literal>DirectoryIndex</literal> directive:</para>
+ <para>Set up document root:</para>
<programlisting>
-DirectoryIndex index.html index.php
+DocumentRoot "<replaceable>/opt/gforge</replaceable>/www"
+<Directory "<replaceable>/opt/gforge</replaceable>/www">
+ Options FollowSymLinks
+ AllowOverride None
+ Order allow,deny
+ Allow from all
+ ErrorDocument 404 /404.php
+</Directory>
</programlisting>
</listitem>
<listitem>
<para>Configuring PHP for Apache</para>
- <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>
- <itemizedlist>
- <listitem>
- <para>Configuring PHP for Apache 1.3</para>
- <orderedlist>
- <listitem>
- <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>
- </listitem>
- <listitem>
- <para>Insert the following instructions after the <literal>DocumentRoot</literal> directive:</para>
-<programlisting><![CDATA[
-<Location /projects>
- ForceType application/x-httpd-php
-</Location>
-<Location /users>
- ForceType application/x-httpd-php
-</Location>
-]]></programlisting>
- <para>Ensure the following lines are present and not commented out in <filename>/etc/httpd/conf/httpd.conf</filename>:</para>
+ <para>Ensure that PHP module is loaded (this is automaticaly made when you install php with rpm or deb). You may need to consult your distribution manual. Typical lines that load and configure PHP module are like this:</para>
<programlisting>
LoadModule php_module modules/libphp.so
AddModule mod_php.c
+
+AddType application/x-httpd-php .php
</programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Configuring PHP for Apache 2.0</para>
- <para>For newer versions of Apache 2.0 (RedHat 9 or above), please follow Apache 1.3 instructions above.</para>
- <orderedlist>
- <listitem>
- <para>Open <filename>/etc/httpd/conf.d/php.conf</filename> and put the rest of the directives in the primary virtual host.</para>
- </listitem>
- <listitem>
- <para>Change the existing <literal>Files</literal> directive to:</para>
-<programlisting><![CDATA[
-<Files *.php>
+ <para>Insert the following instructions after the <literal>DocumentRoot</literal> directive:</para>
+<programlisting>
+<Location /projects>
+ ForceType application/x-httpd-php
+</Location>
+<Location /users>
+ ForceType application/x-httpd-php
+</Location>
+</programlisting>
+ <note>
+ <para>If you use Apache 2, you may need to use a different configuration. Usually, this is not needed. If you receive a <computeroutput>Page Not Found</computeroutput> summary pages, you better try this different style of configuring.</para>
+ <para>Change the existing <literal>Files</literal> directive to:</para>
+<programlisting>
+<Files *.php>
SetOutputFilter PHP
SetInputFilter PHP
AcceptPathInfo On
LimitRequestBody 2097152
-</Files>
-]]></programlisting>
- <para>
- 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>.
- </para>
- </listitem>
- <listitem>
- <para>Add the following lines:</para>
-<programlisting><![CDATA[
-<Files projects>
+</Files>
+</programlisting>
+ <para>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 greater than 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 PHP configuration file.</para>
+ <para>Add the following lines:</para>
+<programlisting>
+<Files projects>
SetOutputFilter PHP
SetInputFilter PHP
AcceptPathInfo on
-</Files>
+</Files>
-<Files users>
+<Files users>
SetOutputFilter PHP
SetInputFilter PHP
AcceptPathInfo on
-</Files>
-]]></programlisting>
- </listitem>
- </orderedlist>
- </listitem>
- </itemizedlist>
+</Files>
+</programlisting>
+ </note>
</listitem>
<listitem>
- <para>Restart the Apache server: <command>/etc/init.d/httpd restart</command></para>
- </listitem>
- </orderedlist>
- <section>
- <title>Project webs</title>
- <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>
-<programlisting><![CDATA[
-#
-# WARNING - security is degraded by having this
-# on the same machine as the primary GForge
-#
-<VirtualHost 192.168.1.1>
- ServerName projects.gforge.company.com
- ServerAlias *.gforge.company.com
- DocumentRoot /var/www/homedirs/groups
- VirtualDocumentRoot /var/www/homedirs/groups/%1
- <Directory /var/www/homedirs/groups>
- Options Indexes
-#
-# WARNING - turning on php will allow any user
-# to upload a php file to your server, and include
-# the gforge local.inc file and get your password to
-# connect to the database and have total control.
-#
- php_flag engine off
- AllowOverride None
- order allow,deny
- allow from all
- </Directory>
- DirectoryIndex index.html index.htm
-</VirtualHost>
-]]></programlisting>
- </section>
- </section>
- <section>
- <title>Configuring the database</title>
- <orderedlist>
- <listitem>
- <para>Configuring PostgreSQL</para>
- <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>
-<screen>
-$ psql -h localhost template1
-</screen>
- <para>If you get an error like this:</para>
-<screen>
-psql: could not connect to server: Connection refused
- Is the server running on host localhost and accepting
- TCP/IP connections on port 5432?
-</screen>
- <para>you need to set <literal>tcpip_socket = true</literal> in the file <filename>/var/lib/pgsql/data/postgresql.conf</filename> then you need to restart PostgreSQL server.</para>
- <para>
- On some systems, PostgreSQL is configured with the <literal>ident</literal> 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 <literal>gforge</literal> on your server, or disable this feature: <command>su - postgres</command>;
- </para>
- <para>Open <filename>/var/lib/pgsql/data/pg_hba.conf</filename> and insert the following lines;</para>
- <para>
- For PostgreSQL 7.3 (note that you can figure out your PostgreSQL version by opening <filename>/etc/init.d/postgresql</filename> and looking for the string <literal>PG_VERSION</literal>=):
- </para>
+ <para>Set up PHP module:</para>
+ <para>If the register_globals variable is set to On in your php.ini, add this line in your conf apache :</para>
<programlisting>
-local all all trust
-host all all 127.0.0.1 255.255.255.255 crypt
+php_flag register_globals Off
</programlisting>
- <para>For PostgreSQL 7.2:</para>
+<para>If the files_uploads variable is not set to On in your php.ini, add this line in your conf apache :</para>
<programlisting>
-local all trust
-host all 127.0.0.1 255.255.255.255 crypt
+php_flag files_uploads On
+</programlisting>
+<para>If the AddDefaultCharset variable is not set to UTF-8 in your httpd.conf, add this line in your conf apache :</para>
+<programlisting>
+php_value default_charset "UTF-8"
+</programlisting>
+<para>Add these lines in your conf apache </para>
+<programlisting>
+php_flag magic_quotes_gpc On
+php_value include_path ".:/etc/gforge:<replaceable>/opt/gforge</replaceable>:<replaceable>/opt/gforge</replaceable>/www/include"
</programlisting>
- <para>and comment out all default directives.</para>
- <para>Restart the PostgreSQL server as root user:</para>
- <screen># /etc/init.d/postgresql restart</screen>
- <para>Become <literal>postgres</literal> user for the following commands:</para>
-<screen>
-# su - postgres
-</screen>
- <para>Now, initialize the database (if you haven't done so already):</para>
-<screen>
-$ initdb
-</screen>
- <para>Create the database user:</para>
-<screen>
-$ createuser -P gforge
-</screen>
- <para>Answer the following two questions:</para>
-<screen>
-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
-</screen>
- <para>and insert a password (most people use <quote>gforge</quote>) for the user to be created.</para>
- <para>Create the database with PL/pgSQL support using the commands:</para>
-<screen>
-$ createdb -U gforge -E UNICODE gforge
-$ createlang plpgsql gforge
-</screen>
</listitem>
<listitem>
- <para>Installing the database</para>
- <para>Now it's time to install the database. The steps are:</para>
- <orderedlist>
- <listitem>
- <para>cd to <filename class="directory">/usr/share/gforge/db</filename></para>
- </listitem>
- <listitem>
-<screen><![CDATA[
-$ psql -a -U gforge gforge < gforge.sql &> /tmp/gforge.sql.log
-]]></screen>
- </listitem>
- </orderedlist>
- <note>
- <title>Mandrake 9-specific installation notes (thanks to Francois Elie)</title>
- <itemizedlist>
- <listitem>
- <para>Edit <filename>/var/lib/pgsql/data/postgresql.conf</filename>:</para>
+ <para>Set up directory index script name (this is automaticaly made when you install php with rpm or deb) :</para>
<programlisting>
-set tcpip_socket=true
-local all md5
+DirectoryIndex index.php
</programlisting>
- </listitem>
- <listitem>
- <para>Edit <filename>/var/lib/pgsql/data/pg_hba.conf</filename>:</para>
- <para>Set for example access right to</para>
- <programlisting>host all 0.0.0.0 0.0.0.0 md5</programlisting>
- </listitem>
- </itemizedlist>
- </note>
+ </listitem>
+ </orderedlist>
+ <para>Of course, all changes will take effect only after reloading or restarting Apache.</para>
+ </section>
+ <section>
+ <title>Configuring Mail Transport Agent (Any)</title>
+ <para>Add the following line to <filename>/etc/aliases</filename> and run <command>newaliases</command>:</para>
+<programlisting>
+noreply: /dev/null
+</programlisting>
+ <para>Make sure that the following domain names are accepted as local destinations by mail transport agent:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>gforge.<replaceable>company.com</replaceable></literal></para>
</listitem>
<listitem>
- <para>Then restart the server: <command>/etc/rc.d/init.d/postgresql restart</command></para>
+ <para><literal>lists.gforge.<replaceable>company.com</replaceable></literal></para>
</listitem>
- </orderedlist>
+ <listitem>
+ <para><literal>users.gforge.<replaceable>company.com</replaceable></literal></para>
+ </listitem>
+ </itemizedlist>
+ <para>You may want to consider adding <literal>MX</literal> (mail exchanger) resource records for the above domain names. This is meaningful only if you want fallback mail routes or if firewall doesn't allow incoming port 25 for the server.</para>
+ <section>
+ <title>Mail gateways to forum and tracker</title>
+ <para>When forum or tracker is monitored, replying to monitor mails are processed by mail gateways. These gateways use GForge configuration file <filename>/etc/gforge/local.inc</filename> so that they can access database but the problem is that they run with different user than that of Apache. So if you want to use these gateways, you'll have to change access mode of <filename>local.inc</filename>.</para>
+ </section>
</section>
<section>
- <title>Upgrading database in existing install</title>
- <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>
- <para>There may also be migration scripts that have to be run. In the <filename class="directory">db/</filename> folder, looked for <filename>migrate-*.php</filename> scripts and run them.</para>
- <warning>
- <para>You have to apply database schema changes and to run migration scripts in the right order.</para>
- </warning>
+ <title>File Release System (FRS)</title>
+ <para>Create a directory (e.g. <filename class="directory"><replaceable>/var/lib/gforge</replaceable>/download</filename>) and make it owned by the webserver user. This directory will be referenced in the GForge Config File <filename>/etc/gforge/local.inc</filename> as <varname>$sys_upload_dir</varname>.</para>
+<screen>
+# <userinput>mkdir <replaceable>/var/lib/gforge</replaceable>/download</userinput>
+# <userinput>chown -R <replaceable>apache-user</replaceable> <replaceable>/var/lib/gforge</replaceable>/download</userinput>
+</screen>
+ <note>
+ <para>For FHS-compliance, use <filename class="directory">/var/local/gforge/download</filename>.</para>
+ </note>
</section>
<section>
- <title>Configuring PHP</title>
- <para>
- Verify the version of PHP installed on your system: <command>php -v</command>
- </para>
+ <title>Configuring GNU Mailman</title>
+ <para>GNU Mailman is used to help manage the GForge mailing lists. Mailman is frequently installed in <filename class="directory">/usr/lib/mailman</filename> but sometimes it can be found in <filename class="directory">/var/mailman</filename>. You should change GForge configuration variable <varname>$sys_path_to_mailman</varname> to that Mailman directory.</para>
+ <para>Cronjobs for Mailman are located in <filename>cronjobs/mail/*</filename>. <filename>cronjobs/mail/mailing_lists_create.php</filename> is used obviously to create new mailing lists.</para>
+ <para>For all problems with Mailman installation and use, contact the Mailman mailing lists for help.</para>
+ <para>To install it:</para>
<orderedlist>
- <listitem><para>Open <filename>/etc/php.ini</filename>.</para></listitem>
<listitem>
- <para>If the PHP version you're using is 4.2.0 or later, enable the <literal>register_globals</literal> variable:</para>
-<programlisting>
-register_globals = On
-</programlisting>
+ <para>Install a GNU Mailman package or compile it</para>
</listitem>
<listitem>
- <para>Ensure that file uploads are allowed:</para>
-<programlisting>
-file_uploads = On
-</programlisting>
+ <para>Don't integrate Mailman with Postfix (or other MTA) by delegating it generation of alias-style file. GForge generates such file. But you'll need to put mail aliases in <filename>/etc/aliases</filename> for the required standard <literal>mailman</literal> mailing list. Create it with:</para>
+<screen>
+# <userinput><replaceable>/usr/lib/mailman/bin</replaceable>/newlist mailman</userinput>
+</screen>
</listitem>
<listitem>
- <para>Add magic quotes to form fields passed to PHP:</para>
-<programlisting>
-magic_quotes_gpc = On
-</programlisting>
+ <para>Configure <filename>mm_cfg.py</filename>:</para>
+ <itemizedlist>
+ <listitem>
+ <para><varname>DEFAULT_HOST_NAME</varname> and <varname>DEFAULT_URL</varname> should point to <literal>lists.gforge.<replaceable>company.com</replaceable></literal>. These variable names may vary depending on Mailman distribution.</para>
+ </listitem>
+ <listitem>
+ <para>Strip ugly <literal>cgi-bin</literal> from URLs in configuration parameters.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para><command>su</command> to <literal>root</literal> and set the Mailman password by using the <command>mmsitepass</command> command</para>
</listitem>
<listitem>
- <para>and configure the <literal>include_path</literal> directive as follows (on one line):</para>
+ <para>Create directory <filename class="directory"><replaceable>/var/www/mailman</replaceable>/</filename>. It will be document root for <literal>lists.gforge.<replaceable>company.com</replaceable>.</literal></para>
+ </listitem>
+ <listitem>
+ <para>In Web server configuraton, create virtual host for Mailman, adjusting <literal>ScriptAlias</literal> and <literal>Alias</literal> directives:</para>
<programlisting>
-include_path=".:/usr/share/gforge:/usr/share/gforge/www/include:/etc/gforge"
+<VirtualHost <replaceable>1.2.3.4</replaceable>>
+ ServerName lists.gforge.<replaceable>company.com</replaceable>
+ ServerAdmin webmaster@gforge.<replaceable>company.com</replaceable>
+
+# You may want to add these files to logrotate, or just use cronolog as shown below
+ CustomLog "<replaceable>/var/log/gforge</replaceable>/lists/access.log" combined
+ ErrorLog "<replaceable>/var/log/gforge</replaceable>/lists/error.log"
+
+# CustomLog "|/usr/bin/cronolog <replaceable>/var/log/gforge</replaceable>/lists/%Y/%m/%d/access.log" combined
+# ErrorLog "|/usr/bin/cronolog <replaceable>/var/log/gforge</replaceable>/lists/%Y/%m/%d/error.log"
+
+ DocumentRoot <replaceable>/var/www/mailman</replaceable>
+ DirectoryIndex index.html
+ ScriptAlias /mailman/ <replaceable>/usr/lib/cgi-bin/mailman/</replaceable>
+ Alias /pipermail/ <replaceable>/var/lib</replaceable>/mailman/archives/public/
+ Alias /images/ <replaceable>/usr/share/images/</replaceable>
+</VirtualHost>
</programlisting>
+ <note>
+ <para>Check that <literal>ScriptAlias</literal> and <literal>Alias</literal> directories are correct. The example values are for Debian 3.1 (Sarge).</para>
+ </note>
</listitem>
</orderedlist>
- <note>
- <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>
- <example>
- <title>gforge.conf vhost configuration</title>
-<programlisting><![CDATA[
-<VirtualHost *>
- DocumentRoot /usr/share/gforge/www
- ServerName gforge.company.com
- ErrorDocument 404 /404.php
- php_value include_path ".:/usr/share/gforge/:/usr/share/gforge/www/include/:/etc/gforge/"
- php_value register_globals On
- php_value magic_quotes_gpc On
- AddDefaultCharset UTF-8
- AcceptPathInfo On
- <Location /projects>
- ForceType application/x-httpd-php
- </Location>
- <Location /users>
- ForceType application/x-httpd-php
- </Location>
-</VirtualHost>
-]]></programlisting>
- </example>
- </note>
+ <section>
+ <title>Mailing list for commits</title>
+ <para>When repositories are created, mailing list <literal><replaceable>project</replaceable>-commits@lists.gforge.<replaceable>company.com</replaceable></literal> is created too. Note that project administrators should manually set Privacy Options... / Sender filters / accept_these_nonmembers to something like <literal>^.*@<replaceable>servername\.company\.com</replaceable></literal> where <replaceable>servername.company.com</replaceable> is name of the host where Mailman is installed (<literal>lists.gforge.<replaceable>company.com</replaceable></literal>).</para>
+ </section>
</section>
<section>
- <title>GForge Config File</title>
- <para>In the GForge distribution, you will find <filename>etc/local.inc</filename>. Move it to <filename>/etc/gforge/local.inc</filename> and edit all of the settings.</para>
- <para>Usually, you will want to make it readable only by webserver user (e.g. <literal>apache</literal>):</para>
-<programlisting>
-# chown -R apache:apache /etc/gforge/
-# chmod 600 /etc/gforge/local.inc
-</programlisting>
+ <title>Source Code Management (SCM)</title>
+ <para>CVS and Subversion (SVN) are popular SCM systems that may be installed as plugins, as shown later. You'll have to make their needed directories:</para>
+<screen>
+# <userinput>mkdir <replaceable>/var/www</replaceable>/scmtarballs</userinput>
+# <userinput>mkdir <replaceable>/var/www</replaceable>/scmsnapshots</userinput>
+</screen>
+ <para>These directories correspond to GForge configuration variables <varname>$sys_scm_tarballs_path</varname> and <varname>$sys_scm_snapshots_path</varname>.</para>
+ <note>
+ <para>For FHS-compliance, use <filename class="directory">/var/local/gforge/scmtarballs</filename> and <filename class="directory">/var/local/gforge/scmsnapshots</filename>.</para>
+ </note>
</section>
<section>
- <title>Mail Aliases</title>
+ <title>Cron Jobs</title>
<para>
- Add the following line to <filename>/etc/aliases</filename> and run <command>newaliases</command>:
+ Cron jobs are in the <filename class="directory">cronjobs/</filename> directory and the <filename>crontab.in</filename> file contains a sample crontab. This gives you the basic cronjobs for updating certain statistics and data on the site.
</para>
-<programlisting>
-noreply: /dev/null
-</programlisting>
- </section>
- <section>
- <title>File Release System (FRS)</title>
<para>
- 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>.
+ <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> and CVS plugins section for more info.
</para>
+ <para>
+ <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.
+ </para>
+ <para>Prepare for <filename>cronjobs/cvs-cron/usergroup.php</filename> and <filename>cronjobs/mail/mailaliases.php</filename>.</para>
+ <screen>
+# <userinput>adduser anonymous</userinput>
+# <userinput>cp /etc/aliases /etc/aliases.org</userinput>
+# <userinput>cp /etc/shadow /etc/shadow.org</userinput>
+# <userinput>cp /etc/passwd /etc/passwd.org</userinput>
+# <userinput>cp /etc/group /etc/group.org</userinput>
+</screen>
+ <note>
+ <para>There are two other ways to authenticate GForge users: LDAP and NSS with PostgreSQL backend. They are not discussed in this guide.</para>
+ </note>
+ <caution>
+ <para>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.</para>
+ </caution>
+ <warning>
+ <para>
+ The following command will blow away any existing root crontab:
+ </para>
+ </warning>
+<screen>
+# <userinput>crontab cronjobs/crontab.in</userinput>
+</screen>
+ <para>Now edit the paths to the cron scripts by setting the value of <varname>GFORGE</varname> and <varname>PHP</varname> variables:</para>
+ <screen>
+# <userinput>crontab -e</userinput>
+</screen>
+ <para>Uncomment entries for <filename>cronjobs/cvs-cron/usergroup.php</filename>, <filename>cronjobs/mail/mailing_lists_create.php</filename>, and <filename>cronjobs/mail/mailaliases.php</filename> but not before understanding the consequences.</para>
</section>
<section>
- <title>Configuring CVSWeb</title>
+ <title>Verifying the Installation</title>
+ <para>To verify if everything was installed correctly, use the browser and connect to GForge. You should see the GForge homepage. You will need to either disable CVS and SVN plugins in some way, or configure them before making the first test.</para>
<note>
- <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>
- <para>The following instructions are for GForge < 4.0.</para>
+ <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>
</note>
- <para>
- 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.
- </para>
- <para>Copy the tar.gz file into a tmp directory and unzip it:</para>
+ </section>
+ <section>
+ <title>Creating the Admin User</title>
+ <para>Site admins are anyone who is an admin of <literal>group_id</literal>=1.</para>
+ <orderedlist>
+ <listitem><para>Connect to GForge and register a new account.</para></listitem>
+ <listitem><para>Insert a valid email address; this will be used for the account confirmation.</para></listitem>
+ <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>
+ <listitem>
+ <para>Verify in Account Maintenance the user id of the user registered.</para>
+ <para>Usually this is 102, but you can verify this by running the following SQL query via the PostgreSQL <command>psql</command> utility:</para>
<screen>
-tar -zxvf cvsweb.tar.gz
+$ <userinput>psql -U gforge -W -h localhost gforge</userinput>
+gforge=> <userinput>SELECT user_id FROM users WHERE user_name='<replaceable>YOUR USER NAME</replaceable>'</userinput>;
</screen>
- <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>
- <itemizedlist>
- <listitem><para>Copy the <filename>cvsweb.cgi</filename> script into Apache's <filename class="directory">cgi-bin</filename> directory</para></listitem>
- <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>
- <listitem><para>Edit <filename>cvsweb.conf</filename></para></listitem>
- <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>
- <listitem><para>Change the <varname>$cvstreedefault</varname> variable to point to a default repository</para></listitem>
- <listitem><para>With GForge specific CVSWeb, you don't need to add manually projects' repositories.</para></listitem>
- <listitem><para>Edit <filename>cvsweb.cgi</filename></para></listitem>
- <listitem><para>Change the <varname>$config</varname> variable to point the <filename>cvsweb.conf</filename> file</para></listitem>
- <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>
- </itemizedlist>
- <para>Possible problems:</para>
- <itemizedlist>
- <listitem>
- <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>
</listitem>
<listitem>
- <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>
+ <para>Now set up the newly added user to be a GForge administrator:</para>
+<screen>
+gforge=> <userinput>INSERT INTO user_group (user_id,group_id,admin_flags)</userinput>
+gforge-> <userinput>VALUES (<replaceable>102</replaceable>,1,'A');</userinput>
+</screen>
</listitem>
- </itemizedlist>
- <para>Create in <filename>httpd.conf</filename> virtual host for viewing of CVSWeb:</para>
-<programlisting><![CDATA[
-<VirtualHost 192.168.1.1>
-ServerName cvs.gforge.company.com
-ServerAdmin webmaster@cvs.gforge.company.com
-DocumentRoot /var/www/cvs
-DirectoryIndex index.php cvsweb.cgi index.html index.htm
-</VirtualHost>
-]]></programlisting>
+ </orderedlist>
+ <para>One of the first string as GForge administrator is to initialize once the reporting tables from Reporting tab.</para>
+ <note>
+ <para>Once you have set up this user as an administrator, you can use GForge web interface to add more administrators.</para>
+ </note>
</section>
<section>
- <title>Configuring GForge</title>
+ <title>Customizing Front Page</title>
+ <para>If you want to customize front page, you'll have to provide new <filename>index_std.php</filename>:</para>
<orderedlist>
- <listitem><para>Login as <literal>root</literal> user</para></listitem>
<listitem>
- <para>Create a directory <filename class="directory">gforge-files</filename>:</para>
- <screen># mkdir /var/www/gforge-files</screen>
- <para>Make this directory writeable by Apache:</para>
- <screen># chown -R apache.apache /var/www/gforge-files</screen>
- <para>This directory will contain all files/patches uploaded to your gforge site.</para>
+ <para>Create <filename class="directory">/etc/gforge/custom</filename> directory.</para>
</listitem>
<listitem>
- <para>Create a directory <filename class="directory">/etc/gforge</filename></para>
+ <para>Set <varname>$sys_custom_path</varname> configuration variable to <filename class="directory">/etc/gforge/custom</filename>.</para>
</listitem>
<listitem>
- <para>Copy the file <filename>local.inc.example</filename> from <filename class="directory">/usr/share/gforge/etc/</filename> to <filename class="directory">/etc/gforge/</filename> </para>
+ <para>Copy <filename><replaceable>/var/www/gforge</replaceable>/www/index_std.php</filename> to <filename>/etc/gforge/custom/index_std.php</filename> and edit it as you like.</para>
</listitem>
- <listitem>
- <para>Open <filename>/etc/gforge/local.inc</filename>, configuring the following basic parameters:</para>
+ </orderedlist>
+ </section>
+ <section>
+ <title>Optional Features</title>
+ <section>
+ <title>Project webs</title>
+ <para>Each project can have its own virtual host <literal><replaceable>projectname</replaceable>.projects.gforge.<replaceable>company.com</replaceable></literal>. Location of project files is configured with <varname>$groupdir_prefix</varname> variable in GForge configuration file. Each project has directory with project's name and contains <filename class="directory">htdocs</filename> subdirectory where Web files are placed. Project directories are created by <filename>cronjobs/cvs-cron/usergroup.php</filename>.</para>
+ <section>
+ <title>DNS Server Configuration (BIND)</title>
+ <para>Project virtual hosts require new DNS zone. Making this new zone is similar to making DNS zone for GForge itself.</para>
<orderedlist>
<listitem>
- <para>Database configuration:</para>
+ <para>Declare new zone in <literal>gforge.<replaceable>company.com</replaceable></literal> zone:</para>
<programlisting>
-$sys_dbhost="localhost" # some folks suggest setting this to "", your mileage may vary
-$sys_dbname="gforge"
-$sys_dbuser="gforge"
-$sys_dbpasswd="gforge"
-$sys_server="postgres"
+projects IN NS ns.projects.gforge.<replaceable>company.com</replaceable>
</programlisting>
+ <para>If DNS server <emphasis>doesn't</emphasis> serve the new <literal>projects.gforge.<replaceable>company.com</replaceable></literal> zone, add the following line too:</para>
+<programlisting>
+ns.projects IN A <replaceable>1.2.3.4</replaceable>
+</programlisting>
+ <para>Don't forget to change serial number of <literal>gforge.<replaceable>company.com</replaceable></literal> zone!</para>
</listitem>
<listitem>
- <para>Change the value of the <varname>$sys_upload_dir</varname> to:</para>
- <programlisting>$sys_upload_dir='/var/lib/gforge/download/';</programlisting>
+ <para>Create new zone file with following content:</para>
+<programlisting>
+$TTL 2d
+@ IN SOA projects.gforge.<replaceable>company.com</replaceable>. hostmaster.gforge.<replaceable>company.com</replaceable>. (
+ 1 ; Serial
+ 172800 ; Refresh
+ 900 ; Update retry
+ 2419200 ; Expire
+ 3600 ) ; Negative Cache TTL
+;
+@ IN NS ns.projects.gforge.<replaceable>company.com</replaceable>.
+@ IN A <replaceable>1.2.3.4</replaceable>
+ns IN A <replaceable>1.2.3.4</replaceable>
+
+* IN A <replaceable>1.2.3.4</replaceable>
+</programlisting>
</listitem>
<listitem>
- <para>Change the value of the <varname>$sys_urlroot</varname> to:</para>
-<programlisting>$sys_urlroot="/usr/share/gforge/www/";</programlisting>
+ <para>The new zone must be added in main BIND configuration file:</para>
+<programlisting>
+zone "projects.gforge.<replaceable>company.com</replaceable>" {
+ type master;
+ file "<replaceable>/dist-specific/path/to/zone-file</replaceable>";
+};
+</programlisting>
</listitem>
<listitem>
- <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>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Restart Apache: <command>/etc/init.d/httpd restart</command></para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>Configuring GNU Mailman</title>
- <para>GNU Mailman is used to help manage the GForge mailing lists. To install it:</para>
- <para>Install a GNU Mailman package or compile it</para>
- <para><command>su</command> to <literal>root</literal> and set the Mailman password</para>
- <para>Create in <filename>httpd.conf</filename> virtual host for Mailman, adjusting <literal>ScriptAlias</literal> and <literal>Alias</literal> directives:</para>
-<programlisting><![CDATA[
-<VirtualHost 192.168.1.1>
-ServerName lists.gforge.company.com
-ServerAdmin mailman@lists.gforge.company.com
-DocumentRoot /var/www/mailman
-DirectoryIndex index.php index.cgi index.html index.htm
-ScriptAlias /mailman/ /var/mailman/cgi-bin/
-Alias /pipermail/ /var/mailman/archives/public/
-</VirtualHost>
-]]></programlisting>
- <para>Run the script <command>gforge/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 <literal>-f</literal> flag, i.e.:</para>
-<screen>
-# php -f mailing_lists_create.php
-</screen>
- </section>
- <section>
- <title>Configuring CVS</title>
- <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>
- <para>Download and install the latest CVS package for your distribution.</para>
- <para>Ensure the following info is in <filename>/etc/services</filename>:</para>
+ <para>Reload BIND and test if all works:</para>
<screen>
-$ grep cvspserver /etc/services
-cvspserver 2401/tcp # CVS client/server operations
-cvspserver 2401/udp # CVS client/server operations
+$ <userinput>host test.projects.gforge.<replaceable>company.com</replaceable></userinput>
+test.projects.gforge.<replaceable>company.com</replaceable> has address <replaceable>1.2.3.4</replaceable>
</screen>
- <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>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section>
+ <title>Web Server Configuration (Apache)</title>
+ <para>Module <literal>vhost_alias</literal> should be enabled and the following directives should be added to <filename>httpd.conf</filename> (if <filename class="directory"><replaceable>/var/www/homedirs</replaceable>/groups</filename> is what you have chosen in <varname>$groupdir_prefix</varname>):</para>
+ <note>
+ <para>If you want to be FHS-compliant, you may use <filename>/var/local/gforge/log</filename> and <filename>/var/local/gforge/homedirs</filename>. </para>
+ </note>
<programlisting>
-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
-}
+#
+# WARNING - security is degraded by having this
+# on the same machine as the primary GForge
+#
+NameVirtualHost <replaceable>1.2.3.4</replaceable>
+<VirtualHost <replaceable>1.2.3.4</replaceable>>
+ ServerName projects.gforge.<replaceable>company.com</replaceable>
+ ServerAlias *.projects.gforge.<replaceable>company.com</replaceable>
+ ServerAdmin webmaster@gforge.<replaceable>company.com</replaceable>
+ UseCanonicalName Off
+
+# You may want to add these files to logrotate, or just use cronolog as shown below
+ CustomLog "<replaceable>/var/log/gforge</replaceable>/projects/access.log" combined
+ ErrorLog "<replaceable>/var/log/gforge</replaceable>/projects/error.log"
+
+# CustomLog "|/usr/bin/cronolog <replaceable>/var/log/gforge</replaceable>/projects/%Y/%m/%d/access.log" combined
+# ErrorLog "|/usr/bin/cronolog <replaceable>/var/log/gforge</replaceable>/projects/%Y/%m/%d/error.log"
+
+ DocumentRoot <replaceable>/var/www/homedirs</replaceable>/groups
+ VirtualDocumentRoot <replaceable>/var/www/homedirs</replaceable>/groups/%1/htdocs
+ <Directory <replaceable>/var/www/homedirs</replaceable>/groups>
+ Options Indexes
+#
+# WARNING - turning on php will allow any user
+# to upload a php file to your server, and include
+# the gforge local.inc file and get your password to
+# connect to the database and have total control.
+#
+ php_flag engine off
+ AllowOverride None
+ Order allow,deny
+ Allow from all
+ </Directory>
+ DirectoryIndex index.html index.htm
+</VirtualHost>
</programlisting>
- <para>Now add an <literal>anonymous</literal> user to your system with a blank password, or one of <literal>anonymous</literal></para>
- </section>
- <section>
- <title>Cron Jobs</title>
- <para>
- 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.
- </para>
- <para>
- <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.
- </para>
- <para>
- <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.
- </para>
- <screen>
-# adduser anonymous
-# cp /etc/aliases /etc/aliases.org
-# cp /etc/shadow /etc/shadow.org
-# cp /etc/passwd /etc/passwd.org
-# cp /etc/group /etc/group.org
-# mkdir /cvsroot
+ <note>
+ <para><filename>cronjobs/cvs-cron/usergroup.php</filename> copies from <filename>cronjobs/cvs-cron/default_page.php</filename> to <filename><replaceable>/var/www/homedirs</replaceable>/groups/<replaceable>projectname</replaceable>/htdocs/index.php</filename> but the above configuration disables PHP.</para>
+ </note>
+ </section>
+ </section>
+ <section>
+ <title>Full Text Indexing</title>
+ <para>If you want to enable full text indexing, follow these steps:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Find <filename>tsearch2.sql</filename> in your distribution of PostgreSQL and run it:</para>
+<screen>
+# <userinput>su - postgres</userinput>
+$ <userinput>psql -f <replaceable>/path/to/</replaceable>tsearch2.sql gforge</userinput>
</screen>
- <warning>
- <para>
- The following command will blow away any existing root crontab:
- </para>
- </warning>
- <screen>
-# crontab cronjobs/crontab.in
+<para>Since <literal>gforge</literal> PostgreSQL user is not superuser, access to some Tsearch2 tables should be additionally granted:</para>
+<screen>
+# <userinput>su - postgres</userinput>
+$ <userinput>psql gforge</userinput>
+gforge=# <userinput>GRANT SELECT ON pg_ts_dict TO gforge;</userinput>
+gforge=# <userinput>GRANT SELECT ON pg_ts_parser TO gforge;</userinput>
+gforge=# <userinput>GRANT SELECT ON pg_ts_cfg TO gforge;</userinput>
+gforge=# <userinput>GRANT SELECT ON pg_ts_cfgmap TO gforge;</userinput>
</screen>
- <para>Now edit the paths to the cron scripts by setting the value of <literal>$GFORGE</literal>:</para>
- <screen>
-# crontab -e
+ </listitem>
+ <listitem>
+ <para>Import data definitions:</para>
+<screen>
+$ <userinput>cd <replaceable>/var/www/gforge</replaceable>/db</userinput>
+$ <userinput>psql -U gforge -W -h localhost -f FTI.sql gforge</userinput>
+$ <userinput>psql -U gforge -W -h localhost -f FTI-20050315.sql gforge</userinput>
+$ <userinput>psql -U gforge -W -h localhost -f FTI-20050401.sql gforge</userinput>
+$ <userinput>psql -U gforge -W -h localhost -f FTI-20050530.sql gforge</userinput>
</screen>
- <caution>
- <para>
- 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.
- </para>
- </caution>
- </section>
- <section>
- <title>JPGraph</title>
- <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>
- <para>
- When you get your preferred version of JPGraph installed, you will have to edit one setting in <filename>jpgraph.php</filename>:
- </para>
- <programlisting>
+ </listitem>
+ <listitem>
+ <para>Enable Full Text Indexing by setting <varname>$sys_use_fti</varname> in GForge Configuration File <filename>local.inc</filename>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>JPGraph</title>
+ <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>
+ <para>Manual installation can be done like this:</para>
+<screen>
+# tar -xzf jpgraph-1.19.tar.gz
+# mkdir <replaceable>/var/www</replaceable>/jpgraph
+# cp -R jpgraph-1.19/src/* <replaceable>/var/www</replaceable>/jpgraph
+</screen>
+ <note>
+ <para>If you want FHS-compliance, <filename class="directory">/usr/local/share/jpgraph</filename></para>
+ </note>
+ <para>When you get your preferred version of JPGraph installed, you will have to edit one setting in <filename>jpgraph.php</filename> (or <filename>jpg-config.php</filename>, depending on JPGraph version):</para>
+<programlisting>
DEFINE("USE_CACHE", false);
</programlisting>
- <warning>
- <para>Be careful with JPGraph license: versions > 1.5.2 are not free (as in free speech).</para>
- </warning>
- </section>
- <section>
- <title>Perl</title>
- <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>
- <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>
- <programlisting>
+ <warning>
+ <para>Be careful with JPGraph license: versions > 1.5.2 are not free (as in free speech). You must check license before use.</para>
+ </warning>
+ </section>
+ <section>
+ <title>Perl</title>
+ <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>
+ <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>
+<programlisting>
$sys_default_domain = 'gforge.company.com' ;
$sys_dbhost = '192.168.12.34' ;
$sys_dbname = 'gforge' ;
$sys_dbuser = 'gforge' ;
$sys_dbpasswd = 'p455w0rd' ;
</programlisting>
- </section>
- <section>
- <title>Jabber Support</title>
- <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>
- <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>
+ </section>
+ <section>
+ <title>Jabber Support</title>
+ <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>
+ <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>
+ </section>
+ <section>
+ <title>Peer Ratings</title>
+ <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>
+ <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>
+ </section>
</section>
</section>
<section>
- <title>Verifying the installation</title>
- <para>
- To verify if everything was installed correctly, use the browser and connect to GForge. You should see the GForge homepage.
- </para>
+ <title>Plugins</title>
<note>
- <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>
+ <para>Since GForge 4.0, plugins are necessary as source code management is now provided by plugins (SCM* plugins).</para>
</note>
- </section>
- <section>
- <title>Creating the admin user</title>
- <para>
- Site admins are anyone who is an admin of <literal>group_id</literal>=1.
- </para>
- <orderedlist>
- <listitem><para>Connect to GForge and register a new account.</para></listitem>
- <listitem><para>Insert a valid email address; this will be used for the account confirmation.</para></listitem>
- <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>
- <listitem>
- <para>Verify in Account Maintenance the user id of the user registered.</para>
- <para>Usually this is 102, but you can verify this by running the following SQL query via the PostgreSQL <command>psql</command> utility:</para>
+ <para>For each plugin, you can find an <filename>INSTALL</filename> file in the plugin tarball.</para>
+ <section>
+ <title>CVS</title>
+ <section>
+ <title>Overview</title>
+ <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 copy the <filename>plugins/scmcvs/etc/*</filename> directories to <filename class="directory">/etc/gforge</filename> directory and possibly modify the files slightly.</para>
+ </section>
+ <section>
+ <title>Cronjobs</title>
+ <para>Cronjobs for CVS are included in <filename>cronjobs/crontab.in</filename>, but are commented out by default for your security. The CVS cronjobs are in <filename><replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron</filename> and consist of:</para>
+ <itemizedlist>
+ <listitem>
+ <para><filename>usergroup.php</filename> creates user and groups in <filename>/etc/passwd</filename>, <filename>/etc/shadow</filename>, and <filename>/etc/group</filename>.</para>
+ </listitem>
+ <listitem>
+ <para><filename>cvs.php</filename> creates repositories.</para>
+ </listitem>
+ <listitem>
+ <para><filename>ssh_create.php</filename> copies SSH keys to user directories.</para>
+ </listitem>
+ <listitem>
+ <para><filename>history_parse.php</filename> collects statistics.</para>
+ </listitem>
+ </itemizedlist>
+ <para>There are other cronjobs that can be activated too:</para>
+ <itemizedlist>
+ <listitem>
+ <para><filename>plugins/scmcvs/cronjobs/tarballs.php</filename> creates tarballs</para>
+ </listitem>
+ <listitem>
+ <para><filename>plugins/scmcvs/bin/snapshots.sh</filename> creates tarballs. <varname>CVSROOT</varname> and <varname>SCMSNAPSHOTSDIR</varname> variables are hard-coded in the script, so you'll have to edit the script if necessary.</para>
+ </listitem>
+ </itemizedlist>
+ <para>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. Here is a list of CVS cronjobs:</para>
+ <para>If you are using CVS 1.12, replace <filename>syncmail</filename> with updated version.</para>
<screen>
-$ psql -U gforge gforge
-gforge=> SELECT user_id FROM users WHERE user_name='<replaceable>YOUR USER NAME</replaceable>';
+# <userinput>cd <replaceable>/var/www/gforge</replaceable></userinput>
+# <userinput>cp plugins/scmcvs/bin/syncmail-cvs-1.12 cronjobs/cvs-cron/syncmail</userinput>
</screen>
- </listitem>
- <listitem>
- <para>Now set up the newly added user to be a GForge administrator:</para>
+ <para>Replace <literal>%1{sVv}</literal> in <filename><replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron/cvs.php</filename> with <literal>%p %{sVv}</literal>. Search for <literal>LockDir=</literal> in <filename>cronjobs/cvs-cron/cvscreate.sh</filename> and add the following line after it:</para>
+ <programlisting>
+echo "UseNewInfoFmtStrings=yes" >> $repositorypath/CVSROOT/config
+ </programlisting>
+ </section>
+ <section>
+ <title>Installation</title>
+ <warning>
+ <para>This guide doesn't cover chrooted CVS repositories which are always recommended.</para>
+ </warning>
+ <orderedlist>
+ <listitem>
+ <para>Create default location for CVS repositories (<varname>$cvsdir_prefix</varname> in GForge configuration file):</para>
<screen>
-gforge=> INSERT INTO user_group (user_id,group_id,admin_flags) VALUES (102,1,'A');
+# <userinput>mkdir <replaceable>/cvsroot</replaceable></userinput>
</screen>
- </listitem>
- </orderedlist>
- <note>
- <para>Once you have set up this user as an administrator, you can use GForge web interface to add more administrators.</para>
- </note>
+ </listitem>
+ <listitem>
+ <para><emphasis>Optional:</emphasis> Set up basic index.php file for CVS virtual host if desired. This guide has not further instructions on enabling CVS virtual host.</para>
+<screen>
+# <userinput>mkdir <replaceable>/var/www/cvs</replaceable></userinput>
+# <userinput>cp <replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron/www/* <replaceable>/var/www/cvs</replaceable></userinput>
+</screen>
+ </listitem>
+ <listitem>
+ <para>Copy the scmcvs plugin config to <filename class="directory">/etc/gforge</filename>:</para>
+<screen>
+# <userinput>cp -R <replaceable>/var/www/gforge</replaceable>/plugins/scmcvs/etc/* /etc/gforge</userinput>
+</screen>
+ </listitem>
+ <listitem>
+ <para>Make sure the cvs crons are executable:</para>
+<screen>
+# <userinput>cd <replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron/</userinput>
+# <userinput>chmod 755 *.php *.sh</userinput>
+</screen>
+ </listitem>
+ <listitem>
+ <para>Copy CVS restricted shell:</para>
+<screen>
+# <userinput>cp <replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron/cvssh.pl /bin</userinput>
+</screen>
+ </listitem>
+ <listitem>
+ <para>Edit GForge Config File <filename>/etc/gforge/local.inc</filename> and change <varname>$sys_path_to_scmweb</varname> to be <filename class="directory"><replaceable>/var/www/gforge</replaceable>/plugins/scmcvs/cgi-bin</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>You may have to edit <filename>/etc/gforge/plugins/scmcvs/cvsweb.conf</filename> to change the cvsroot location:</para>
+<screen>
+'gforge' => ['GForge-CVS', '<replaceable>/cvsroot/</replaceable>'],
+</screen>
+ </listitem>
+ <listitem>
+ <para>Install the following non-core Perl modules:</para>
+ <itemizedlist>
+ <listitem>
+ <para>IPC::Run</para>
+ </listitem>
+ <listitem>
+ <para>URI::Escape</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>You may want to user CVS pserver. First, assure that cvspserver service is defined in <filename>/etc/services</filename>. It will look like this:</para>
+<programlisting>
+cvspserver 2401/tcp
+cvspserver 2401/udp
+</programlisting>
+ <para>Add entry for pserver in <filename>/etc/inetd.conf</filename>:</para>
+<para><literal>cvspserver stream tcp nowait root <replaceable>/var/www/gforge</replaceable>/plugins/scmcvs/bin/cvs-pserver cvs-pserver</literal></para>
+
+ <para>Make sure that the wrapper script is executable:</para>
+<screen>
+# <userinput>chmod +x <replaceable>/var/www/gforge</replaceable>/plugins/scmcvs/bin/cvs-pserver</userinput>
+</screen>
+ <para>The used wrapper script <filename><replaceable>/var/www/gforge</replaceable>/plugins/scmcvs/bin/cvs-pserver</filename> assumes that CVS repositories are in chroot environment and you may want to edit the script and change <varname>CHROOTDIR</varname> and <varname>CVSROOT</varname> variables.</para>
+ <warning>
+ <para>CVS pserver has long history of vulnerabilities and its use is highly discouraged.</para>
+ </warning>
+ </listitem>
+ </orderedlist>
+ </section>
+ </section>
+ <section>
+ <title>CVSTracker</title>
+ <section>
+ <title>Overview</title>
+ <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>
+ <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>
+ <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>
+ </section>
+ <section>
+ <title>Installation</title>
+ <screen>
+# <userinput>cd <replaceable>/var/www/gforge</replaceable>/plugins/cvstracker/</userinput>
+# <userinput>cp -R etc/plugins/cvstracker/ /etc/gforge/plugins/</userinput>
+ </screen>
+ <para>Edit <filename>/etc/gforge/plugins/cvstracker/config.php</filename> and change parameters.</para>
+ <para>Uncomment <filename>update_loginfo.php</filename> in crontab.</para>
+ <note>
+ <para>CVS Tracker is not enabled by default for project. You'll have to manually enable it.</para>
+ </note>
+ </section>
+ </section>
+ <section>
+ <title>SVN</title>
+ <section>
+ <title>Overview</title>
+ <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>
+ <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>
+ <para>Configuring svnserv for svn-over-ssh:
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://svnbook.red-bean.com/en/1.0/ch06s03.html" /></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://www.logemann.org/day/archives/000099.html" /></para>
+ </listitem>
+ <listitem>
+ <para><ulink url="http://bitworking.org/news/Getting_subversion_svn_ssh____to_work_with_PuTTY" /></para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section>
+ <title>Installation</title>
+ <note>
+ <para><emphasis>Instructions here are far from complete.</emphasis></para>
+ </note>
+<programlisting>
+#Create default location for SVN repositories
+mkdir /svnroot
+
+# Optional - Set up some basic files for SVN-over-DAV only
+mkdir /var/www/svn
+cp <replaceable>/var/www/gforge</replaceable>/cronjobs/dav-svn/www/* /var/www/svn/
+
+#copy the scmsvn config files to /etc/gforge/
+cp -R gforge/plugins/scmsvn/etc/plugins/scmsvn/ /etc/gforge/plugins/
+</programlisting>
+ </section>
+ </section>
</section>
<section>
- <title>Peer Ratings</title>
- <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>
- <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>
+ <title>Upgrading Existing Install</title>
+ <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>
+ <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>
+ <warning>
+ <para>You have to apply database schema changes and to run migration scripts in the right order.</para>
+ </warning>
</section>
<section>
- <title>Installing a plugin</title>
- <note>
- <para>From GForge 4.0, plugins are necessary as source code management is now provided by plugins (SCM* plugins).</para>
- </note>
- <para>For each plugin you can find an INSTALL file in the plugin tarball.</para>
+ <title>Most Common Problems</title>
+ <para>Q: I get a blank page when I visit http://gforge.company.com/</para>
+ <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>
+ <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>
+<programlisting>
+$conn = @pg_connect(
+</programlisting>
+ <para>So that it looks like:</para>
+<programlisting>
+$conn = pg_connect(
+</programlisting>
+ <para>This will let debug output dump to the screen and may let you find the problem. Search the forums for more solutions.</para>
+
+ <para>Q: <quote>Error Occurred In the Logger</quote> or other database permission problems</para>
+ <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>
+
+ <para>Q: Reporting or time tracking doesn't work</para>
+
+ <para>A: Go to the reporting tab and scroll down so you can choose <quote>Initialize/Rebuild Reporting Tables</quote></para>
+
+ <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>
+
+ <para>Q: How do I upgrade my database?</para>
+ <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>
+
+ <para>Q: I'm getting an error about BaseLanguage.class.php not being found.</para>
+ <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>
+
+ <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>
+ <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>
+
+ <para>Q: How do I backup GForge?</para>
+ <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>
+
+ <para>Q: Any time i enter an apostrophe in a text box, i get a parse error</para>
+ <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>
+
+ <para>Q: Large uploads into FRS or the doc manager fail.</para>
+ <para>A: Apache and the <filename>php.ini</filename> file need to have upload limits and possibly memory limits increased.</para>
+
+ <para>Q: When I click on <filename>/projects/</filename> or <filename>/users/</filename> links, I get a <computeroutput>Page Not Found</computeroutput> error instead of the page I expected.</para>
+ <para>A: Switch to/from the <Files projects> from/to the <Location /projects> directives in your <filename>httpd.conf</filename>. (Q&A provided by David Morsberger)</para>
+
</section>
+
</article>