1 Installation of GForge is a non-trivial undertaking, since it integrates
2 with so many different components across your system. A skilled sysadmin
3 is required to pull it off, or at the least a great deal of patience.
5 The result of a complete installation means automatic creation of CVS
6 and Subversion repositories, and having access to them controlled by
7 GForge and stats gathered from them. ViewCVS (used for CVS and
8 Subversion browsing) are two additional integration points.
11 * PROFESSIONAL SUPPORT
13 * If you need professional installation, support, etc:
14 * http://gforgegroup.com/
17 BASICS OF INSTALLATION
18 ----------------------
26 Optional (but highly recommended)
27 PHP Accelerator ( http://www.php-accelerator.co.uk/ )
29 Optional Gantt Charting and Graphing Support:
30 JPGraph: ( http://www.aditus.nu/jpgraph/ )
32 (NOTE: An older version of JPGraph may be
33 required - it can be downloaded here:
34 http://gforge.org/frs/download.php/142/jpgraph-1.9.1.tar.gz)
40 GForge has a lot of different pieces touching a lot of different components
41 in the system. Cronjobs are required to maintain the system, touching lots
42 of files on a daily and hourly basis, including /etc/* system files.
44 The plugins that now manage the CVS and SVN functionality have made
45 installation slightly harder because even more files have to be moved into
46 place during installation.
48 The manual installation of gforge is documented below. Be sure to follow
49 each step carefully, check the forums for frequently asked questions,
50 and ask your Apache, mailman, and postgresql installation questions in the
51 corresponding mailing lists rather than on the gforge forums where little
57 CVS is now managed via the scmcvs plugin which is included in the
58 plugins/ directory in the tarball downloaded from gforge.org. Most
59 of the files in scmcvs are intended for auto-installation on debian
60 systems and DO NOT APPLY to the majority of users. The scmcvs plugin
61 is activated by default in the gforge.sql database.
63 Cronjobs for CVS are included in cronjobs/crontab.in, but are commented
64 out by default for your security. cronjobs/cvs-cron/* contains the files
65 that are executed hourly to build permissions and create blank cvs trees.
66 Make sure these files are executed as root, and have proper execution bits
67 set. Each of these cronjobs has configuration parameters which you may
68 have to edit manually the paths in those files for your specific system.
74 If you want to use GForge's svn-over-DAV support and apache2 are
77 SVN is also managed via plugin - the scmsvn plugin is included and
78 activated by default in gforge.
80 The sample etc/gforge-httpd.conf.example file in this tarball contains
81 a COMPLETE AND WORKING vhost for subversion-over-dav. The gforge-install.sh
82 script will copy this to /etc/gforge/httpd.conf You may have to
83 alter the passwords and any other config options, but the sample config
84 shown has been used in dozens or even hundreds of installs and DOES WORK.
89 The cvstracker plugin allows for some integration between CVS
90 commits and the bug tracker and task manager. So, for example,
91 when you commit, you can reference bug and task IDs in your
92 commit message and have the commit linked to the corresponding
95 This works by having a script in the cvs server issue a POST
96 to the main website ( /plugins/cvstracker/newcommit.php )
98 See the plugins/cvstracker/README file for details. This
99 plugin is enabled by default in the gforge.sql database file.
100 As with the other plugins, you may manually place the config
101 files in /etc/gforge/plugins/cvstracker/ and uncomment the
102 cronjob in crontab.in.
107 The cronjobs require the PHP CGI to be installed and the php.ini
108 file to be properly configured with your include_path OR edit the
109 crontab.in file to set your include path.
111 In addition, you may have to symlink /usr/bin/php to /usr/bin/php5,
112 which is where the cronjobs expect your PHP CGI to be located.
118 Mailman is needed to create and use mailing lists with gforge.
119 Mailman is frequently installed in /var/mailman/ and the sample
120 vhost shown below will work with this setup without any changes.
122 Cronjobs for mailman are located in cronjobs/mail/*
124 cronjobs/mail/mailing_lists_create.php is used obviously to
125 create new mailing lists. You may have to edit /etc/gforge/local.inc
126 to change the location of the mailman bin/ directory.
128 For all problems with mailman installation and use, contact
129 the mailman mailing lists for help.
138 BLANK DATABASE - FRESH INSTALL
139 ------------------------------
141 First, make sure you create a 'gforge' user at the unix command prompt:
145 Then create a postgres account for gforge:
147 [root]# su - postgres
149 [postgres]# createuser -A -d -E -P gforge
151 and enter the password for the user.
153 You may also need to add Pl/Pgsql as a language. To do so:
155 [postgres]$ createlang plpgsql template1
160 [gforge]# createdb gforge
161 [gforge]# psql gforge < db/gforge.sql > import.log
163 Be sure to watch for any errors during import and check the
164 import.log file. For postgresql 7.3 users, you will have to
165 use the db/gforge-pgsql7.3.sql file, since the postgres team
166 has broken compatibility between releases yet again.
168 Now, find your pg_hba.conf file and edit it to include this line:
172 You will have to restart postgresql after changing this line so it can
173 pick up your configuration change. Usually you can restart by
175 [root]# /etc/init.d/postgresql restart
178 UPGRADING DATABASE - EXISTING INSTALL
179 -------------------------------------
181 To migrate to a newer version of GForge, you must import
182 your old database, FRS files, mailing lists, cvs and svn trees
183 into your new installation.
185 1) Completely install your new system
186 2) Move the mentioned files into place
187 3) Import your old database
188 4) go into the gforge/db directory and choose 'startpoint.php 4.0.2'
189 as the starting point of the installation (4.0.2 is an example)
190 5) ./upgrade-db.php - this script will run the updates in order.
191 If any of them fail, it will prompt you to continue. Generally,
192 you should always continue. Most are minor or informational errors.
195 WEB SETUP - MANUAL INSTALLATION
196 -------------------------------
198 The following are sample commands commonly issued for a manual installation:
200 tar -xjf gforge-4.5.6.tar.bz2
204 # BEFORE RUNNING THIS, determine your apacheuser/group
205 # and pass it as an argument as shown below.
207 # Argument 1: the main hostname you want to use.
208 # Argument 2: the apache user
209 # Argument 3: the apache group
210 # Argument 3: the IP address that you are listening on
212 ./gforge-install.sh gforge.company.com apacheuser apachegroup
215 # jpgraph install - use the 1.9.1 version from gforge.org
218 tar -xzf jpgraph-1.9.1.tar.gz
219 mv jpgraph-1.9.1/src/* /opt/jpgraph/
221 #you will have to edit jpgraph.php to set USE_CACHE=false
222 vim /opt/jpgraph/jpgraph.php
224 Apache will need to have a line added to its httpd.conf:
226 Include /etc/gforge/httpd.conf
228 Restart apache when you are done editing the file so the
229 changes can be picked up.
235 You may also add the include_path to the php.ini, as it will be
236 necessary for your php cgi to run the cron jobs.
238 register_globals = Off
239 magic_quotes_gpc = On
241 include_path = ".:/opt/gforge/gforge/:/opt/gforge/gforge/www/include/:/etc/gforge/"
243 PHP CLI that is used by crontab.in may use different php.ini. Find
244 it by running the following command and add the above include_path
247 $ /usr/bin/php5 -i | fgrep php.ini
250 FRS - File Release System
251 -------------------------
253 FRS has been radically simplified. Simply create a directory and make
254 it owned by the webserver-user. Usually "chown -R apache:apache mydir"
257 This directory will be referenced in the GForge Config File as $sys_upload_dir
263 Edit the /etc/gforge/local.inc and set any specific variables
264 like sys_default_domain and any paths to files that are not right
270 Site admins are anyone who is an admin of group_id=1
272 To give the first user "Site Admin" privileges, register a new user,
273 and confirm it via the email link. Then enter the postgres command
274 line and issue these commands:
276 [gforge]# psql gforge
278 psql> SELECT user_id FROM users WHERE user_name='******MY NEW USERNAME*********';
280 The result of that query will be put into this next query:
282 psql> insert into user_group (user_id,group_id,admin_flags) values (*****YOUR NEW NUMERIC USER ID*****,1,'A');
288 This alias was already added by the gforge-install script:
296 Add yourself, and any others you wish, to the "Peer Ratings" project,
297 which should be at /projects/peerrating/ on the website. Make yourself
298 an "admin" of the project, and then proceed to "rate" other users on
301 Members of the "Peer Ratings" project, who are "admins" of the project
302 become the first trusted users. This is the only way to prime the pump
303 for the peer ratings system.
309 Cron jobs are in the cronjobs/ directory and the README file contains
310 a sample crontab. This gives you the basic cronjobs for updating
311 certain statistics and data on the site.
313 /cronjobs/cvs-cron/ contains scripts useful for creating blank cvs
314 trees and managing the /etc/groups /etc/passwd and /etc/shadow files.
315 See /cronjobs/README.root for more info.
317 /cronjobs/mail/ contains files useful for the creation of new mailing
318 lists in mailman and creating the /etc/aliases file.
320 **************************************************************************
321 WARNING!!! the following command will blow away any existing root crontab.
322 **************************************************************************
324 [root]# crontab cronjobs/crontab.in
326 Now edit the paths to the cron scripts:
330 IMPORTANT!!!! - the cvs-cron/usergroup.php cron script will meddle
331 with your /etc/passwd, /etc/group, and /etc/shadow files. By default,
332 this cron will save these files with a .new extension. You will have
333 to edit the cron script to remove the .new extension, but you must
334 make sure that it is properly generating your files or your server
337 Once you have manually run the usergroup.php file, look at the
338 /etc/*.new files and verify that they contain sensisble information.
339 When you are confident they are right, you can edit usergroup.php
340 to remove the .new extension and uncomment the cronjobs.
346 The installation was shown above. Be sure to use the 1.9.1 version
347 from gforge.org and set USE_CACHE=false as shown here.
349 DEFINE("USE_CACHE",false);
355 Q: I get a blank page when I visit http://gforge.company.com/
357 A: Most often you are missing the php-pgsql library that lets PHP
358 talk to the postgres database. Find a php-pgsql RPM or recompile
359 php to have pgql support.
361 If you're sure you have php-pgsql support, you can edit
362 common/include/database.php and remove the @ symbol from
367 So that it looks like:
371 This will let debug output dump to the screen and may let you find
372 the problem. Search the forums for more solutions.
375 Q: "Error Occurred In the Logger" or other database permission problems
377 A: As stated in the installation instructions, the database must be created,
378 owned, and accessed by the gforge user. This user is the only one who will
379 have total acess to all the tables. Any other user would have to be specifically
380 granted permissions with the GRANT commands in postgres.
383 Q: Reporting or time tracking doesn't work
385 A: Go to the reporting tab and scroll down so you can choose
386 "Initialize/Rebuild Reporting Tables"
388 You may also be missing GD support or be missing JPGraph or have it installed
389 improperly. The jpgraph/src/ directory should be specified accurately in your
390 local.inc file, and you should include a / at the end of the path specified.
391 In addition, you should modify jpgraph.php to set USE_CACHE=false
394 Q: How do I upgrade my database?
396 A: As stated above, you must apply the changes that are listed in date order
397 in the db/ directory to your database. Only the changes that are not already
398 in your old db/ directory should be applied, and they should be applied and
402 Q: I'm getting an error about BaseLanguage.class.php not being found.
404 A: Make sure your localization path is correctly specified in the local.inc
405 file and that it is readable AND writable by the apache user.
408 Q: When I click on "/projects/" or "/users/" links, I get the source code
409 instead of the page I expected.
411 A: As shown in the example httpd.conf files above, you may have to switch
412 to using the <Files> or <Location> directives depending on your server
416 Q: How do I backup GForge?
418 A: The only proper way to backup the gforge database is with pg_dump.
419 Any attempt to backup the filesystem while pgsql is running will result
420 in a useless and corrupt backup. You can backup CVS trees using tar as
421 long as they are not actively and heavily used during the backup.
422 Mailman and the FRS uploads dir can also be backed up with tar.
425 Q: Any time i enter an apostrophe in a text box, i get a parse error
427 A: As stated in the instructions above, you should have magic_quotes_gpc=On
431 Q: Large uploads into FRS or the doc manager fail.
433 A: Apache and the php.ini file need to have upload limits and possibly
434 memory limits increased.