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

This sectionon 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)
    * LDAPv2 compliant server (OpenLDAP for works fine, however LDAP isn't required)
    * some CPAN-Module (DBI, DBD::mysql, Digest::MD5, MIME::Base64 (if Perl < 5.8), Net::DNS) 
      for LDAP (Net::LDAP) 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):
   ---------------------------------
   Note: use "bin/otrs.checkModules" to get an overview of all installed and 
   required cpan modules.

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

   b) Install the required modules via CPAN shell (http://www.cpan.org/)
      perl -MCPAN -e shell;
      ...
      install Digest::MD5
      install Net::DNS
      install MIME::Base64 (if Perl < 5.8)
      ...

      if you plan to use an LDAP directory service you should install Net::LDAP
      ...
      install Net::LDAP
      ...
      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

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:
   ------------
   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 default cronjobs in $OTRS_HOME/var/cron/*.dist. 
    Make copies of all of the default 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>

  You may want to 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).
 
  - Change the default startup script location of your httpd to 
    $OTRS_HOME/scripts/apache-perl-startup.pl in httpd.conf 
    [...]
    # load all otrs modules
    Perlrequire /opt/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 (if needed)!
 
     [...]
     # --
     # 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