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. CVSWEB and ViewCVS (used for
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)
36 IPC Run for Perl may be required on some platforms and is hard to find:
37 https://gforge.org/frs/download.php/143/IPC-Run-0.78.tar.gz
39 ViewCVS (now called ViewVC)
40 http://gforge.org/frs/download.php/152/viewvc-1.0-dev-gforge.tar.bz2
46 GForge has a lot of different pieces touching a lot of different components
47 in the system. Cronjobs are required to maintain the system, touching lots
48 of files on a daily and hourly basis, including /etc/* system files.
50 The plugins that now manage the CVS and SVN functionality have made
51 installation slightly harder because even more files have to be moved into
52 place during installation.
54 The manual installation of gforge is documented below. Be sure to follow
55 each step carefully, check the forums for frequently asked questions,
56 and ask your Apache, mailman, and postgresql installation questions in the
57 corresponding mailing lists rather than on the gforge forums where little
63 CVS is now managed via the scmcvs plugin which is included in the
64 plugins/ directory in the tarball downloaded from gforge.org. Most
65 of the files in scmcvs are intended for auto-installation on debian
66 systems and DO NOT APPLY to the majority of users. The scmcvs plugin
67 is activated by default in the gforge.sql database.
69 Cronjobs for CVS are included in cronjobs/crontab.in, but are commented
70 out by default for your security. cronjobs/cvs-cron/* contains the files
71 that are executed hourly to build permissions and create blank cvs trees.
72 Make sure these files are executed as root, and have proper execution bits
73 set. Each of these cronjobs has configuration parameters which you may
74 have to edit manually the paths in those files for your specific system.
76 CVSWeb works easily on most platforms, if you follow the instructions
77 below, but the IPCRUN lib may be missing and hard to find. Download it
78 here: https://gforge.org/frs/download.php/143/IPC-Run-0.78.tar.gz
84 If you want to use GForge's svn-over-DAV support, apache2 and
85 mod_auth_gforge are required.
87 SVN is also managed via plugin - the scmsvn plugin is included and
88 activated by default in gforge.
90 To install mod_auth_gforge, download it from
91 http://gforge.org/frs/?group_id=128
93 The sample etc/gforge-httpd.conf.example file in this tarball contains
94 a COMPLETE AND WORKING vhost for subversion-over-dav. The gforge-install.sh
95 script will copy this to /etc/gforge/httpd.conf You may have to
96 alter the passwords and any other config options, but the sample config
97 shown has been used in dozens or even hundreds of installs and DOES WORK.
99 Cronjobs - the /cronjobs/dav-svn/create_svn.php creates blank repositories
100 for subversion. You will likely have to edit this file to get the proper
103 ViewCVS (ViewVC now) - this is used to browse the SVN repository.
104 A modified version of ViewVC can be downloaded from GForge.org here:
105 http://gforge.org/frs/download.php/152/viewvc-1.0-dev-gforge.tar.bz2
106 This should be built using the instructions ( ./viewcvs-install )
107 then the viewcvs.conf should be modified to recognize the svnroots
109 root_parents = /svnroot : svn
111 The docroot var in viewcvs.conf should also be set to the location that the
112 files will be accessible from the web:
114 docroot = /plugins/scmsvn/viewcvs/
116 The viewcvs.cgi should then be placed in the same location as your
117 cvsweb cgi (usually placed into /etc/gforge/). The /etc/gforge/local.inc
118 has a path to this cgi, set in the sys_path_to_scmweb='' variable. This
119 variable is shared with the cvs plugin as well, so that's why both cvsweb
120 and viewcvs.cgi must be in the same location. gforge-install.sh takes care
121 of this step if you have viewvc installed in /opt/viewvc
123 Finally, the /usr/lib/gforge/www/plugins/scmsvn/viewcvs/ directory should
124 be symlinked to the same location that you installed your viewvc/templates/docroot
125 gforge-install.sh takes care of this step if you have viewvc installed in /opt/viewvc
127 cd /usr/lib/gforge/www/plugins/scmsvn/
128 ln -s /opt/viewvc/templates/docroot viewcvs
135 # mod_vhost_alias is used by the
136 # <projectname>.projects.gforge.company.com vhosts
137 # which are commented out by default in the sample apache conf
139 LoadModule vhost_alias_module modules/mod_vhost_alias.so
142 # these modules are all needed for mod_auth_gforge
144 LoadModule dav_module modules/mod_dav.so
145 LoadModule dav_fs_module modules/mod_dav_fs.so
146 LoadModule dav_svn_module modules/mod_dav_svn.so
147 LoadModule authz_svn_module modules/mod_authz_svn.so
148 LoadModule auth_gforge_module modules/mod_auth_gforge.so
153 The cvstracker plugin allows for some integration between CVS
154 commits and the bug tracker and task manager. So, for example,
155 when you commit, you can reference bug and task IDs in your
156 commit message and have the commit linked to the corresponding
159 This works by having a script in the cvs server issue a POST
160 to the main website ( /plugins/cvstracker/newcommit.php )
162 See the plugins/cvstracker/README file for details. This
163 plugin is enabled by default in the gforge.sql database file.
164 As with the other plugins, you may manually place the config
165 files in /etc/gforge/plugins/cvstracker/ and uncomment the
166 cronjob in crontab.in.
168 You will also have to copy the newcommit.php file to your
169 gforge www/plugins/cvstracker/ dir
174 The cronjobs require the PHP CGI to be installed and the php.ini
175 file to be properly configured with your include_path OR edit the
176 crontab.in file to set your include path.
178 In addition, you may have to symlink /usr/bin/php to /usr/bin/php5,
179 which is where the cronjobs expect your PHP CGI to be located.
180 install-gforge.sh takes care of this step for you.
186 Mailman is needed to create and use mailing lists with gforge.
187 Mailman is frequently installed in /var/mailman/ and the sample
188 vhost shown below will work with this setup without any changes.
190 Cronjobs for mailman are located in cronjobs/mail/*
192 cronjobs/mail/mailing_lists_create.php is used obviously to
193 create new mailing lists. You may have to edit /etc/gforge/local.inc
194 to change the location of the mailman bin/ directory.
196 For all problems with mailman installation and use, contact
197 the mailman mailing lists for help.
206 BLANK DATABASE - FRESH INSTALL
207 ------------------------------
209 First, make sure you create a 'gforge' user at the unix command prompt:
213 Create a MySQL database for gforge, replace adminuser with the name of a user with database create privileges:
215 # mysqladmin -u adminuser -p create gforge
217 Create the MySQL user for GForge, replace password with the desired password for the gforge account.
219 # mysql -u adminuser -p -D gforge -e "grant all privileges on gforge.* to gforge@localhost identified by 'password'"
221 Logon as the GForge user
225 $ mysql -u gforge -p gforge < db/gforge-struct-mysql.sql
227 $ mysql -u gforge -p gforge < db/gforge-data-mysql.sql
229 Be sure to watch for any errors during import and check the
232 UPGRADING DATABASE - EXISTING INSTALL
233 -------------------------------------
235 You will upgrade your database from a prior version by applying
236 each database schema change, in order, and applying it only once.
237 Only apply the schema changes in the db/ folder that are dated
238 AFTER your currently installed version!!
240 This process will apply your upgrades. BE SURE TO WATCH FOR ERRORS!
242 $ mysql -u gforge -p gforge < db/mysql-XXXXXXXXXX.sql >> import.log
244 There may also be migration scripts that have to be run. In the
245 db/ folder, look for XXXXXXXXXXX.php scripts and run them AFTER
246 YOU HAVE SET THE .htaccess file for your include_path.
249 WEB SETUP - MANUAL INSTALLATION
250 -------------------------------
252 The following are sample commands commonly issued for a manual installation:
254 tar -xjf gforge-4.5.6.tar.bz2
258 # BEFORE RUNNING THIS, determine your apacheuser/group
259 # and pass it as an argument as shown below.
261 # Argument 1: the main hostname you want to use.
262 # Argument 2: the IP address that you are listening on
264 ./gforge-restricted.sh gforge.company.com 100.100.100.100
267 # jpgraph install - use the 1.9.1 version from gforge.org
271 $ tar -xzf jpgraph-1.9.1.tar.gz
273 $ mv jpgraph-1.9.1/src/* ~/jpgraph
275 #you will have to edit jpgraph.php to set USE_CACHE=false
276 $ vim ~/jpgraph/jpgraph.php
283 Add the following lines to the .htaccess file in your ~/gforge/lib/www directory.
284 The crontab.in file also can be modified to include this path as well.
286 php_value register_globals 1d
287 php_value magic_quotes_gpc 1
288 php_value file_uploads 1
289 php_value include_path = ".:~/gforge/lib/:~/gforge/lib/www/include/:~/gforge/etc/"
292 FRS - File Release System
293 -------------------------
295 FRS has been radically simplified, simply create a directory.
297 This directory will be referenced in the GForge Config File as $sys_upload_dir
303 Edit the ~/gforge/etc/local.inc and set any specific variables
304 like sys_default_domain and any paths to files that are not right
310 Site admins are anyone who is an admin of group_id=1
312 To give the first user "Site Admin" privileges, register a new user,
313 and confirm it via the email link. Then enter the following command
315 $ mkadmin.sh "new user name" -u gforge -p
322 This alias was already added by the gforge-install script:
330 Add yourself, and any others you wish, to the "Peer Ratings" project,
331 which should be at /projects/peerrating/ on the website. Make yourself
332 an "admin" of the project, and then proceed to "rate" other users on
335 Members of the "Peer Ratings" project, who are "admins" of the project
336 become the first trusted users. This is the only way to prime the pump
337 for the peer ratings system.
343 Cron jobs are in the cronjobs/ directory and the README file contains
344 a sample crontab. This gives you the basic cronjobs for updating
345 certain statistics and data on the site.
347 /cronjobs/cvs-cron/ contains scripts useful for creating blank cvs trees.
349 See /cronjobs/README.root for more info.
351 /cronjobs/mail/ contains files useful for the creation of new mailing
352 lists in mailman and creating the /etc/aliases file.
354 *********************************************************************
355 WARNING!!! the following command will blow away any existing crontab.
356 *********************************************************************
358 $ crontab cronjobs/crontab.in
360 Now edit the paths to the cron scripts:
364 IMPORTANT!!!! - the cvs-cron/usergroup.php cron script will meddle
365 with your /etc/passwd, /etc/group, and /etc/shadow files. By default,
366 this cron will save these files with a .new extension. You will have
367 to edit the cron script to remove the .new extension, but you must
368 make sure that it is properly generating your files or your server
371 Once you have manually run the usergroup.php file, look at the
372 /etc/*.new files and verify that they contain sensisble information.
373 When you are confident they are right, you can edit usergroup.php
374 to remove the .new extension and uncomment the cronjobs.
380 The installation was shown above. Be sure to use the 1.9.1 version
381 from gforge.org and set USE_CACHE=false as shown here.
383 DEFINE("USE_CACHE",false);
389 Q: I get a blank page when I visit http://gforge.company.com/
391 A: Most often you are missing the php-mysqli library that lets PHP
392 talk to the MySQL database. Find a php-pgsql RPM or recompile
393 php to have pgql support.
395 If you're sure you have php-pgsql support, you can edit
396 common/include/database-mysql.php and remove the @ symbol from
401 So that it looks like:
405 This will let debug output dump to the screen and may let you find
406 the problem. Search the forums for more solutions.
409 Q: "Error Occurred In the Logger" or other database permission problems
411 A: As stated in the installation instructions, the database must be created,
412 owned, and accessed by the gforge user. This user is the only one who will
413 have total acess to all the tables. Any other user would have to be specifically
414 granted permissions with the GRANT commands in postgres.
417 Q: Reporting or time tracking doesn't work
419 A: Go to the reporting tab and scroll down so you can choose
420 "Initialize/Rebuild Reporting Tables"
422 You may also be missing GD support or be missing JPGraph or have it installed
423 improperly. The jpgraph/src/ directory should be specified accurately in your
424 local.inc file, and you should include a / at the end of the path specified.
425 In addition, you should modify jpgraph.php to set USE_CACHE=false
428 Q: How do I upgrade my database?
430 A: As stated above, you must apply the changes that are listed in date order
431 in the db/ directory to your database. Only the changes that are not already
432 in your old db/ directory should be applied, and they should be applied and
436 Q: I'm getting an error about BaseLanguage.class.php not being found.
438 A: Make sure your localization path is correctly specified in the local.inc
439 file and that it is readable AND writable by the apache user.
442 Q: When I click on "/projects/" or "/users/" links, I get the source code
443 instead of the page I expected.
445 A: As shown in the example httpd.conf files above, you may have to switch
446 to using the <Files> or <Location> directives depending on your server
450 Q: How do I backup GForge?
452 A: The only proper way to backup the gforge database is with pg_dump.
453 Any attempt to backup the filesystem while pgsql is running will result
454 in a useless and corrupt backup. You can backup CVS trees using tar as
455 long as they are not actively and heavily used during the backup.
456 Mailman and the FRS uploads dir can also be backed up with tar.
459 Q: Any time i enter an apostrophe in a text box, i get a parse error
461 A: As stated in the instructions above, you should have magic_quotes_gpc=On
465 Q: Large uploads into FRS or the doc manager fail.
467 A: Apache and the php.ini file need to have upload limits and possibly
468 memory limits increased.