1 Installation of FusionForge 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 FusionForge and stats gathered from them. ViewCVS (used for CVS and
8 Subversion browsing) are two additional integration points.
10 BASICS OF INSTALLATION
11 ----------------------
14 For Ubuntu/Debian system, you should use the debian packaging, see
15 the fusionforge.org website for the correct instructions.
17 For an installation on CentOS or Red Hat, use the following command.
19 install.sh <hostname with domain>
21 That will install the bulk of the system and even set up a site admin
26 The information below may not be necessary if you succeeded installing
27 using the above method. However this info may give you an overview
28 of how the installation is done.
37 FusionForge has a lot of different pieces touching a lot of different components
38 in the system. Cronjobs are required to maintain the system, touching lots
39 of files on a daily and hourly basis, including /etc/* system files.
41 The plugins that now manage the CVS and SVN functionality have made
42 installation slightly harder because even more files have to be moved into
43 place during installation.
45 The manual installation of fusionforge is documented below. Be sure to follow
46 each step carefully, check the forums for frequently asked questions,
47 and ask your Apache, mailman, and postgresql installation questions in the
48 corresponding mailing lists rather than on the gforge forums where little
54 CVS is now managed via the scmcvs plugin which is included in the
55 plugins/ directory in the tarball downloaded from gforge.org. Most
56 of the files in scmcvs are intended for auto-installation on debian
57 systems and DO NOT APPLY to the majority of users. The scmcvs plugin
58 is activated by default in the gforge.sql database.
60 Cronjobs for CVS are included in cronjobs/crontab.in, but are commented
61 out by default for your security. cronjobs/cvs-cron/* contains the files
62 that are executed hourly to build permissions and create blank cvs trees.
63 Make sure these files are executed as root, and have proper execution bits
64 set. Each of these cronjobs has configuration parameters which you may
65 have to edit manually the paths in those files for your specific system.
71 If you want to use GForge's svn-over-DAV support and apache2 are
74 SVN is also managed via plugin - the scmsvn plugin is included and
75 activated by default in gforge.
77 The sample etc/gforge-httpd.conf.example file in this tarball contains
78 a COMPLETE AND WORKING vhost for subversion-over-dav. The gforge-install.sh
79 script will copy this to /etc/gforge/httpd.conf You may have to
80 alter the passwords and any other config options, but the sample config
81 shown has been used in dozens or even hundreds of installs and DOES WORK.
86 The cvstracker plugin allows for some integration between CVS
87 commits and the bug tracker and task manager. So, for example,
88 when you commit, you can reference bug and task IDs in your
89 commit message and have the commit linked to the corresponding
92 This works by having a script in the cvs server issue a POST
93 to the main website ( /plugins/cvstracker/newcommit.php )
95 See the plugins/cvstracker/README file for details. This
96 plugin is enabled by default in the gforge.sql database file.
97 As with the other plugins, you may manually place the config
98 files in /etc/gforge/plugins/cvstracker/ and uncomment the
99 cronjob in crontab.in.
104 The cronjobs require the PHP CGI to be installed and the php.ini
105 file to be properly configured with your include_path OR edit the
106 crontab.in file to set your include path.
111 Mailman is needed to create and use mailing lists with gforge.
112 Mailman is frequently installed in /var/mailman/ and the sample
113 vhost shown below will work with this setup without any changes.
115 Cronjobs for mailman are located in cronjobs/mail/*
117 cronjobs/mail/mailing_lists_create.php is used obviously to
118 create new mailing lists. You may have to edit /etc/gforge/local.inc
119 to change the location of the mailman bin/ directory.
121 For all problems with mailman installation and use, contact
122 the mailman mailing lists for help.
125 UPGRADING DATABASE - EXISTING INSTALL
126 -------------------------------------
128 To migrate to a newer version of GForge, you must import
129 your old database, FRS files, mailing lists, cvs and svn trees
130 into your new installation.
132 1) Completely install your new system
133 2) Move the mentioned files into place
134 3) Import your old database
135 4) go into the gforge/db directory and choose 'startpoint.php 4.0.2'
136 as the starting point of the installation (4.0.2 is an example)
137 5) ./upgrade-db.php - this script will run the updates in order.
138 If any of them fail, it will prompt you to continue. Generally,
139 you should always continue. Most are minor or informational errors.
142 WEB SETUP - MANUAL INSTALLATION
143 -------------------------------
145 The following are sample commands commonly issued for a manual installation:
147 tar -xjf gforge-X.X.tar.bz2
151 # BEFORE RUNNING THIS, determine your apacheuser/group
152 # and pass it as an argument as shown below.
154 # Argument 1: the main hostname you want to use.
155 # Argument 2: the apache user
156 # Argument 3: the apache group
157 # Argument 3: the IP address that you are listening on
159 ./gforge-install.sh gforge.company.com apacheuser apachegroup
161 Apache will need to have a line added to its httpd.conf:
163 Include /etc/gforge/httpd.conf
165 Restart apache when you are done editing the file so the
166 changes can be picked up.
172 You may also add the include_path to the php.ini, as it will be
173 necessary for your php cgi to run the cron jobs.
175 register_globals = Off
176 magic_quotes_gpc = Off
178 include_path = ".:/opt/gforge/gforge/:/opt/gforge/gforge/www/include/:/etc/gforge/"
180 PHP CLI that is used by crontab.in may use different php.ini. Find
181 it by running the following command and add the above include_path
184 $ /usr/bin/php -i | fgrep php.ini
187 FRS - File Release System
188 -------------------------
190 FRS has been radically simplified. Simply create a directory and make
191 it owned by the webserver-user. Usually "chown -R apache:apache mydir"
194 This directory will be referenced in the GForge Config File as $sys_upload_dir
200 Edit the /etc/gforge/local.inc and set any specific variables
201 like sys_default_domain and any paths to files that are not right
207 Site admins are anyone who is an admin of group_id=1
209 To give the first user "Site Admin" privileges, register a new user,
210 and confirm it via the email link. Then enter the postgres command
211 line and issue these commands:
213 [gforge]# psql gforge
215 psql> SELECT user_id FROM users WHERE user_name='******MY NEW USERNAME*********';
217 The result of that query will be put into this next query:
219 psql> insert into user_group (user_id,group_id,admin_flags) values (*****YOUR NEW NUMERIC USER ID*****,1,'A');
225 This alias was already added by the gforge-install script:
233 Add yourself, and any others you wish, to the "Peer Ratings" project,
234 which should be at /projects/peerrating/ on the website. Make yourself
235 an "admin" of the project, and then proceed to "rate" other users on
238 Members of the "Peer Ratings" project, who are "admins" of the project
239 become the first trusted users. This is the only way to prime the pump
240 for the peer ratings system.
246 Cron jobs are in the cronjobs/ directory and the README file contains
247 a sample crontab. This gives you the basic cronjobs for updating
248 certain statistics and data on the site.
250 /cronjobs/cvs-cron/ contains scripts useful for creating blank cvs
251 trees and managing the /etc/groups /etc/passwd and /etc/shadow files.
252 See /cronjobs/README.root for more info.
254 /cronjobs/mail/ contains files useful for the creation of new mailing
255 lists in mailman and creating the /etc/aliases file.
257 **************************************************************************
258 WARNING!!! the following command will blow away any existing root crontab.
259 **************************************************************************
261 [root]# crontab cronjobs/crontab.in
263 Now edit the paths to the cron scripts:
267 IMPORTANT!!!! - the cvs-cron/usergroup.php cron script will meddle
268 with your /etc/passwd, /etc/group, and /etc/shadow files. By default,
269 this cron will save these files with a .new extension. You will have
270 to edit the cron script to remove the .new extension, but you must
271 make sure that it is properly generating your files or your server
274 Once you have manually run the usergroup.php file, look at the
275 /etc/*.new files and verify that they contain sensisble information.
276 When you are confident they are right, you can edit usergroup.php
277 to remove the .new extension and uncomment the cronjobs.
283 For XHTML validation against the DTD, the following files must be
284 placed under the gforge/common/include/ directory:
289 * xhtml1-transitional.dtd
290 They can be downloaded from http://www.w3.org/TR/xhtml1/dtds.html
291 as tarball (xhtml1.tgz).
293 Installation of xmlstarlet is also required.
298 Q: I get a blank page when I visit http://gforge.company.com/
300 A: Most often you are missing the php-pgsql library that lets PHP
301 talk to the postgres database. Find a php-pgsql RPM or recompile
302 php to have pgql support.
304 If you're sure you have php-pgsql support, you can edit
305 common/include/database-pgsql.php and remove the @ symbol from
310 So that it looks like:
314 This will let debug output dump to the screen and may let you find
315 the problem. Search the forums for more solutions.
318 Q: "Error Occurred In the Logger" or other database permission problems
320 A: As stated in the installation instructions, the database must be created,
321 owned, and accessed by the gforge user. This user is the only one who will
322 have total acess to all the tables. Any other user would have to be specifically
323 granted permissions with the GRANT commands in postgres.
326 Q: Reporting or time tracking doesn't work
328 A: Go to the reporting tab and scroll down so you can choose
329 "Initialize/Rebuild Reporting Tables"
331 Q: How do I upgrade my database?
333 A: As stated above, you must apply the changes that are listed in date order
334 in the db/ directory to your database. Only the changes that are not already
335 in your old db/ directory should be applied, and they should be applied and
339 Q: I'm getting an error about BaseLanguage.class not being found.
341 A: Make sure your localization path is correctly specified in the local.inc
342 file and that it is readable AND writable by the apache user.
345 Q: When I click on "/projects/" or "/users/" links, I get the source code
346 instead of the page I expected.
348 A: As shown in the example httpd.conf files above, you may have to switch
349 to using the <Files> or <Location> directives depending on your server
353 Q: How do I backup GForge?
355 A: The only proper way to backup the gforge database is with pg_dump.
356 Any attempt to backup the filesystem while pgsql is running will result
357 in a useless and corrupt backup. You can backup CVS trees using tar as
358 long as they are not actively and heavily used during the backup.
359 Mailman and the FRS uploads dir can also be backed up with tar.
362 Q: Large uploads into FRS or the doc manager fail.
364 A: Apache and the php.ini file need to have upload limits and possibly
365 memory limits increased.