To install GForge, follow these steps:

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 db/ folder that are dated after your existing installation.

There may also be migration scripts that have to be run. In the db/ folder, looked for migrate-*.php scripts and run them.

Verify the version of PHP installed on your system: php -v

<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>

In the GForge distribution, you will find etc/local.inc. Move it to /etc/gforge/local.inc and edit all of the settings.

Usually, you will want to make it readable only by webserver user (e.g. apache):

# chown -R apache:apache /etc/gforge/
# chmod 600 /etc/gforge/local.inc

Add the following line to /etc/aliases and run newaliases:

noreply: /dev/null

Create a directory (e.g. /var/lib/gforge/download) and make it owned by the webserver user (e.g. apache). Usually chown -R apache:apache /var/lib/gforge/download will do the trick. This directory will be referenced in the GForge Config File /etc/gforge/local.inc as $sys_upload_dir.

You can download the latest official CVSWeb release from http://www.freebsd.org/projects/cvsweb.html but you should consider using the one bundled in GForge SCMCVS plugin.

Copy the tar.gz file into a tmp directory and unzip it:

tar -zxvf cvsweb.tar.gz

CVSWeb consists of a Perl script (cvsweb.cgi), a configuration file (cvsweb.conf), and some icons (back.gif, dir.gif, etc).

Possible problems:

Create in httpd.conf virtual host for viewing of CVSWeb:

<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>

GNU Mailman is used to help manage the GForge mailing lists. To install it:

Install a GNU Mailman package or compile it

su to root and set the Mailman password

Create in httpd.conf virtual host for Mailman, adjusting ScriptAlias and Alias directives:

<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>

Run the script gforge/cronjobs/mail/mailing_lists_create.php; 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 -f flag, i.e.:

# php -f mailing_lists_create.php

GForge uses CVS via pserver for anonymous read only access and ext for developers to commit to the repositories. To set it up:

Download and install the latest CVS package for your distribution.

Ensure the following info is in /etc/services:

$ grep cvspserver /etc/services
cvspserver      2401/tcp                        # CVS client/server operations
cvspserver      2401/udp                        # CVS client/server operations

Ensure the following info is in /etc/xinetd.d/cvspserver (if it doesn't exist, create a new file with the following text to enable anonymous access):

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
}

Now add an anonymous user to your system with a blank password, or one of anonymous

Cron jobs are in the cronjobs/ directory and the README file contains a sample crontab. This gives you the basic cronjobs for updating certain statistics and data on the site.

cronjobs/cvs-cron/ contains scripts useful for creating blank cvs trees and managing the /etc/groups, /etc/passwd and /etc/shadow files. See cronjobs/README.root for more info.

cronjobs/mail/ contains files useful for the creation of new mailing lists in mailman and creating the /etc/aliases file.

# 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

# crontab cronjobs/crontab.in

Now edit the paths to the cron scripts by setting the value of $GFORGE:

# crontab -e

PHP must be compiled with --with-gd, or appropriate package must be installed. Extra fonts for JPGraph are not necessary. Be sure your /etc/gforge/local.inc file contains the proper path to the jpgraph/src/ directory.

When you get your preferred version of JPGraph installed, you will have to edit one setting in jpgraph.php:

DEFINE("USE_CACHE", false);

If you want to use some of the Perl scripts that access the database, you'll need the DBI and DBD::Pg Perl modules. On Red Hat systems (and variants), you can get them by installing the libdbi and libdbd-pgsql packages. On Debian systems (and variants), the packages are called libdbi-perl and libdbd-pg-perl.

You'll also need to install utils/include.pl to /usr/lib/gforge/lib/, and put some configuration variables into /etc/gforge/local.pl. In particular, you'll need something like the following in local.pl:

$sys_default_domain = 'gforge.company.com' ;
$sys_dbhost = '192.168.12.34' ;
$sys_dbname = 'gforge' ;
$sys_dbuser = 'gforge' ;
$sys_dbpasswd = 'p455w0rd' ;

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.

Once you have that user account, server, and password set up, just edit /etc/gforge/local.inc and add the information to the jabber section.

This section explains how to register as a new user, how to register a new project, how to login and how to logout.

This section describes the functions of GForge that are relative to the user's section.

This document describes the user's homepage, how to modify user settings, how to handle user ratings, skill profiles and Diary and Notes.

This section explains the project specific functions of the GForge software.

Connect with your browser to GForge. This can be either http://gforge.org or a locally-installed version of the software.

To register a new user, click on the New Account link on the top right side of the browser window.

To register as a user, you need to fill out the form with the following data:

To register a new project, connect to your GForge , login and go to My Page section. You have a Register Project link in the menu at the top of the page.

You need to insert the following information to register a project:

Click on the I agree button to register the project. Your project is now registered on GForge; but you cannot yet access it. It has to be approved from the site administrators.

When the project is approved, you'll receive an email from GForge confirming that the project is active.

You can login by clicking the Login link in the top-right border of the browser window.

The form requires that you insert your username and your password to access the site. If the data is correct, the user homepage will be displayed.

To log out from GForge, click on the Logout link on the top right of your browser window.

The User home page appears after the user has performed the login or when he clicks the My Page tab.

The User homepage contains a list of all open activities/tracker items:

When you click on Account Maintenance on your user homepage, you get a page where you can change some data you inserted. You can change every data you inserted when you registered as user except:

You can be rated by other users and you can rate other users. Every time you go to the detail of a user, you can rate the user.

Ratings can be given for:

In this section you can add your skills. You can set your skills profile to public, so everyone can see it, or to private, so that only you can view it.

The information that you can insert is:

The Diary and Notes section allows you to simulate a basic agenda. You can insert a subject and a description of the item and select if the item is public or private.

If the item is public, every user of GForge can view and monitor this item.

The project summary shows summarized information about the current project. The following information is displayed:

The Project Administration section allows you to administer the project.

Every project can have his own discussion forums. When a new project is created, 3 forums are automatically created:

This is where you will set up and administer the mailing lists associated with the project.

The Task Manager is similar to the tracker, with the following differences:

Tasks are organized in subprojects. Before inserting a new task, you must first create a subproject. You can use the Admin link to create new subprojects.

Tasks allows you to create and manage tasks, or blocks of work, similar to the way projects are broken down in eg MS Project.

The Document Manager provided with GForge gives you a simple way to publish documents on the site.

The news section allows you to insert news relative to your project. News can be monitored similar to tracker items, forums. News will be displayed on the project homepage and also on the site homepage, if the site administrators approve the news.

News are generally used to announce software releases, milestones, or significant changes in the software.

The CVS button shows a page that contains information on how to access the CVS repository. Use this information to configure your client for CVS access.

This page also displays some statistics about the selected project's CVS tree.

The Browse CVS Repository link opens the viewcvs web interface, where you can view the CVS repository, view differences between revisions, download versions of a file.

The side-wide functions are available anytime, they are not dependent on the single projects.

The site-wide functions handle data that are not relevant to a single project, as code fragments, project classification, project helps, etc.

The single site-wide functions available to the users are:

You can search in GForge for the following arguments:

You can search for People or Software groups by selecting the item in the combo box and inserting the search text in the text box.

If the user is inside one of the Trackers, a voice Tracker appears in the combo box.

If the user is inside a forum, a voice Forum appears in the combo box.

This allows users to classify their projects in a tree so that they can be found more easily.

The Snippet Library function of GForge is very interesting; it allows to collect all the type of information/knowledge which is not a complete piece of code and which is usually difficult to organize/share.

A typical example are sophisticated shell commands, javascript functions, perl one-liner, SQL expressions that perform special queries, an algorithm, etc.

This feature allows users to search for help for their projects.

You can check out the GForge CVS repository through anonymous CVS with the following instructions.

The module you wish to check out must be specified as the <modulename>. When prompted for a password for anonymous, simply press the Enter key.

export CVSROOT=:pserver:anonymous@cvs.gforge.org:/cvsroot/gforge
cvs login
cvs co <modulename>

The following CVS modules are available in GForge repository.

Coding Standards. Live them, love them.

Then come up with a new introduction...

In the GForge system, PHP itself is used as the template language. To make the templating clearer, template files should be separated out and included once objects and database results are established. Detailed examples are in the docs repository and here.

Variables in the templates are presented surrounded by <?php ?> tags instead of the {} tags that some other template libraries would use. The end result is the same, with less bloat and more efficient code.

Objects should generally be normalized similar to a database so they contain only the attributes that make sense.

Each object should have Error as the abstract parent object unless the object or its subclasses will never produce errors.

Each object should also have a create() method which does the work of inserting a new row into the database table that this object represents.

An update() method is also required for any objects that can be changed. Individual set() methods are generally not a good idea as doing separate updates to each field in the database is a performance bottleneck.

fetchData() and getId() are also standard in most objects. See the tracker codebase for specific examples.

Common sense about performance should be used when designing objects.

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated form:

if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

Control statements shall have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

You should use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

switch (condition) {
    case 1: {
        action1;
        break;
    }
    case 2: {
        action2;
        break;
    }
    default: {
        defaultaction;
        break;
    }
}

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once will not be included again by include_once.

include('pre.php');

The following code examples demonstrate how all coding on GForge is going to be done in the future. The first example shows the “switchbox” page (taken from www/tracker/index.php) - where the various objects are included, instantiated and checked for errors every step of the way.

Once the objects are instantiated, the template file can be included. In this example, the template file is detail.php (example2).

This short HOWTO explains how you can customize your local installation of GForge.

First, a quick course on the internationalisation system present in GForge.

The texts you can read on the web pages are not hard-coded. Instead, they are displayed as results of a function of several parameters. One of these parameters is the language in which you wish to display a piece of information, and another is some handle to identify the information you want to display. In GForge, this handle is made up of the “page name” and the “category” strings.

Knowing all the needed info, the function displays the appropriate text. How appropriate is this text? Well, that depends. First, a basic set of texts is loaded. Historically, this set is loaded in English. This set of texts makes the Base class, storing texts for all known “handles”.

This set of texts can then be partially or completely overloaded, e.g. for other languages: the handles present in the language overwrite the Base handles, and the ones not found keep their values from the Base class.

The language files are located in the www/include/languages directory.

The following languages are available in GForge :

You might consider translating GForge into your language. If you do so, please also consider submitting your translated file to us so that future releases of GForge include your translated file by default.

These are the steps to add a new language:

The *.tab files are in a fairly straightforward format. Lines starting with a '#' character are ignored, other lines must be in the following format:

<pagename> TAB <category> TAB <data>

The <data> field can use variables in the form $1, $2, etc. These variables are defined by the script and there's no simple way of knowing what they are apart from looking at the script itself. To find out exactly what these variables are filled out with, search for the getText('<pagename>','<category'>) string in the scripts contained in the www/ and common/. This is not always easy to do.

Your best bet is to guess the meaning of the $1, $2, etc. variables from the non-customized text (either Base.tab or Foobaric.tab if it is defined).

GForge is constantly developed and so translation files are regularly outdated. Thus translations should be regularly updated to be uptodate.

If you are maintaining a translation file, you may find useful language_file_merger.php script you can find in tools module (see GForge CVS repository for more information).

You can use the following command to merge your outdated language file with Base.tab :

php -q language_file_merger.php <your/gforge/install/root> <language> \
1>merge.tab 2>merge.log

You have to check lines with #TO_TRANSLATE# and #TO_REMOVE# flags and respectively translate them and remove them. Lines are already sorted by alphabetical order so you just have to add header information found in the previous YourLanguage.tab file to merge.tab file and replace YourLanguage.tab by merge.tab.

The text content can be somewhat customized. The GForge internationalisation system already provides a way to have different texts depending on user choice.

You might want to change page footers, or contact pages, or host names, or whatever you need to integrate your GForge your target audience (company, organisation, or even your own personal GForge).

The way you should usually go when you have to customize some text is the following: