Using the tar.gz file to install OTRS on any Linux/Unix plattform

This section is a guide for installing OTRS on any Linux. Please use this way only in case you feel comfortable with it otherwise use the RPM. Before starting the installation have a look at http://otrs.org/ and check if a newer and better version of the tar.gz file is available. If so please download it and use the newer documentation and the newer rpm.

Install


Software requirements?
======================

  On all Perl-Platforms! You need:
    * min. Perl5
    * Database (e. g. MySQL, PostgreSQL)
    * Webpserver (mod_perl isn't required but "very nice" to have)
    * some CPAN-Module (DBI, DBD::mysql, Digest::MD5) and for stats (GD, 
      GD::Text, GD::Graph, GD::Graph::lines, GD::Text::Align)

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

This few steps describe an OTRS installation incl. webserver and database 
settings. The OTRS user is "otrs" and the home (root) directory is /opt/otrs
(of cause you can choose an other directory or/and OTRS user). 

1. Install CPAN Modules (if needed):
   ---------------------------------
   a) Install the RPMs if your distributions provides RPMs for
      the CPAN modules. 

   b) Install the modules via CPAN (http://www.cpan.org/)
      perl -MCPAN -e shell;
      ...
      install Digest::MD5
      ...

      and maybe the GD stuff (stats support, not required!)
      ...
      install GD
      install GD::Text
      install GD::Graph
      install GD::Graph::lines
      install GD::Text::Align
      ...

   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/PostMaster.pl 
      /opt/otrs/bin/PostMaster.pl syntax OK
      $shell:~>

    If you get "syntax OK" it seems to be Ok. Go ahead.

2. Create user: 
   ------------
    Add 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 nogroup otrs

    (SuSE=nogroup, Red Hat=apache)

3. Install tar.gz:
   ---------------
   $shell: cd /opt/
   $shell: tar -xzvf otrs-xxxx-xx-xx.tar-gz
   $shell: chown -R /opt/otrs/* otrs

4. Demo config files:
   ------------------  
    There are several OTRS demo config files in $OTRS_HOME/Kernel/*.dist
    and $OTRS_HOME/Kernel/Config/*.dist. Make copies of all demo config files:
  
      cp Kernel/Config.pm.dist Kernel/Config.pm
 
      cd Kernel/Config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

    Or if you are installing OTRS an a Windows system:

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

5. Webserver:
   ----------
   [follow README.webserver] 

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

7. Config file ($HOME/Kernel/Config.pm):
   -------------------------------------
   If you used the Web-Installer, you can skip this point. If not,
   set some Kernel::Config ($HOME/Kernel/Config.pm) Options (FQDN, SystemID, TicketHook, 
   Home, ...)

8. File Permissions:
   -----------------
   Set the file permissions with 
   "$HOME/bin/SetPermissions.sh <OTRS_HOME> <OTRS_USER> <WEBSERVER_USER> [OTRS_GROUP] [WEB_GROUP]"
   e. g. 
     Webserver with OTRS user: "SetPermissions.sh /opt/otrs otrs otrs" 
     Webserver with wwwrun user (e. g. SuSE): "SetPermissions.sh /opt/otrs otrs wwwrun" 
     Webserver with apache user (e. g. Redhat): "SetPermissions.sh /opt/otrs otrs apache users apache"

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

   --> goto AdminArea and set some config settings (UserAdd, Queues, ...).

   Finished.

10. First Email:
   ------------
   use the procmailrc of the OTRS user --> ~otrs/.procmailrc or e. g. /opt/otrs/.procmailrc

   --> send emails to the otrs user (e. g. otrs@localhost)

   or pipe an email directly into $OTRS_HOME/bin/Postmaster.pl
    (e. g. 'cat /opt/otrs/doc/test-email-1.box | /opt/otrs/bin/PostMaster.pl').

11. Cronjobs for the OTRS user:
    ---------------------------
    There are several OTRS demo cronjobs in $OTRS_HOME/var/cron/*.dist. 
    Make copies of all of the demo cronjobs:
 
      cd var/cron
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

    Or if you are installing OTRS an a Windows system:

      cd var/cron
      copy *.dist *.


    Use $OTRS_HOME/bin/Cron.sh {start|stop|restart} to start or stop this cronjobs
    from $OTRS_HOME/var/cron/* (.dist will be ignored). 

    >> Note: Install this cronjobs as OTRS user. <<


Remark: For installation questions ask otrs@otrs.org (http://lists.otrs.org/).

Have a lot of fun.

 Martin Edenhofer 

(January 2003 Frankfurt/Germany)

EOF

Database


Where can I find the database description files?
================================================

XML:
====
$HOME_OTRS/install/database/OpenTRS-schema.xml

The XML description files for torque which generate the SQL for your 
target database e. g. MySQL, PostgreSQL, DB2, Oracle, ...)

More Infos: http://jakarta.apache.org/turbine/turbine-2/howto/torque-howto.html 

MySQL: 
------
$HOME_OTRS/install/database/OpenTRS-schema.mysql.sql

PostgreSQL:
-----------
$HOME_OTRS/install/database/OpenTRS-schema.postgresql.sql

Initial insert file:
====================
$HOME_OTRS/install/database/initial_insert.sql contains all needed standard 
values. At first use the OpenTRS-schema.*.sql and the insert this file.



DB - Setup Example (MySQL):
===========================
Create OTRS database:
---------------------
shell> mysql -u root -p -e 'create database otrs'

Create the OTRS tables:
-----------------------
shell> mysql -u root -p otrs < install/database/OpenTRS-schema.mysql.sql

Insert inital data:
-------------------
shell> mysql -u root -p otrs < install/database/initial_insert.sql

Create an database user:
-----------------------
shell> mysql -u root -p -e 'GRANT ALL PRIVILEGES ON otrs.* TO otrs@localhost IDENTIFIED BY "some-pass" WITH GRANT OPTION;'

Reload the grant tables of your mysql-daemon:
---------------------------------------------
shell> mysqladmin -u root -p reload

**************************************************************
*                                                            *
* Change the DB-Settings (host, database, user and password) *
*                                                            *
*   $OTRS_HOME/Kernel/Config.pm                              *
*   [...]                                                    *
*   # Database                                               *
*   # (The database name.)                                   *
*   $Self->{Database} = 'otrs';                              *
*                                                            *
*   # DatabaseUser                                           *
*   # (The database user.)                                   *
*   $Self->{DatabaseUser} = 'otrs';                          *
*                                                            *
*   # DatabasePw                                             *
*   # (The password of database user.)                       *
*   $Self->{DatabasePw} = 'some-pass';                       *
*   [...]                                                    *
*                                                            *
**************************************************************

EOF

Webserver


Which webserver is needed?
==========================
I prefer the apache webserver (http://httpd.apache.org). 

Configuration:
==============
"After" this steps, you will get the login page at 
http://your-host/otrs/index.pl or http://your-host/otrs/installer.pl.

SuSE Linux:
===========
a) Install the RPM-Package (http://otrs.org/ - "rpm -i otrs-xxx.rpm").
 
b) The manual way:
  Use the "$OTRS_HOME/scripts/suse-httpd.include.conf" include config file.

  Add it to /etc/sysconfig/apache with HTTPD_CONF_INCLUDE_FILES
  [...]
  HTTPD_CONF_INCLUDE_FILES=/opt/otrs/scripts/suse-httpd.include.conf
  [...]

  Start SuSEconfig and restart the webserver (rcapache restart).


Or edit the httpd.conf directly:
================================
a)
 *) Change the webserver user (normaly wwwrun) to the OTRS user (otrs).

  [...]
  User wwwrun 
  [...]
  User otrs
  [...]
 
 *) If you can't change the user and group of your webserver (system-wide), 
    because you have other applications running on this server, you can
    also work with group permissions (more tricky). 

    Use "$HOME/bin/SetPermissions.sh <OTRS_HOME> <OTRS_USER> <WEBSERVER_USER> [OTRS_GROUP] [WEB_GROUP]"
    e. g. 
     Webserver with otrs user: "SetPermissions.sh /opt/otrs otrs otrs"   
     Webserver with wwwrun user (e. g. SuSE): "SetPermissions.sh /opt/otrs otrs wwwrun"
     Webserver with apache user (e. g. Redhat): "SetPermissions.sh /opt/otrs otrs apache"

b)
 *) 
  Without mod_perl (just CGI):
  ============================
  Add this to the cgi-bin stuff section in httpd.conf
  [...]
  ScriptAlias /otrs/ "/opt/otrs/bin/cgi-bin/"
  [...]

 *)
  With mod_perl (speed!):
  =======================
  Add this to the mod_perl stuff section in httpd.conf
  [...]
  Alias /otrs/ "/opt/otrs/bin/cgi-bin/"

  <Location /otrs>
    SetHandler  perl-script
    PerlHandler Apache::Registry
    Options ExecCGI
    PerlSendHeader On
  </Location>

  May you want use a mod_perl startup script. Compiled modules on startup 
  (speed!)! Use the mod_perl startup script which comes with otrs 
  (scripts/apache-perl-startup.pl).
 
  - Add startup script (scripts/apache-perl-startup.pl) to httpd.conf 
    [...]
    # load all otrs modules
    Perlrequire /path/to/otrs/scripts/apache-perl-startup.pl
    [...]

  Edit the scripts/apache-perl-startup.pl script:

   - Establish datababase connections on process startup (httpd).

     [...]
     use Apache ();
     use Apache::DBI ();
     Apache::DBI->connect_on_init('DBI:mysql:otrs', 'otrs', 'some-pass');
     # Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr)
     [...]

   - Change the otrs lib dir!
 
     [...]
     # --
     # set otrs lib path!
     # --
     use lib "/path/to/otrs/";
     use lib "/path/to/otrs/Kernel/cpan-lib";
     [...]

  Nice! You will love mod_perl! ,-)

c)
  Restart the webserver
  =====================

d)
  Web-Installer
  =============
   http://yourhost/otrs/installer.pl
 
  First login
  ===========
   http://yourhost/otrs/index.pl
   User: root@localhost
   PW: root

EOF