Improved the documentation based on user feedback.

INSTALL.mdtext

@@ -4,6 +4,29 @@ The installation of InDefero is composed of 2 parts, first the
 installation of the [Pluf framework](http://www.pluf.org) and second,
 the installation of InDefero by itself.
 
+## Recommended Layout of the Files
+
+If your server document root is in `/var/www` a good thing is to keep
+the number of files under the `/var/www` folder to its minimum. So,
+you should create a `/home/www` folder in which we are going to
+install all but the files which need to be available under the
+document root.
+
+    /home/www/pluf/src/
+    /home/www/pluf/src/Pluf.php
+    /home/www/pluf/src/migrate.php
+    /home/www/indefero/src
+    /home/www/indefero/www
+    /home/www/indefero/www/index.php
+    /home/www/indefero/www/media
+
+The you need to link the `media` and `index.php` files into your
+docroot.
+
+    $ cd /var/www
+    $ ln -s /home/www/indefero/www/index.php
+    $ ln -s /home/www/indefero/www/media
+
 ## Installation of Pluf
 
 * Checkout the trunk of [Pluf](http://www.pluf.org).
@@ -12,7 +35,7 @@ the installation of InDefero by itself.
     $ sudo pear install --alldeps Mail
     $ sudo pear install --alldeps Mail_mime
 
-The Pluf installation folder is the folder containing the file `Pluf.php`.
+The Pluf installation folder is the folder containing the file `Pluf.php`. 
 
 ## Installation of InDefero
 
@@ -30,15 +53,18 @@ Here is the step-by-step installation procedure:
 * Make a copy of `src/IDF/conf/idf.php-dist` as `src/IDF/conf/idf.php`.
 * Update the idf.php file to match your system.
 * Open a terminal/shell and go into the `src` folder in the InDefero installation folder.
-* Run `php /path/to/pluf/src/migrate.php --conf=IDF/conf/idf.php -a -i -d -u` to test the installation of the tables.
+
-* Run `php /path/to/pluf/src/migrate.php --conf=IDF/conf/idf.php -a -i -d` to really install the tables.
+    $ cd /home/www/indefero/src
+
+* Run `php /home/www/pluf/src/migrate.php --conf=IDF/conf/idf.php -a -i -d -u` to test the installation of the tables.
+* Run `php /home/www/pluf/src/migrate.php --conf=IDF/conf/idf.php -a -i -d` to really install the tables.
 * Create a bootstrap file to create the first project and admin user for example `www/bootstrap.php`. Do not forget to update the second line with your path to Pluf:
 
     <?php
-    set_include_path(get_include_path().PATH_SEPARATOR.dirname(__FILE__).'/../src');
+    set_include_path(get_include_path().PATH_SEPARATOR.dirname(__FILE__).'/home/www/indefero/src');
-    set_include_path(get_include_path().PATH_SEPARATOR.'/path/to/pluf/src');
+    set_include_path(get_include_path().PATH_SEPARATOR.'/home/www/pluf/src');
     require 'Pluf.php';
-    Pluf::start(dirname(__FILE__).'/../src/IDF/conf/idf.php');
+    Pluf::start(dirname(__FILE__).'/home/www/indefero/src/IDF/conf/idf.php');
     Pluf_Dispatcher::loadControllers(Pluf::f('idf_views'));
     
     $project = new IDF_Project();
@@ -48,7 +74,7 @@ Here is the step-by-step installation procedure:
     $project->create();
     $user = new Pluf_User();
     $user->first_name = 'John';
-    $user->last_name = 'Doe';
+    $user->last_name = 'Doe'; // Required!
     $user->login = 'doe';
     $user->email = 'doe@example.com';
     $user->password = 'yourpassword'; // the password is salted/hashed 
@@ -61,6 +87,8 @@ Here is the step-by-step installation procedure:
 
 * Run `php www/bootstrap.php`.
 * Remove the `www/bootstrap.php` file.
+* Open the `www/index.php` file and ensure that the path to Pluf and
+  Indefero are correctly set for your configuration.
 
 Now you can login with this user into the interface.
 
@@ -78,3 +106,11 @@ the following `.htaccess` file to be put in the same folder of the
     RewriteRule ^(.*) /index.php/$1
 
 
+## For the Gentoo users
+
+If you get the error:
+
+    T_CHARACTER Use of undefined constant T_CHARACTER - assumed 'T_CHARACTER'"
+
+you need to compile PHP with the "tokenizer" flag.
+

src/IDF/conf/idf.php-dist

@@ -23,126 +23,146 @@
 
 $cfg = array();
 
-// to start with, it can be practical.
+#
-$cfg['debug'] = false;
+# You must set it to false once everything is running ok.
+#
+$cfg['debug'] = true;
 
-// If you have a single git repository, just put the full path to it
+# If you have a single git repository, just put the full path to it
-// without trailing slash. The path is the path to the git database,
+# without trailing slash. The path is the path to the git database,
-// so you need to include the /.git folder.
+# so you need to include the /.git folder.
-// For example: '/path/to/my/project/.git'
+# For example: '/path/to/my/project/.git'
-//
+#
-// If you have multiple repositories, you need to put %s where you
+# If you have multiple repositories, you need to put %s where you
-// want the shortname of the project to be replaced. 
+# want the shortname of the project to be replaced. 
-// For example:
+# For example:
-// - You have many projects on your local computer and want to use 
+# - You have many projects on your local computer and want to use 
-//   InDefero to see them. Put: '/home/yourlogin/Projects/%s/.git'
+#   InDefero to see them. Put: '/home/yourlogin/Projects/%s/.git'
-// - You have many projects on a remote server with only "bare" git
+# - You have many projects on a remote server with only "bare" git
-//   repositories. Put: '/home/git/repositories/%s.git'
+#   repositories. Put: '/home/git/repositories/%s.git'
-//
+#
+# ** Do not forget to give read access to these folders to your www
+# ** user. For example, adding www to the git group.
 $cfg['git_repositories'] = '/home/git/repositories/%s.git';
-//
+#
-// Like for the git_repositories definition, the path can contains %s
+# Like for the git_repositories definition, the path can contains %s
-// and it will be automatically replaced. You can ignore this
+# and it will be automatically replaced. You can ignore this
-// configuration variable as it is only for information use in the
+# configuration variable as it is only for information use in the
-// tree view.
+# tree view.
-//
+#
 $cfg['git_remote_url'] = 'git://projects.ceondo.com/%s.git';
 
-// Same as for git, you can have multiple repositories, one for each
+# Same as for git, you can have multiple repositories, one for each
-// project or a single one for all the projects. 
+# project or a single one for all the projects. 
-//
+#
-// In the case of subversion, the admin of a project can also select a
+# In the case of subversion, the admin of a project can also select a
-// remote repository from the web interface. From the web interface
+# remote repository from the web interface. From the web interface
-// you can define a local repository, local repositories are defined
+# you can define a local repository, local repositories are defined
-// here. This if for security reasons.
+# here. This if for security reasons.
 $cfg['svn_repositories'] = 'file:///home/svn/repositories/%s';
 $cfg['svn_remote_url'] = 'http://projects.ceondo.com/svn/%s';
 
-// Mercurial repositories path
+# Mercurial repositories path
-//$cfg['mercurial_repositories'] = '/home/mercurial/repositories/%s';
+#$cfg['mercurial_repositories'] = '/home/mercurial/repositories/%s';
-//$cfg['mercurial_remote_url'] = 'http://projects.ceondo.com/hg/%s';
+#$cfg['mercurial_remote_url'] = 'http://projects.ceondo.com/hg/%s';
 
-// admins will get an email in case of errors in the system in non
+# admins will get an email in case of errors in the system in non
-// debug mode.
+# debug mode.
 $cfg['admins'] = array(
                        array('Admin', 'you@example.com'),
                        );
 
-// Email configuration
+# Email configuration
 $cfg['send_emails'] = true;
 $cfg['mail_backend'] = 'smtp';
 $cfg['mail_host'] = 'localhost';
 $cfg['mail_port'] = 25;
 
-// Paths/Url configuration
+# Paths/Url configuration.
 # 
-# if you access the index.php with:
+# Examples:
-#  http://www.mydomain.com/myfolder/index.php
+# You have: 
-# put the following:
+#   http://www.mydomain.com/myfolder/index.php
+# Put:
+#   $cfg['idf_base'] = '/myfolder/index.php';
+#   $cfg['url_base'] = 'http://www.mydomain.com';
 #
-# $cfg['idf_base'] = '/myfolder/index.php';
+# You have: 
-# $cfg['url_base'] = 'http://www.mydomain.com';
+#   http://www.mydomain.com/
-
+# Put:
-$cfg['idf_base'] = ''; // put '/whatever/index.php if you are not
+#   $cfg['idf_base'] = '';
-                       // using mod_rewrite and installing in a
+#   $cfg['url_base'] = 'http://www.mydomain.com';
-                       // subfolder.
+#
+#
+#
+$cfg['idf_base'] = '';
 $cfg['url_base'] = 'http://projects.ceondo.com';
+
+# Url to access the media folder which is in the www folder 
+# of the archive
 $cfg['url_media'] = 'http://projects.ceondo.com/media';
+
+# Url to access a folder in which the files you upload through
+# the downloads tab will be stored.
 $cfg['url_upload'] = 'http://projects/ceondo.com/media/upload';
+# Path to the upload folder
 $cfg['upload_path'] = '/path/to/media/upload';
 
 #
 # The following path *MUST NOT* be accessible through a web browser 
 # as user will be able to upload .html, .php files and this can 
-# create *TERRIBLE* security issues.
+# create *TERRIBLE* security issues. In this folder, the attachments 
+# to the issues will be uploaded and we do not restrict the content type.
 #
 $cfg['upload_issue_path'] = '/path/to/attachments';
 
-// write here a long random string unique for this installation. This
+#
-// is critical to put a long string.
+# write here a long random string unique for this installation. This
+# is critical to put a long string, with at least 40 characters.
 $cfg['secret_key'] = ''; 
 
-// the sender of all the emails.
+# the sender of all the emails.
 $cfg['from_email'] = 'sender@example.com'; 
 
-// Email address for the bounced messages.
+# Email address for the bounced messages.
 $cfg['bounce_email'] = 'no-reply@example.com';
 
-// Temporary folder where the script is writing the compiled templates,
+# Temporary folder where the script is writing the compiled templates,
-// cached data and other temporary resources.
+# cached data and other temporary resources.
-// It must be writeable by your webserver instance.
+# It must be writeable by your webserver instance.
-// It is mandatory if you are using the template system.
+# It is mandatory if you are using the template system.
 $cfg['tmp_folder'] = '/tmp';
 
-// Database configuration
+# Database configuration
-// For testing we are using in memory SQLite database.
+# For testing we are using in memory SQLite database.
 $cfg['db_login'] = 'www';
 $cfg['db_password'] = '';
 $cfg['db_server'] = '';
-$cfg['db_version'] = '';
+# Only needed for MySQL
-$cfg['db_table_prefix'] = ''; 
+$cfg['db_version'] = '5.1';
+# If you want to have different installations with the same DB
+$cfg['db_table_prefix'] = 'indefero_'; 
+# ** DO NOT USE SQLITE IN PRODUCTION ** 
+# This is not because of problems with the quality of the SQLite
+# driver or with SQLite itself, this is due to the lack of migration
+# support in Pluf for SQLite, this means we cannot modify the DB
+# easily once it is loaded with data.
+$cfg['db_engine'] = 'PostgreSQL'; # SQLite is also well tested or MySQL
+$cfg['db_database'] = 'website'; # put absolute path to the db if you
+                                 # are using SQLite. 
 
-// ** DO NOT USE SQLITE IN PRODUCTION ** 
+# -- From this point you should not need to update anything. --
-// This is not because of problems with the quality of the SQLite
-// driver or with SQLite itself, this is due to the lack of migration
-// support in Pluf for SQLite, this means we cannot modify the DB
-// easily once it is loaded with data.
-$cfg['db_engine'] = 'PostgreSQL'; // SQLite is also well tested or MySQL
-$cfg['db_database'] = 'website'; // put absolute path to the db if you
-                                 // are using SQLite. 
-
-// -- From this point you should not need to update anything. --
 $cfg['pear_path'] = '/usr/share/php';
 
 $cfg['login_success_url'] = $cfg['url_base'].$cfg['idf_base'];
 $cfg['after_logout_page'] = $cfg['url_base'].$cfg['idf_base'];
 
-// Caching of the scm commands.
+# Caching of the scm commands.
 $cfg['cache_engine'] = 'Pluf_Cache_File';
 $cfg['cache_timeout'] = 300;
 $cfg['cache_file_folder'] = $cfg['tmp_folder'].'/cache';
 
-// The folder in which the templates of the application are located.
+# The folder in which the templates of the application are located.
 $cfg['template_folders'] = array(
                                  dirname(__FILE__).'/../templates',
                                  );
@@ -166,7 +186,7 @@ $cfg['template_modifiers'] = array(
                                    'size' => 'IDF_Views_Source_PrettySize',
                                    );
 
-// available languages
+# available languages
 $cfg['languages'] = array('en', 'fr'); 
 
 # SCM base configuration

www/index.php

@@ -22,7 +22,12 @@
 # ***** END LICENSE BLOCK ***** */
 
 // Set the include path to have Pluf and IDF in it.
-set_include_path(get_include_path().PATH_SEPARATOR.dirname(__FILE__).'/../src');
+$indefero_path = dirname(__FILE__).'/../src';
+//$pluf_path = '/path/to/pluf/src';
+set_include_path(get_include_path()
+                 .PATH_SEPARATOR.$indefero_path
+//                 .PATH_SEPARATOR.$pluf_path
+                 );
 require 'Pluf.php';
 Pluf::start(dirname(__FILE__).'/../src/IDF/conf/idf.php');
 Pluf_Dispatcher::loadControllers(Pluf::f('idf_views'));