</para>
<orderedlist>
<listitem><para>Linux Operating System</para></listitem>
- <listitem><para><ulink url="http://www.postgresql.org/">PostgreSQL</ulink> 7.3 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>
<title>Installation</title>
<section>
<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>
- <para>This installation guide is for GForge 4.5.0.1.</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 on Debian</title>
+ <title>Installing Gforge on Debian</title>
<para>
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>
</para>
</section>
<section>
- <title>Installing on RPM-based systems</title>
+ <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>Installing GForge</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>/var/www/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>
+ <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>Unpacking</title>
- <para>To install GForge, follow these steps (as root):</para>
-<screen>
-# <userinput>bzip2 -dc gforge-4.5.tar.bz2 | tar xvf -</userinput>
-# <userinput>mv gforge-4.5 <replaceable>/var/www/gforge</replaceable></userinput>
-</screen>
+ <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 -R root: /etc/gforge</userinput>
-# <userinput>cp <replaceable>/var/www/gforge</replaceable>/etc/local.inc.example /etc/gforge/local.inc</userinput>
-# <userinput>chmod -R 644 /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>
$sys_dbhost="localhost"
$sys_dbname="gforge"
$sys_dbuser="gforge"
-$sys_dbpasswd="gforge"
-$sys_server="postgres"
+$sys_dbpasswd="<replaceable>gforge-password</replaceable>"
</programlisting>
</listitem>
- <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>-->
<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>
+ <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>
<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>
<screen>
local all postgres 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>:</para>
+<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>
+
+ <!-- <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>
+</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>
<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>su - postgres</userinput> -->
$ <userinput>createlang plpgsql gforge</userinput>
</screen>
<para>Finally, install the database:</para>
<screen>
-$ <userinput>cd <replaceable>/var/www/gforge</replaceable>/db</userinput>
-$ <userinput>psql -a -U gforge -W -f gforge.sql gforge &> /tmp/gforge.sql.log</userinput>
+$ <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>
<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>
+ <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>.
};
</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><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 document. If you prefer to configure <filename>php.ini</filename>, the following directives are required by GForge:</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 = On
+<!-- register_globals = Off-->
magic_quotes_gpc = On
file_uploads = On
-include_path=".:<replaceable>/var/www/gforge</replaceable>:<replaceable>/var/www/gforge</replaceable>/www/include:/etc/gforge"
+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>php4 -f cronjobs/mail/mailing_lists_create.php</userinput>
+$ <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. To find where <filename>php.ini</filename> is located, use the following command:</para>
+ <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>php4 -i | fgrep php.ini</userinput>
+$ <userinput>php5 -i | fgrep php.ini</userinput>
</screen>
</listitem>
</orderedlist>
</section>
<section id="web-server">
<title>Configuring the Web Server (Apache)</title>
- <para>First, 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>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.</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>
</Location>
</programlisting>
<note>
- <para>If you use Apache 2, you may need to use a different configuration. Usually, this is not neede.</para>
+ <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>
<listitem>
<para>Set up PHP module:</para>
<programlisting>
-php_flag register_globals On
-php_flag gpc_magic_quotes On
+php_flag register_globals Off
+php_flag magic_quotes_gpc On
php_flag files_uploads On
php_value include_path ".:/etc/gforge:<replaceable>/var/www/gforge</replaceable>:<replaceable>/var/www/gforge</replaceable>/www/include"
php_value default_charset "UTF-8"
</programlisting>
</listitem>
</orderedlist>
- <para>Of couse, all changes will take effect only after reloading or restarting Apache.</para>
- <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>Declare new zone in <literal>gforge.<replaceable>company.com</replaceable></literal> zone:</para>
-<programlisting>
-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>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>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>Reload BIND and test if all works:</para>
-<screen>
-$ <userinput>host test.projects.gforge.<replaceable>company.com</replaceable></userinput>
-</screen>
- </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> (<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>
-#
-# 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 *.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>
- <note>
- <para><filename>cronjobs/cvs-cron/usergroup.php</filename> creates <filename>index.php</filename> file in Web directory (<filename class="directory">htdocs</filename>) of project but the above configuration disables PHP.</para>
- </note>
- </section>
- </section>
+ <para>Of course, all changes will take effect only after reloading or restarting Apache.</para>
</section>
<section>
<title>Configuring Mail Transport Agent (Any)</title>
<listitem>
<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>
-# <replaceable>/usr/lib/mailman/bin</replaceable>/newlist mailman
+# <userinput><replaceable>/usr/lib/mailman/bin</replaceable>/newlist mailman</userinput>
</screen>
</listitem>
<listitem>
<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>.</para>
+ <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>Don't use ugly <literal>cgi-bin</literal> as part of URLs.</para>
+ <para>Strip ugly <literal>cgi-bin</literal> from URLs in configuration parameters.</para>
</listitem>
</itemizedlist>
</listitem>
<programlisting>
<VirtualHost <replaceable>1.2.3.4</replaceable>>
ServerName lists.gforge.<replaceable>company.com</replaceable>
- ServerAdmin mailman@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
DirectoryIndex index.html
ScriptAlias /mailman/ <replaceable>/usr/lib/cgi-bin/mailman/</replaceable>
Alias /pipermail/ <replaceable>/var/lib</replaceable>/mailman/archives/public/
- Alias /doc/ <replaceable>usr/share/images/mailman/</replaceable>
+ Alias /images/ <replaceable>/usr/share/images/</replaceable>
</VirtualHost>
</programlisting>
<note>
</orderedlist>
<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>
+ <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>
# <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>Cron Jobs</title>
</para>
<para>Prepare for <filename>cronjobs/cvs-cron/usergroup.php</filename> and <filename>cronjobs/mail/mailaliases.php</filename>.</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
+# <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>
</para>
</warning>
<screen>
-# crontab cronjobs/crontab.in
+# <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>
-# crontab -e
+# <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>
<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>
-$ psql -U gforge gforge
-gforge=> SELECT user_id FROM users WHERE user_name='<replaceable>YOUR USER NAME</replaceable>';
+$ <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>
</listitem>
<listitem>
</screen>
</listitem>
</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>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>Create <filename class="directory">/etc/gforge/custom</filename> directory.</para>
+ </listitem>
+ <listitem>
+ <para>Set <varname>$sys_custom_path</varname> configuration variable to <filename class="directory">/etc/gforge/custom</filename>.</para>
+ </listitem>
+ <listitem>
+ <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>
+ </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>Declare new zone in <literal>gforge.<replaceable>company.com</replaceable></literal> zone:</para>
+<programlisting>
+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>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>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>Reload BIND and test if all works:</para>
+<screen>
+$ <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>
+ </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>
+#
+# 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>
+ <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>
+<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>
+ </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>
+ </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><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.11, replace <literal>%1{sVv}</literal> in <filename><replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron/cvs.php</filename> with <literal>%{sVv}</literal>, and replace <filename>syncmail</filename> with updated version:</para>
-<screen>
-# <userinput>cd <replaceable>/var/www/gforge</replaceable></userinput>
-# <userinput>cp plugins/scmcvs/bin/syncmail-cvs-1.11 cronjobs/cvs-cron/syncmail</userinput>
-</screen>
- <para>If you are using CVS 1.12, replace <literal>%1{sVv}</literal> in <filename><replaceable>/var/www/gforge</replaceable>/cronjobs/cvs-cron/cvs.php</filename> with <literal>%s</literal>, and replace <filename>syncmail</filename> with updated version:</para>
+ <para>If you are using CVS 1.12, replace <filename>syncmail</filename> with updated version.</para>
<screen>
# <userinput>cd <replaceable>/var/www/gforge</replaceable></userinput>
# <userinput>cp plugins/scmcvs/bin/syncmail-cvs-1.12 cronjobs/cvs-cron/syncmail</userinput>
</screen>
+ <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>
<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>If you want to use checkout of svmcvs plugin, copy it:</para>
-<screen>
-# <userinput>mkdir <replaceable>/var/www/gforge</replaceable>/plugins/scmcvs</userinput>
-# <userinput>cp -R <replaceable>gforge-plugin-scmcvs</replaceable>/* <replaceable>/var/www/gforge</replaceable>/plugins/scmcvs</userinput>
-
-# <userinput>mkdir <replaceable>/var/www/gforge</replaceable>/www/plugins/scmcvs</userinput>
-# <userinput>cp -R <replaceable>gforge-plugin-scmcvs</replaceable>/www/* <replaceable>/var/www/gforge</replaceable>/www/plugins/scmcvs</userinput>
</screen>
</listitem>
<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>/home/chroot/cvsroot/</replaceable>'],
+'gforge' => ['GForge-CVS', '<replaceable>/cvsroot/</replaceable>'],
</screen>
</listitem>
<listitem>
</section>
<section>
<title>Installation</title>
- <programlisting>
-#copy the cvstracker config files to /etc/gforge/
-cd <replaceable>/var/www/gforge</replaceable>/plugins/cvstracker/
-cp -R etc/plugins/cvstracker/ /etc/gforge/plugins/
-mkdir <replaceable>/var/www/gforge</replaceable>/www/plugins/cvstracker/
-cp -R www/* <replaceable>/var/www/gforge</replaceable>/www/plugins/cvstracker/
-</programlisting>
- <para><filename>plugins/cvstracker/bin/post.php</filename> is called on each commit and it needs the GForge configuration file <filename>local.inc</filename> so the latter should have relaxed permissions.</para>
+ <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>
- <para>Fix CVSTracker table:</para>
-<screen>
-ALTER TABLE public.plugin_cvstracker_data_master DROP cvs_date;
-ALTER TABLE public.plugin_cvstracker_data_master ADD cvs_date INT;
-ALTER TABLE public.plugin_cvstracker_data_master ALTER cvs_date SET NOT NULL;
-</screen>
+ <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>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>
</note>
<programlisting>
#Create default location for SVN repositories
-mkdir /var/svn
+mkdir /svnroot
# Optional - Set up some basic files for SVN-over-DAV only
mkdir /var/www/svn
<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 not being found.</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>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>