source: indico/INSTALL @ fa0a08

Table of Contents
Indico Installation Guide

    1. Programs to Install prior
    2. Mod_python configuration
    3. Installation

        3.1. Default Installation
        3.2. Custom Installation
        3.3. Running Indico

    4. Reconfiguring after Installation
    5. Upgrading
    6. Explanation of the XML Configuration File 'config.xml'

        6.1. Path Directories
        6.2. Database, Access Rights, Url, Email, SMTP and OAI Parameters
        6.3. File Types and System Icons

    7. Notes

Indico Installation Guide

CERN

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents
1. Programs to Install prior
2. Mod_python configuration
3. Installation

    3.1. Default Installation
    3.2. Custom Installation
    3.3. Running Indico

4. Reconfiguring after Installation
5. Upgrading
6. Explanation of the XML Configuration File 'config.xml'

    6.1. Path Directories
    6.2. Database, Access Rights, Url, Email, SMTP and OAI Parameters
    6.3. File Types and System Icons

7. Notes

1. Programs to Install prior

1. Python 2.4.4 (and above)      http://python.org
2. Apache HTTP Server 2.0 (and   http://httpd.apache.org/download.cgi
above)
3. ZODB 3.4                      http://zope.org/Products/ZODB3.4
4. Reportlab 2.0                 http://www.reportlab.org/downloads.html
5. mod_python 3.3.1 (and above)  http://httpd.apache.org/modules/
                                 python-download.cgi
6. libxml and libxslt            http://xmlsoft.org/python.html
7. Python Imaging Library        http://www.pythonware.net/storage/
                                 Imaging-1.1.4.tar.gz
8. Pytz - Python Timezone        http://sourceforge.net/projects/pytz
Library
9. Python simplejson             http://pypi.python.org/pypi/simplejson

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2. Mod_python configuration

In the Apache config files (httpd.conf or apache2.conf) add the following:

 i. Add the "LoadModule" line to make Apache load mod_python.

     In Linux, the configuration files normally already has the following line:

    Include /etc/apache2/mods-enabled/*.load
    Include /etc/apache2/mods-enabled/*.con

    If you have installed mod_python through a package, the file /etc/apache2/
    mods-enabled/mod_python.load will probably be already created with the
    'LoadModule' line inside it. In that case, you don't need to add anything.
    Otherwise, see the instructions for Windows.

     In Windows, add the following line:

    LoadModule python_module modules/mod_python.so

    This assumes mod_python.so has been placed in the modules folder.
    Otherwise, put the appropriate directory instead.

    For more information, see the mod python documentation

ii.  At the end of the Apache config file add:

         <Directory "C:/Program Files/Apache Group/Apache2/htdocs/MaKaC">
         AddHandler python-program .py
         PythonHandler mod_python.publisher
         PythonDebug On
         </Directory>

    Adapt this to your own file system, e.g. If using Linux use <Directory "/
    soft/http/htdocs/MaKaC">

iii. Change the Apache config file so that Apache is aware of previous
    directory. There are usually two ways of doing this:

    -Changing the DocumentRoot value. If you used "C:/Program Files/Apache
    Group/Apache2/htdocs/MaKaC", a correct value of DocumentRoot would be "C:/
    Program Files/Apache Group/Apache2/htdocs", if you want Indico to show on
    http://webserverhostname/MaKaC/index.py.

    For Linux a correct DocumentRoot value would be "/soft/http/htdocs".

     -Using the Alias directive by adding the following at the end of the
    Apache configuration file:

    Alias /MaKaC "C:Program Files/Apache Group/Apache2/htdocs/MaKaC"

    or in Linux:

    Alias /MaKaC "/soft/http/htdocs/MaKaC"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3. Installation

After downloading and uncompressing the Indico distribution, you have 2 options
when running an installation: Default or Custom.

Your uncompressed folder will be referred to as the 'Indico distributed
directory' throughout this document

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3.1. Default Installation

To make a default installation, from the 'Indico distributed directory', run
the setup install script using

 "setup.py install"

A default installation will install Indico onto your machine dependant on the
platform you are running. The default configuration for Indico is:

 i.  Main Package Directory 'pkgdirectory' (Pythons site packages directory
    name varies on version):

    Windows - C:\Python24\Lib\site-packages
    Linux -  /usr/local/lib/python2.4/site-packages

    (Templates Directory 'tpls' is defaulted to this directory with /MaKaC/
    webinterface/tpls at the end)

ii.  Apache Files Directory 'htdocs':

    Windows - C:\Program Files\Apache Group\Apache2\htdocs\MaKaC
    Linux -  /soft/http/htdocs/MaKaC

    (Images Directory 'images' is defaulted to this directory with /images at
    the end

iii.  Archive Directory 'archive':

    Windows - C:\MaKaC\archive
    Linux -  /soft/MaKaC/archive

iv.  Temporary Directory 'temp':

    Windows - C:\MaKaC\temp
    Linux -  /soft/MaKaC/temp

 v. For All other parameters the default configurations are written in the XML
    config file

See Explanation of XML config file for more information on each path

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3.2. Custom Installation

A custom Installation lets you change the directories and parameters of the
Indico installation, please read Explanation of XML config file, before
starting a custom installation this will explain what each parameter is, then
follow these steps:

 1. From the 'Indico distributed directory', open the config.xml file into a
    text editor

 2. Edit the path names and parameters that you wish to change, save and close
    the file

     1. If you changed the "htdocs" path name you need to change the
        <Directory> you added in the Apache config file to match your htdocs
        path

     2.  If you changed the "pkgdirectory" path name you need to add to the
        code you added in the Apache config file. Before the final </Directory>
        tag you need to add:

        PythonPath "sys.path+['pkgdirectory']"

        Where pkgdirectory is the full path of your defined directory

     3. If you changed the "dp_param" you may need to edit the 'address'
        section in the config file for ZODB, for information on how to do this
        visit: http://zope.org/Wikis/ZODB/HowtoRunAZEOServer/howto.html

 3.  From the 'Indico distributed directory', run the setup install script
    using

     "setup.py install"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3.3. Running Indico

To run Indico:

 1. Start the Database Daemon: You need to have the ZODB Database running in
    order for InDiCo to work correctly.

    The database can be on your machine or running on a remote machine. The
    ZODB database runs into a ZEO server. In order to have the server running,
    you should locate the script "runzeo.py", which should be in the ZEO server
    folder (/usr/lib/python2.4/site-packages/ZEO/ in Linux).

     Create a file called "zeo.config" with the following lines for a default
    installation:

    <zeo>
      address databasehostname:9675
      transaction-timeout 5
    </zeo>
    <filestorage 1>
      path /usr/lib/python2.4/site-packages/ZEO/data/data.fs
    </filestorage>

    <eventlog>
      <logfile>
        path /usr/lib/python2.4/site-packages/ZEO/log/zeo.log
        format %(asctime)s %(message)s
      </logfile>
    </eventlog>

    Please note that the host name of the database should be the same as the
    one you put in config.xml file (see "Explanation of the XML Configuration
    File 'config.xml' "). Of course you can change the <filestorage> and
    <logfile> values to your convenience.

     After creating the file zeo.config, call the script runzeo.py with

    python runzeo.py -C zeo.config

    For more information, please see the "How to run a ZEO Server" (http://
    zope.org/Wikis/ZODB/HowtoRunAZEOServer/howto.html) for more information on
    how to do this.

 2. Start the Apache Server: You need to have the Apache server running for
    Indico to work, for more information on starting the Apache Server visit:

      □  Using Apache with Microsoft Windows

      □  Starting Apache (For Linux).

         In Linux, you normally can do this by executing

        apache2ctl -k start/stop/restart/graceful

        as root.

 3.  In a web browser type your base URL followed by index.py. If you chose a
    default installation or did not edit the URL base, this will be:

    http://webserverhostname/MaKaC/index.py

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

4. Reconfiguring after Installation

Once you have installed Indico you may need to change a path or parameter of
the configuration. This can be done by reconfiguring Indico. To do this:

 1. From the 'common' folder inside your main package directory ('pkgdirectory/
    MaKaC/common'), open the config.xml file with a text editor. If a default
    installation was chosen or "pkgdirectory" was not edited, this will be
    located inside Python site-packages. Otherwise it will be inside the
    "pkgdirectory" you specified when installing Indico.

 2. Edit those parameters or paths that you wish to reconfigure, then save and
    close the file.

 3.  From the current directory (MaKaC/common), run the reconfigure script
    using

    "reconfigure.py run"

 4. Restart the Apache Server.

Your Indico Installation will now be reconfigured with your new settings.

NOTE: You cannot reconfigure the main package directory, if you need to change
the main installation directory you can do so by either upgrading or
reinstalling Indico again.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

5. Upgrading

Once you already have an installation of Indico you may need to install a newer
release. If you want to keep the same configurations as your previous
installation, you can upgrade your version. During the upgrading process, your
current settings will be read and you will be able to check if they are
correct. You can also edit the settings if you want the new release to be
configured differently.

Once you have downloaded and uncompressed your Indico distribution you can
upgrade by:

 1.  From the 'Indico distributed directory' run the Upgrade script using:

    "setup.py upgrade"

     1. You will then be asked to give the directory path of the MaKaC package
        or to type 'default' if you did not specify the "pkgdirectory" on the
        original installation.

     2. Follow the instructions given.

 2.  From the 'Indico distributed directory' run the setup install script
    using:

    "setup.py install"

 3. Restart the Apache Server.

Your upgraded Indico version will now be installed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

6. Explanation of the XML Configuration File 'config.xml'

6.1. Path Directories

See Default Installation for the default configurations of these paths

Numbered sections may not be in the same order in the actual config.xml file

<!--Enter Path names in between the pathdir tags, e.g.<pathdir>c:\tmp</pathdir>
or leave blank for default-->

 <paths>
(1)   <pathname>pkgdirectory</pathname>
     <pathdir></pathdir>
 </paths>

<!--htdocs needs to be the same directory as where you set the modpython handler
(or blank)-->
 <paths>
(2)   <pathname>htdocs</pathname>
     <pathdir></pathdir>
 </paths>

 <paths>
(3)   <pathname>archive</pathname>
     <pathdir></pathdir>
 </paths>

 <paths>
(4)   <pathname>temp</pathname>
      <pathdir></pathdir>
 </paths>

 <paths>
(5)   <pathname>tpls</pathname>
    <pathdir></pathdir>
 </paths>

<paths>
(6)   <pathname>ssheets</pathname>
    <pathdir></pathdir>
 </paths>


(1) The main package directory, this is where the main package files for the
    Indico program will be put on you machine,this will be under a folder
    called MaKaC.
(2) The htdocs directory, this directory holds the Apache-link files for the
    webinterface.
(3) The archive directory, multimedia files attached to the conferences will be
    stored in this directory.
(4) The temporary directory, files being uploaded and any other temporary files
    will be stored into this directory, Note: This directory needs to have a
    fair amount of space available.
(5) The templates directory, templates for the webinterface are kept in this
    directory.
(6) The stylesheets directory, the stylesheets are stored in this directory

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

6.2. Database, Access Rights, Url, Email, SMTP and OAI Parameters

<!--Enter database parameters in between tags, e.g. <port>1234</port>
or leave as they are for default-->

 <db_param>
     (1)     <host>databasehostname</host>
     (2)     <port>9675</port>
 </db_param>

<!-- Enter user and group name for access rights on the Public Folder
(only applicable for linux installations)-->

 <access>
     (3)     <user></user>
     (4)     <group></group>
 </access>

<!--Enter url base in between tags, e.g. <url>http://webserverhostname/MaKaC</url>
or leave as it is for default-->


     (5) <url>http://webserverhostname/MaKaC</url>

<!--Enter support email in between tags, e.g. <email>indico-project@cern.ch</email>
or leave for default-->


     (6) <email>indico-project@cern.ch</email>


<!--Enter SMTP Server to send Email or leave for default-->

     (7) <smtp>smtp.cern.ch</smtp>

<!--OAI Parameters, leave for default -->

     (8) <OAI>
             <logfile>/tmp/oailog.log</logfile>
             <nb_record>100</nb_record>
             <nb_ids>100</nb_ids>
             <oai_rt_exp>90000</oai_rt_exp>
             <namespace>eAgora.cern.ch</namespace>
             <iconfNS>URL_base</iconfNS>
             <iconfXSD>URL_base+"/iconf.xsd"</iconfXSD>
             <reposName>eAgora</reposName>
             <reposId>eAgora.cern.ch</reposId>
       </OAI>


(1) The database host, this parameter holds the location of the host that the
    database is stored on.
(2) The database port, this parameter holds the port number of which to contact
    the database.
(3) The user for access, this parameter holds the user for which the public
    folder will be given rights to.
(4) The group for access, this parameter holds the group for which the public
    folder will be given rights to.
(5) The Base Url, the url from which Indico can be reached from a web browser.
(6) The support email, the email address for people to contact with support
    issues.
(7) The smtp server, the server to allow emails to be sent out.
(8) The OAI parameters, these are for configuring the open archive interface.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

6.3. File Types and System Icons

<!--Known file types-->

(1) <FileType>
            <type>DOC</type>
            <name>Ms Word</name>
            <loc>application/msword</loc>
            <img>doc.gif</img>
   </FileType>

<!-- System Icons -->

(2) <SysIcon>
             <icon>modify</icon>
             <pic>link.gif</pic>
   </SysIcon>

<!-- Stylesheets-->


(3)   <event>
          <eventname>simple_event</eventname>
              <sheets>
                        <view>static</view>
                        <style>static</style>
              </sheets>
    </event>


<!-- Default Stylesheets -->

(4) <defaultss>
                <eventid>simple_event</eventid>
                <sheet>lecture</sheet>
   </defaultss>


(1) FileTypes, These specify the different file types and the name, location
    and image associated with them that are available within Indico.
(2) System Icons, These specify the icon name and the image associated with
    them.
(3) Stylesheets, These specify the stylesheets available for each event with
    the event name, view and stylesheet.
(4) Default Stylesheets, These specify the default stylesheet for each event
    with the event name and stylesheet.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

7. Notes

 a. If you would like to check that the config.xml file is valid once you have
    changed it there is a schema called config.xsd in the dist directory which
    you may validate it with. To do this you can use

     http://apps.gotdotnet.com/xmltools/xsdvalidator/Default.aspx