INSTALLATION OF SAVANE: This file might change very often. Please make sure you have the most recent version. This installation instructions are still not complete. If you have any questions or run into trouble, please contact us at $Id$ * * * FRONTEND AND BACKEND? Savane is made of a PHP Frontend and a Perl Backend. The PHP Frontend is the web interface and the only way to interact with the database and trigger actions executed by the backend. The Perl Backend is a set of scripts that update a system (a set of machines) according to the informations entered in the database by the PHP Frontend. It is not necessary for bug tracking (for instance) because it only relies on the database. It is necessary for mailing lists or CVS because it needs to create directories and configure servers. In the following guide, the tag [BACKEND ONLY] designates information you can skip if you are only interested by the Frontend. * * * GETTING THE SOURCE CODE First, you must get a copy of Savane from the CVS tree located at http://gna.org/projects/savane In this guide, we will assume that your copy is in a directory called /usr/src/savane. Go in this directory: cd /usr/src/savane (if you use a different directory, keep that in mind every time we refer to /usr/src/savane below); The configure script will ask you several things required in order to proceed. You're not forced to choose /etc/savannah as configuration directory. If you choose something else (needed if you use concurrent Savane installation), be sure to set SAVANE_CONF enviroment variable, both in Apache and in terminals you use to call backend scripts. Note that whenever you are asked for a domain name, you should use a fully qualified domain name (like http://thishost.thisdomain.net). ./configure make It will build several minor parts (translation files etc...) * * * The second step is to create the database: make database * * * CONFFILES: The Savane configuration is made of two files: savane.conf.pl and .savane.conf.php. .savane.conf.php is generated from savane.conf.pl, and must not be edited manually. These files should be generated using the script sv_update_conf, for instance by typing: make conf This process may ask for input from user, depending on the informations provided at the configuration step. Each time savane.conf.pl is edited, run: make update-conf or run the script sv_update_conf to re-generate the .savane.conf.php file. * * * BACKEND INSTALLATION: make install will install backend scripts, even if you only use the frontend. Some backend scripts like sv_update_conf or sv_cleaner are required to maintain a Savane installation properly. Also, the translations files will be installed at this step. Note that translation will only work if your server is configured to accept different locales. On Debian, run `dpkg-reconfigure locales` to add more locales. * * * [BACKEND ONLY] CRONJOBS: You should edit your /etc/cron.d/savane to fit your needs. This single file runs all the backend jobs. Commands with --cron option will not be effective until you set them on in the configuration file. Remember that backend scripts need SAVANE_CONF to be set if the configuration directory is not /etc/savannah. * * * APACHE CONFIGURATION: First of all, note that you should be able to check your server setup at http://127.0.0.1/pathtosavane/testconfig.php. Warning: Make sure the env_module is being used by Apache. In the Apache configuration add the following: LoadModule env_module /usr/lib/apache/1.3/mod_env.so - Savane is in UTF-8. But Apache is frequently distributed with AddDefaultCharset activated so it adds a default charset different from UTF-8. You must deactivate it (or set the default charset to UTF-8) by editing this variable to get the following: AddDefaultCharset off - Make sure that php accept file upload. In the php.ini file, add the following: ; Whether to allow HTTP file uploads. file_uploads = on Make sure that php register_globals is set to "on". It is set by default on old PHP packages but not in newer ones. In the php.ini file, add the following: register_globals = on Make sure php variable_order is set to "EGPCS". This is the default and shouldn't be changed in general, but bad things will happen to Savane, and other programs in general if it's modified. There are a few others settings you may require and may have deactivated by default (especially if you use very recent PHP versions). You can check at: http://127.0.0.1/pathtosavane/testconfig.php - You can either use a virtual domain for the Savannah package in your server, or you can install it in a subdirectory of your home page. If for instance you are going to install it in a virtual server "projects.my.net" in a server with IP 192.168.62.11, and you've created the configuration file in /etc/savannah, you should write the following in Apache's configuration file: NameVirtualHost 192.168.62.11 # Basic setup ServerName projects.my.net DocumentRoot /usr/src/savane/frontend/php ServerAdmin your.name@my.net SetEnv SAVANE_CONF /etc/savane ErrorDocument 404 /404.php DirectoryIndex index.php index.html Options SymLinksIfOwnerMatch AllowOverride None Order allow,deny Allow from all # Configure some specials urls: ForceType application/x-httpd-php ForceType application/x-httpd-php ForceType application/x-httpd-php # Restrict access to testconfig Order Deny,Allow Allow from 127.0.0.1 Deny from All # Restrict access into include/ Order Allow,Deny Deny from all On the other hand if you decide to install it in a subdirectory of your home URL, for instance http://myhome.net/savane/, and the configuration file is in /etc/savannah, put the following lines in Apache's configuration file: Alias /savane /usr/src/savane/frontend/php # Pure apache conf: SetEnv SAVANE_CONF /etc/savane Options SymLinksIfOwnerMatch AllowOverride None #Necessary with apache2: AcceptPathInfo On ErrorDocument 404 /savane/404.php Order allow,deny Allow from all # Configure some specials urls: ForceType application/x-httpd-php ForceType application/x-httpd-php ForceType application/x-httpd-php ForceType application/x-httpd-php ForceType application/x-httpd-php ForceType application/x-httpd-php ForceType application/x-httpd-php # Restrict access to testconfig Order Deny,Allow Allow from 127.0.0.1 Deny from All # Restrict access into include/ Order Allow,Deny Deny from all IMPORTANT: Then reset the Apache server. At this point you should be able to see the Savannah package home page in you server, at the URL where you put it. - To get more complete examples for both apache 1.33.x and apache 2.0.x, check etc/apache and etc/apache2. * * * CREATING A PROJECT DEDICATED TO ADMINISTRATION Create a user with the web interface and login. You should create a project dedicated to the server administration. Give it the name you chose for it in the configuration. Administrators of this project will be Savannah administrators. Warning: the unix_group_name of the system group MUST be defined in the configuration file before the creation of that group! * * * SETTING UP EXTERNAL FEATURES: mailman, cvs To install cvs, mailman, you should get them packaged for your distribution. Once it's done, you should use the tool your distribution provide to configure them. For instance, on Debian, you can do: dpkg-reconfigure cvs And then add 2 new directories... For Source CVS and HTML cvs IHMO (yeupou@gnu.org), this is the hardest part of the job, dealing with the installation of this software. If you run exim (it's probably the case if you are running Debian GNU/Linux), you may take a look at http://www.exim.org/howto/mailman.html EOF.