Stud.IP Installation Guide
Version 1.2 (based on Stud.IP 1.0 - some details may differ)

Contents:

1 Installation
1.1 Programs and modules needed
1.2 Unpacking the files
1.3 Setting-up phplib
1.3.1 Adjusting the file local.inc
1.3.2 Basic module configuration
1.3.3 Further optional paramters in local.inc
1.3.4 Defining additional LaTeX-formats
1.4 Adjusting the values of php.ini
1.4.1 Entering values into php.ini
1.4.2 Changing values in php.ini using a <Directory>-directive
1.4.3 Changing values in php.ini using an .htaccess file
1.5 Sending emails 
1.6 Creating the MySQL database
1.7 Configuration of the Stud.IP basic system
1.7.1 Directories and paths
1.7.2 config.inc.php
1.8 Configuration of the Stud.IP modules and optional features
2 The first start of Stud.IP


1 Installation
--------------
Stud.IP relies on a LAMP-system (Linux/Apache/MySQL/PHP) for productive use. 
However an installation on a WAMP-system (Windows system) is possible, but 
not recommended as some of the core features like sending emails and graphic 
editing will not work.

IMPORTANT NOTE: This installation-guide is based on the assumption, that you 
have root rights regarding the web server, the PHP interpreter and the MySQL 
database. The instructions are not suitable for a web hosting setup where you 
only have limited to no control over the installation.


1.1 Programs and modules needed
-------------------------------
The following programs are needed for Stud.IP:

Basic components

- Apache Webserver (version 1.3 or better) (http://httpd.apache.org)
- MySQL database server (version 3.23 or better, we recommend version 4.0 or better) (http://www.mysql.com)
- PHP-Apache module (version 4.2.1 or better) (http://www.php.net)

Tools

Following Tools are needed for the basic functionality:
- zip (http://www.info-zip.org/pub/infozip/)

Needed for the optional LaTeX-Rendering-System:
- completely configured LaTeX-system (http://www.tug.org/teTeX/)
- dvips (http://www.radicaleye.com/dvips.html)
- ImageMagick (http://www.imagemagick.org/)

PHP-modules

The following modules must be compiled into PHP and are needed for the basic functionality:
- mysql
- gettext

In order to use the Chat, the following modules are needed:
- sysvshm
- sysvsem
(see section 1.8 "Configuration of the Stud.IP modules")

In order to use the export-tool, following modules are needed additionally:
- xml
- xslt
Furthermore the FOP (Formating objects Processor, http://xml.apache.org/fop/) 
and the Java Runtine Environment, JRE (http://java.sun.com), need to be installed.
(see section 1.8 "Configuration of the Stud.IP modules")

The installation of the actual LAMP system is presupposed  suitable 
instructions can be found in a great number on the Web.
Whether PHP, Apache and MySQL work correctly together 
can be tested with the following simple script (just copy the 3 lines 
into a text file with extension php in your web-root and access it using 
a web browser):

<?
phpinfo();
?>

All compiled-in modules will be listed and the php.ini configuration 
can be checked (see section 1.3 regarding this).


1.2 Unpacking the files
-----------------------
The downloaded file should be unpacked with 
	tar xjvf studip-1.2.0-1.tar.bz2
into a temporary  directory, which can be deleted or kept as 
reference after the installation.

Quick reference of the directories included in the package:

- studip-db			SQL-dumps for the database setup and demo data
- studip-doc		Installation documentation
- studip-config		Default configuration files (local.inc, config.inc.php)
- studip-htdocs		The Stud.IP core (later in the document-root
					of the webserver)
- studip-phplib		Stud.IP-adapted version of phplib
- studip-update		Migrationscripts for older Stud.IP-Versions
					(See README before upgrade please!)
- studip-varlib		Default-structure of the Stud.IP data-folders 
					outside the Apache-Document root directory.


1.3 Setting-up of the phplib
----------------------------
Stud.IP uses phplib-7.2d with slight modifications. The Orginal can 
be found at http://phplib.sourceforge.net/.

The following files were added:
- email-validation.inc (check of email-addresses and other information)
- smtp.inc (to send emails on a Linux system)
- ct_sql_patched.inc (small bugfix of ct_sql.inc, only for MySQL)

The following files were changed:
- prepend.php (above-mentioned files are included automatically)
- page.inc (functionality to abort login)

The adapted version is in the directory studip-phplib of the installation 
package and should copied into the Apache root directory. 
e.g.: If /usr/local/httpd is your apache root directory, then 
copy the files to /usr/local/httpd/php. For debian-Linux 3.0 the 
directory /usr/lib/apache is a good choice.

CAUTION: Do not put this include directory into the Document-Root 
of the weserver because the database passwords are stored in it!


1.3.1 Adjusting the file local.inc
----------------------------------
local.inc in the directory of the phplib is one of the two central
configuration files of Stud.IP. Most of the technical basic settings 
are defined here.

Rename the file local.inc.dist to local.inc and adapt the parameters 
to the local requirements. An explanation of each parameter is 
included in local.inc.

Note: As the module ILIAS CONNECT is optional you can leave the 
corresponding settings blank.

1.3.2 basic module configuration
--------------------------------
You can specify the modul configurations in local.inc in their appropriate
sections. Every module has a switch $<MODULNAME>_ENABLE which you can 
use to turn it on or off. Normally you can leave most of the settings like 
they are.

Only following options are important:
- If you want to use the export module, the values $FOP_SH_CALL and
  $JAVA_ENV_CALL must be set
- If you want to use the Ilias connect module, $ABSOLUTE_PATH_ILIAS must 
  contain the absolute path (URL) to you Ilias installation
- If you want to use the module SRI-interface (external pages), you must 
  define them your server name in $EXTERN_SERVER_NAME and set  
  $EXTERN_CONFIG_FILE_PATH to point to a directory, in which the configuration 
  files will be saved.
  CAUTION: The webserver needs writing access to that directory!

1.3.3 further optional parameters in local.inc
----------------------------------------------
Besides to the above mentioned options there are further parameters, 
that can be defined in local.inc optionally:
- $LATEXRENDER_ENABLE, $WIKI_ENABLE, $SCM_ENABLE, $SMILEYADMIN_ENABLE to set 
  up some basic system functions
- $ALLOW_GROUPING_SEMINARS, $ALLOW_SELFASSIGN_STUDYCOURSE, 
  $SHOW_TERMS_ON_FIRST_LOGIN you might want to set of you work with 
  an external authentication (LDAP or similar).
- Settings for the authentification plugins (need to be adjusted only if 
  you use an external authentication).

1.3.4 Defining additional LaTeX-formats
---------------------------------------
The LaTeX rendering system is configured to process mathematical formulas by 
default, but can be extended to include also formats for setting phonetic fonts, 
Arabian, Hebrew, Cyrillic writing, certain diagram models etc.

For this purpose attention is to be paid to two points:

- The variable $LATEX_FORMATS must be extended with an entry for the additional 
format (The precise syntax and two examples are given in local.inc.dist.)
- The additionally needed LaTeX packackes need to be available to the local machine.


1.4 Adjusting the values of php.ini
-----------------------------------
To get Stud.IP running some values in php.ini need to be adjusted. There 
are 3 different ways to do this:
- Set directly the corresponding values in the php.ini. 
- Set the values in httpd.conf of the Apache using a 
  <Directory>-directive. 
- Set the values via a .htaccess file. This variant would also be your choice, 
  if you install Stud.IP on a webserver of an external provider.

CAUTION: If you wand to use Stud.IP and ILIAS on the same server,
you need either variant 2 or 3!


1.4.1 Adjusting the values of php.ini
-------------------------------------
You should choose this installation variant only if you run Stud.IP 
as the only PHP program on the webserver.

In most cases php.ini can be found in one of the following directories:
/etc/httpd/, /etc or /etc/php4/apache

The following values must be adjusted:

auto_prepend_file = /usr/local/httpd/php/prepend.php

include_path = /usr/local/httpd/php

The include_path must be set to the directory you copied the Stud.IP phplib 
into.

register_globals = on

This option must be set in any case, as Stud.IP will only work with global 
variables at this time.

magic_quotes_gpc = on

This option must be set in any case, too.

upload_max_filesize = 8M

This value influences the maximum size of the files that can be uploaded to 
the webserver. If you want to accept larger files, set this value accordingly.

memory_limit = 8M

This value must correspond with upload_max_filesize.

post_max_size = 9M

This value must be set to a bit more than upload_max_filesize

max_execution_time = 300

This value influences the maximum execution time of a php-script. A higher 
value proved to be a good choice here.

1.4.2 Changing values in php.ini using a <Directory>-directive (recommended)

This variant allows the installation to coexist with other php programs 
ithout disturbing them and is therefore the recommended variant. 
You can find in /studip-config a file studip-httpd.conf which contains 
all necessary settings. Just copy it into your http.conf or use an include 
directive. Remember to check the paths!

1.4.3 Changing values in php.ini using an .htaccess file

This is similar to 1.4.2, but has the advantage that you don't need to have 
access to the configuration file of the webserver.
To make it work the setting

AllowOverride All

must be set in httpd.conf either globally or inside a <Directory>-directive 
that includes your Stud.IP path.

You can find an .htaccess file with all the necessary settings in /studip-config.


1.5 Sending emails
------------------
To get the registration module of Stud.IP working, the webserver needs to 
be able to send mails via the mailserver configured with $MAIL_HOST_NAME 
left blank for localhost). The reply-to field in all emails send by Stud.IP 
is set to abuse@<SERVER_NAME> so remember to forward the address to one of 
the administrators
NOTE: If the mail-system not set up properly either the self-registration nor the
creation of new user-accounts, because registration and password-mail will be sent 
directly direct to the user via the mail-system.
Registrierungsmail bzw. das Passwort auf diese Weise an die Nutzer zugestellt werden.


1.6 Creating the MySQL database
-------------------------------
You need an installed MySQL database version 3.23 or better to use Stud.IP.
The directory /studip-db contains the database dumps user below.

Use the following command to create the database:
mysql -e "create database studip"

Create the database tables:
mysql studip < studip-db/studip.sql

Load the basic presets into the database:
mysql studip < studip-db/studip_default_data.sql

To create a root user with
Username: root@studip
Password: testing
Also execute:
mysql studip < studip-db/studip_root_user.sql
(CAUTION: You should change that password immediately after installation!) 


If you want to use the resource management, load the following file as well:

mysql studip < studip-db/studip_resources_default_data.sql

If you want to test the system first of all, can you also load the following Demo data:

mysql studip < studip-db/studip_demo_data.sql
mysql studip < studip-db/studip_resources_demo_data.sql


Furthermore a data base user for studip with the rights 
SELECT, INSERT, UPDATE, DELETE, CREATE, DROP (for temporary tables) must be created.
(see also configuration of local.inc above)

Do not forget to restart the MySQL Datenbank (reload!) at the end please.


1.7 Configuration of the Stud.IP basic system
---------------------------------------------
The files stored in /studip-htdocs should be copied into the document-root 
directory of the webserver. In our example this should become 
/usr/local/httpd/htdocs/studip. If you use a different dir remember 
to set $ABSOLUTE_PATH_STUDIP in local.inc accordingly.

1.7.1 Directories and paths

The webserver (mostly user "wwwrun", group "nogroup"; check in 
httpd.conf if unsure) needs to have write access to the directories 
$UPLOAD_PATH, $ARCHIV_PATH, $TMP_PATH, $TEXCACHE_PATH (if you 
use LaTeX-Rendering) and $EXTERN_CONFIG_FILE_PATH (if you use 
the SRI-Interface) configured in local.inc. With the default values 
these are:

- Upload directory for all documents ($UPLOAD_PATH):
  /var/lib/studip/upload_doc/
- Directory to store the archived courses ($ARCHIV_PATH):
  /var/lib/studip/archive/
- Directory for configuration files of the external pages (SRI-Interface; 
  only if activated) ($EXTERN_CONFIG_FILE_PATH):
  /var/lib/studip/extern_config/
- Cache for rendered TeX-elements (only when LaTeX-Rendering is activated)
  ($TEXCACHE_PATH)
  <Document-Root>/pictures/tex/
- Storage of the uploaded user photos
  <Document-Root>/user
- Storage of smileys ($SMILE_PATH):
  <Document-Root>/user

The first three directories MUST NOT be accessible from outside via the webserver 
(i.e. dont put them into your web-root!), the TeX-cache and the user-photo 
directory, however, MUST be readable for the webserver.

Access to the system's temp directory (by default /tmp) must be ensured as well.


1.7.2 config.inc.php
--------------------
Rename the file config.inc.php.dist to config.inc.php.

Set $UNI_URL, $UNI_LOGOUT_ADD, $UNI_CONTACT and $UNI_INFO according to your 
needs. All other values can normally be left like they are. You can adapt 
them to your needs later on.

CAUTION: If you go into productive use, dont change any of the entries 
except the ones mentioned above as otherwise inconsistencies in the database 
may arise.

1.8 Configuration of the Stud.IP of modules and optional feature

Besides the basic system there are some Stud.IP modules which need which 
have additional requirements and need to be configured in advance.
Some of them are enabled in the distribution so check which of them you 
need and which of them you want to have turned off. (see 1.3.2 "basic 
module configuration").


Latex-Renderer
The LaTeX-Renderer can be enabled via $LATEXRENDER_ENABLE in the local.inc 
defaults to on). If it is enabled, LaTeX-Formulas can be set with [tex]  [/tex] 
at various places in Stud.IP.

Export-module:
To export data in HTML, PDF etc. formats XSLT-support for PHP is required.
If this is not provided by your PHP installation, you need to install the 
Sablotron and expat libraries (www.gingerall.com) and configure PHP again 
accordingly (configure --enable-xslt --with-xslt-sablot). For Debian 
distributions the package php4-xslt (apt-get install php4-xslt) does this. 

For the export as PDF the Objects Formatting processor (FOP) of the Apache 
XML Projekt is necessary. (http://xml.apache.org/fop/download.html)
FOP is programmed in Java and an executable JRE is needed therefore.
$FOP_SH_CALL must contain the complete path to the FOP starting-script. 
It might be necessary to include the path to a script which sets the Java 
environment variables in $JAVA_ENV_CALL (/etc/profile.d/alljava.sh for SuSE
Distributions).

Chat-module:
The Chat module requires the PHP modules sysvshm and sysvsem to be installed. 
If these modules are unavailable, the variable $CHAT_SERVER_NAME can be 
hanged to "ChatFileServer". This enables the file-based processing of chat 
data, but has a huge impact on performace which makes it not a recommendable 
for bigger installations.

Ilias-Connect-module: 
To use the module "Ilias Connect", which allows to attach Ilias learning 
modules to Stud.IP courses, an Ilias installation version 2.3.3 or better 
is needed. (Version 3.x is not yet supported!)

Copy the file studip-htdocs/lernmodule/studip2ilias.php to the Ilias 
root directory. Then a mysql user with SELECT, INSERT, UPDATE and DELETE 
rights for the Ilias database needs to be entered into local.inc and 
$ABSOLUTE_PATH_ILIAS adjusted to the complete URL of the Ilias installation.

Further modules such as the calendar, the resource management, the Wiki- 
or the Vote and Survey-modules require no specific configuration or optional software.

2 The first start of Stud.IP

http://localhost/studip should present you with the starting page of Stud.IP 
by now. If you have imported studip_root_user.sql, a root user has been already created: 
User name:	root@studip
Password:	testing

Further users can be created either via the Administration console (key symbol at the 
top right, global settings) or via Self-registration (if enabled in local.inc).

- The Stud.IP Crew <crew@studip.de> 2005

$Id: studip_installation_guide.txt,v 1.1 2006/03/16 15:19:49 anoack Exp $
