===========================================================================
 ConfTool - Your Conference Management Tool
 (c) 2001-2006 Harald Weinreich
               VSIS, Fachbereich Informatik, Universität Hamburg
 http://www.conftool.net/
===========================================================================


REQUIREMENTS
============

ConfTool requires an Web server with installed PHP module and MySQL as
relational database system.

Required versions:
* Apache 1.3.x or 2.0.36 or higher
* PHP Version 4.3.x/4.4.x/5.0.x/5.1.x (should be installed as Apache module).
* MySQL, Version 4.0.x or higher.

The current development environment for ConfTool is:
* Apache HTTPD 2.0.50 (with SSL)
* PHP 4.3.10 and PHP 5.1.2
* MySQL 4.1.21
* Linux 2.6 and Windows XP SP2

ConfTool has been used with OSX/FreeBSD/Darwin, Solaris, Gentoo and other
Unix derivates as well. It is also possible to install it under Microsoft IIS
with php as cgi, but that setup is not covered by this instruction.

If you experience problems with other system configurations, please send a
message with a description of your problem to <info (at) conftool . net>

I also appreciate messages about successful installations or hints how
to improve the setup process.

During the installation process described below, root access is required.

If you do not have root access or are on a shared server, the installation
procedure is a bit different. If you get the Pro version I can provide further
details and the (usually necessary) support. I also offer hosting of ConfTool
Pro for reasonable prices. In this case I do the installation and configuration
according to your requirements.



INSTALLATION
============

Note: For the following installation steps we assume the above mentioned packages
and modules to have been already successfully installed and configured.
We do not provide help or specific installation instructions for those modules, as
all required information can already be found on the internet.


* Step 1: Unpack archive and set file permissions
*------------------------------------------------

Create a directory where you want to install ConfTool. This can be e.g.
"/usr/local/conftool" or "/home/conftool". It is also possible to create a new
user and use "~/conftool" as installation directory. Go to the directory of your
choice and unpack the archive using the following command:

	> tar xvzf conftool-x.y.tgz

(Windows: Please use Winzip, Winrar or a similar tool to unpack.
          The home directory could be e.g. "C:\conftool\".)

Seven sub-directories will be created. These are:

	install/	directory with installation support files
	etc/		contains configuration files
	htdocs/	    contains files, directly accessible through the Web server
	pages/	    contains all Web pages
	lib/		contains libraries ConfTool
	classes/	contains classes of ConfTool
	uploads/	used to save paper uploads


Please set the user privileges for the upload directory so that the Web server has
full write access to that directory. This is necessary as uploaded documents
will be stored here. Example: If the server (httpd) runs as user "nobody",
please execute the following commands:

	> chown nobody uploads/
	> chmod u+rwx uploads/

(If you do not have root rights, you may instead set "chmod a+rwx uploads/")
Furthermore, the server needs read access to all these directories
(except install/).


* Step 2: Web Server Configuration
*---------------------------------

The configuration of the server has to be modified so that the "htdocs/"
directory can be directly accessed through the Web server. Furthermore, the
"etc/" directory has to be added to the PHP include path (php_include_path).

For the Apache server the following configuration commands realize the
above enhancements (if "/conftool" is the URL and "/home/conftool/" is the
directory, where ConfTool shall be located). These Apache configuration
file is usually called "httpd.conf" and can for instance be found in
"/etc/apache2/httpd.conf", but this depends on your system setup.


Alias /conftool "/home/conftool/htdocs/"
<Directory "/home/conftool/htdocs">
    Order deny,allow
    Allow from all
    Options Includes FollowSymLinks
    DirectoryIndex index.php
    php_value include_path ".:/home/conftool/etc"

# The following php parameters have to be set here or in php.ini (preferred!)
# php_value works only in Apache 2!

	# Values required to enable big uploads:
	# Up to 10MB - leave some extra space.
    php_value upload_max_filesize 11M
    # Files are sent by POST so the post_max_size has to be even bigger.
    php_value post_max_size 12M
    # PHP receives the files, so this value has to be even bigger
    php_value memory_limit 15M
    # 15min timeout is usually enough - otherwise uploads are cancelled by a timeout message...
    php_value max_execution_time 900
    # Set the session timeout to 2 hours (7200s).
	php_value session.gc_maxlifetime 7200

	# For security reasons:
	php_value register_globals off

	# If you have problems downloading files with IE and SSL, please try the following settings:
	php_value session.cache_limiter public
	php_value session.cache_expire 5
</Directory>


Windows: Instead of "/home/conftool/..." you have to enter sth. like
 "C:/conftool/...", e.g.

Alias /conftool "C:/conftool/htdocs/"
<Directory "C:/conftool/htdocs">
    Order deny,allow
    Allow from all
    Options Includes FollowSymLinks
    DirectoryIndex index.php
    php_value include_path ".;C:/conftool/etc/"
(... see above ...)
</Directory>

Last but not least the server has to be configured to parse all files with the
extension ".php" by the PHP interpreter before sending them to the browser:

	AddType application/x-httpd-php .php

We recommend also to add the extensions .inc, .conf, .page, .lib and .ctcls for
security reasons, but it is not really necessary. It is more important to to
block the access to backup files like "*.bak", "*.BAK" and "*~".

Finally we recommend you modify the standard PHP configuration to allow big file
uploads for the submission process. The default value depends on the installed
PHP version, however, it is usually about 2MByte. The following parameter in the
"php.ini"-file (usually located in "/usr/local/lib/php.ini", "/etc/php.ini" or
"C:\windows\php.ini") is responsible for the maximum file size for uploads:

    upload_max_filesize 11M
    post_max_size 12M
    memory_limit 15M
    max_execution_time 900
	session.gc_maxlifetime 7200

This allows an maximum upload file size of 10MByte and 15 minutes and increase the
session timeout to two hours.

We also recommend to enable the zlib compression:

    zlib.output_compression = On



* Step 3: Testing the Setup
* -------------------------
After restarting the server you should test if your settings worked.
Please call the following address in your browser:
http://www.yourdomain.org/conftool/info.php

  Important Remarks:
  - For security reasons you have to rename the file "info.ph_" to
    "info.php" first. You find this file in "conftool/htdocs/").
  - Please DELETE the file "htdocs/info.php" after finishing your installation
    for security reasons.
  - "www.yourdomain.org" is the domain name of your server and "conftool" is the
    directory alias set in your httpd.conf file.

You will get an overview of the current php settings for ConfTool.
If some parameters are not configured correctly (as you have no access to php.ini),
you may also try to set them in the files "htdocs/.htaccess" and "htdocs/settings.php".


* Step 4: Initialize Database
* ---------------------------

For ConfTool a database is required to store all data. Additionally a
database user has to be set up to enable write access to the tables in the
database.
The standard configuration uses a database called "conference" and a database
user "confuser". These names can be modified. However, if you choose to
modify the names, you must adapt the ConfTool configuration files as well.

The following description is for a MySQL database system. To create the
database and the database user, usually root rights are required.

Start with creating the new database and creating a new user. You also have to
assign all rights for the new database to this user. In our example, Web server and
MySQL database system reside on the same computer. If you require a distributed
configuration, please adapt the commands and use the Web server's IP instead of
"localhost". Please choose an appropriate "password". The appropriate commands for
this can be found in the file instal/createDBUser.sql
After editing this file you can invoke it by calling:

	> mysql -u root -p < install/createDBUser.sql

(You will be asked for the password of the root user of the mysql database)

Now create the database tables by running the installation script on your
database(you have to enter the new password):

	> mysql conference -u confuser -pconfpass < install/initdb.sql

The next step is to enter the default data into the database:

	> mysql conference -u confuser -pconfpass < install/defaultdata.sql

If you got no error message, the database should be installed.


* Step 5: Main Configuration of ConfTool
* --------------------------------------

The next step is configuring ConfTool. You need to modify some settings to make
it work with your Web server and database. Also, some settings have to be
customized to make ConfTool your conference system. All ConfTool settings are
set in the file "etc/conftool.conf.php" and well documented.
You have to set your ConfTool installation path and other parameters.

The language and wordings of the system can also be modified. All textual output
is defined in one language file that resides in the directory "etc/". The
default language is German, so the corresponding file is "german.lang".
WARNING: Changes to the language file may be tricky and have to be tested
carefully.


* Step 6: Modify the Appearance of ConfTool
* -----------------------------------------

ConfTool has a site header and footer that can easily be modified to match the
appearance of your conference. You can use simple HTML as well as PHP code in
these files. The two files that should be modified reside in the directory
"etc/" and are called "siteheader.inc" and "sitefooter.inc". You should
modify these files to make the tool fit your conference site.

Furthermore, the image file "logo.gif" in the directory "htdocs/" should be
replaced by a small logo of your conference. Recommended width: 50-150 pixel,
height: 30-60 pixel. Finally, the file "logo-invoice.gif" should be replaced by
a logo of the organizer. It is used on invoices in the upper right corner above
the addressor.

The "htdocs/" directory also contains the cascading style sheet file for
ConfTool. It is called "conftool.css" and contains all color and font
definitions for the tool. It is possible to alter the color and fonts scheme
of the system to match to your design requirements. However, these
modifications are more complicated than they might seem.


FIRST LOG-ON
============

If everything went right, ConfTool should now be up and running. Please use a
Web browser and enter the URL you chose in your httpd configuration file, e.g.
http://www.yourdomain.org/conftool/
You should get to the login page.

The database initialization also installed some standard settings as well as a
standard administration user. The initial username of that user is "admin," the
password is also "admin." Now, please log on as administrator, go to "User Data"
and change the password for the "admin" user and set the correct email address.

Registration of new users can be done at the same address, where you just logged
in as administrator. However, new users naturally do not have administrator
rights.


Setup of Conftool
=================
Log in as "admin" and go to "Settings". Here, most basic parameters of the system
can be set.

First the main parameters like the conference name are to be defined. This can be
done in "Settings" => "Main Setup".

Secondly the dates for phases of your conference (Submission, Review, Final Upload,
Registration for Participation etc.) should be defined. We strongly recommend to
deactivate currently unneeded parts of the system! For example, it doesn't make
sense to allow entering reviews or to access the review results while the
submission is still in progress, or to allow registration for conference
participation (as the program and prices of the conference are most
likely not defined yet).

Furthermore, you should define possible topics for papers (and reviewers).
If the topics are well elaborated, assigning papers to reviewers will be
much easier.

We recommend that you now enter all reviewers as "new users" with name, surname,
e-mail and (dummy) password yourself. Initially, this is some work, but it will
help contacting the PC members by mail and avoid later headaches with "busy" PC
members who don't register themselves. When you enter such members, you should
also set their status to "Member of the program committee (reviewer)". Now you
can use the function "Send E-Mails" to contact all PC members and ask them to
complete their personal data (like their address) and also select their special
topics.

In our own experience, this is probably the most efficient procedure. Be
prepared that some PC members will also forget to register for participation
later. (They can of course use the same user account.)

When the conference program and prices are established, you can define the
conference registration data in the "Settings" menu as well. Please enter the
data step by step as defined in that menu. This part of the ConfTool is fairly
complex, but if you follow the steps, you should not experience complications.

IMPORTANT: Please schedule all possible events (tutorials, workshops etc.) and
services (social evening, extra proceedings, cups, t-shirts etc.), _before_
people can register for the conference. Although it is possible to add further
events later, we strongly discourage to do this, as e.g. participants can not
modify their registration data themselves (because registrations are binding).

All other features are explained in the tool itself. If you encounter any
problems or have suggestions, please let us know.

IMPORTANT TESTS!!!!!
====================
The following settings can cause problems and should be tested carefully:

1. Is the mail server configuration correct?
   This can easily be tested by using the function "Forgotten your password?"

2. Does the up- and download of papers work well?
   Try to submit a (big!!) paper as admin and to download it afterwards.
   If you are using https, please also check, if you can download
   papers using the Windows Internet Explorer, as all current versions
   have a serious bug in the https implementation. ConfTool has corresponding
   workarounds, however, they require that your PHP configuration does not
   explicitly prevent the caching of files by the browser.
   If you have problems, plaease check your settings with info.php and look
   at the FAQs before sending a mail to us!

May You Do Well!
================
We wish you a successful conference and hope to get a lot of constructive
feedback regarding ConfTool.

  Harald Weinreich