INSTALL.verbose

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 <https://gna.org/support/?group=savane>

$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
  <VirtualHost 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:
	<Files users>
        	ForceType application/x-httpd-php
	</Files>
	<Files projects>
        	ForceType application/x-httpd-php
	</Files>
	<Files file>
        	ForceType application/x-httpd-php
	</Files>
    
	# Restrict access to testconfig
	<Files testconfig.php>
   		Order Deny,Allow
		Allow from 127.0.0.1
		Deny from All
	</Files>
  </VirtualHost>
  # Restrict access into include/
  <Directory /usr/src/savane/frontend/php/include>
	Order Allow,Deny
	Deny from all
  </Directory>

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

  <Directory /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:
      <Files u>
          ForceType application/x-httpd-php
      </Files>
      <Files us>
          ForceType application/x-httpd-php
      </Files>
      <Files users>
          ForceType application/x-httpd-php
      </Files>
      <Files projects>
          ForceType application/x-httpd-php
      </Files>
      <Files pr>
          ForceType application/x-httpd-php
      </Files>
      <Files p>
          ForceType application/x-httpd-php
      </Files>
      <Files file>
          ForceType application/x-httpd-php
      </Files>

      # Restrict access to testconfig
      <Files testconfig.php>
          Order Deny,Allow
          Allow from 127.0.0.1
          Deny from All
      </Files>
  </Directory>
  # Restrict access into include/
  <Directory /usr/src/savane/frontend/php/include>
	Order Allow,Deny
	Deny from all
  </Directory>


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.