# --
# INSTALL description of OTRS
# Copyright (C) 2001-2010 OTRS AG, http://otrs.org/
# --
# $Id: INSTALL,v 1.55 2010/11/23 10:19:27 mg Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (AGPL). If you
# did not receive this file, see http://www.gnu.org/licenses/agpl.txt.
# --

Software requirements:
======================

Mandatory:
    * Perl 5.8.8 or higher (not Perl6)
    * Database (e. g. MySQL, PostgreSQL)
    * Webserver
    * some CPAN-Modules (see step 2 of the chapter "Installation" for details)

Optional:
    * On the Apache webserver, using mod_perl is highly recommended
    * LDAPv2 compliant server (e. g. OpenLDAP)


Installation:
=============

This few steps describe an OTRS installation with webserver and database
setup. The OTRS system user in this example is "otrs" and the installation
directory is /opt/otrs. You can adapt these values as needed.

1) Install tar.gz:
   ---------------
   shell> cd /opt/
   shell> tar -xzvf otrs-x.x.x.tar.gz
   shell> mv otrs-x.x.x otrs

2) Install CPAN Modules (if needed):
   ---------------------------------
   Use the following script to get an overview of all installed and
   required cpan modules.

   shell> perl /opt/otrs/bin/otrs.CheckModules.pl

   To install missing Perl modules, you can:

   a) Install the RPMs if your distributions provides RPMs for
      the required CPAN modules.

   - or -

   b) Install the required modules via CPAN shell (http://www.cpan.org/)

      shell> perl -MCPAN -e shell;
      ...
      install Digest::MD5
      install Crypt::PasswdMD5
      ...

   Any optional modules listed by the script should be installed depending
   on the special requirements of the target system.

3) Create OTRS user:
   -----------------

    Create user:

    shell> useradd -d /opt/otrs/ -c 'OTRS user' otrs

    Add user to webserver group (if the webserver is not running with OTRS user):

    shell> usermod -G www otrs

    (SuSE=www, Red Hat/Fedora=apache)

4) Demo config files:
   ------------------
    There are several OTRS demo config files in $OTRS_HOME/Kernel/*.dist
    and $OTRS_HOME/Kernel/Config/*.dist. They must be activated by copying
    them without the ".dist" filename extension.

      shell> cd /opt/otrs/
      shell> cp Kernel/Config.pm.dist Kernel/Config.pm
      shell> cd Kernel/Config/
      shell> for foo in *.dist; do cp $foo `basename $foo .dist`; done

    Or if you are installing OTRS an a Windows system:

      shell> copy Kernel/Config.pm.dist Kernel/Config.pm
      shell> cd Kernel/Config/
      shell> copy *.dist *.

5) Check if all needed modules are installed:
   ------------------------------------------
      shell> perl -cw /opt/otrs/bin/cgi-bin/index.pl
      /opt/otrs/bin/cgi-bin/index.pl syntax OK

      shell> perl -cw /opt/otrs/bin/otrs.PostMaster.pl
      /opt/otrs/bin/otrs.PostMaster.pl syntax OK

    "syntax OK" tells you all mandatory perl modules are installed.

6) Webserver:
   ----------
   [follow README.webserver]

7) File Permissions:
   -----------------
   File permissions need to be adjusted to allow OTRS to read and write files:

   shell> bin/otrs.SetPermissions.pl --otrs-user=<OTRS_USER> --web-user=<WEBSERVER_USER> [--otrs-group=<OTRS_GROUP>] [--web-group=<WEB_GROUP>] <OTRS_HOME>

   For example:
     Webserver with OTRS user:

       shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=otrs /opt/otrs

     Webserver with wwwrun user (e. g. SuSE):

       shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=wwwrun /opt/otrs

     Webserver with apache user (e. g. Redhat):

       shell> bin/otrs.SetPermissions.pl --otrs-user=otrs --web-user=apache --otrs-group=apache --web-group=apache /opt/otrs

8) Database setup:
   ---------------
   If you use MySQL, you can use the Web-Installer (http://yourhost/otrs/installer.pl).
   Otherwise, please follow README.database --> "DB - Setup Example".

9) Basic Configuration:
   --------------------
   If you used the Web-Installer, you can skip this point.
   Otherwise, set the mandatory configuration settings in /opt/otrs/Kernel/Config.pm,
   such as FQDN, SystemID, Ticket::Hook, Home and other settings you need.

10) First Login:
   ------------
   http://yourhost/otrs/index.pl
   User: root@localhost
   PW: root

   With this step, the basic system setup is finished.

11) First Email:
    ------------
   To check email reception, you can pipe an email directly into /opt/otrs/bin/otrs.Postmaster.pl:

   shell> cat /opt/otrs/doc/sample_mails/test-email-1.box | /opt/otrs/bin/otrs.PostMaster.pl

12) Cronjobs for the OTRS user:
    ---------------------------
   There are several OTRS default cronjobs in $OTRS_HOME/var/cron/*.dist.
   They can be activated by copying them without the ".dist" filename extension.

   shell> cd var/cron
   shell> for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Or if you are installing OTRS an a Windows system:

   shell> cd var/cron
   shell> copy *.dist *.

   To schedule these cronjobs on your system, you can use the script Cron.sh.
   Make sure to execute it as the OTRS system user!

      Scheduling the cronjobs for the first time:

      shell> /opt/otrs/bin/Cron.sh start

      Updating the cronjob schedulings after changes:

      shell> /opt/otrs/bin/Cron.sh restart

      Deallocating the cronjobs:

      shell> /opt/otrs/bin/Cron.sh stop


Notes:
======

Also you should read the OTRS performance tuning chapter on our homepage:
http://doc.otrs.org/3.0/en/html/.

If you encounter problems with the installation, you cane ask on the
mailing list otrs@otrs.org (http://lists.otrs.org/).

((enjoy)).

 Your OTRS Team

EOF
