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

This section is a guide for installing OTRS on any Linux/Unix. 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 tar.gz.

Install

# --
# INSTALL description of OTRS
# Copyright (C) 2001-2004 Martin Edenhofer <martin+code@otrs.org>
# --
# $Id: install-cli.sgml,v 1.6 2005/08/04 10:51:51 cs Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (GPL). If you
# did not receive this file, see http://www.gnu.org/licenses/gpl.txt.
# --

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 course 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
      ...


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. 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.

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

7. 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 apache apache"

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

9. 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, ...)

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

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

   Finished.

11. 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').

12. 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. <<

Notes:
======

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

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

Have a lot of fun.

 Your OTRS Team

(January 2004 Frankfurt/Germany)

EOF

Database

# --
# README.database - database description of OTRS
# Copyright (C) 2001-2004 Martin Edenhofer <martin+code@otrs.org<
# --
# $Id: install-cli.sgml,v 1.6 2005/08/04 10:51:51 cs Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (GPL). If you
# did not receive this file, see http://www.gnu.org/licenses/gpl.txt.
# --

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

XML:
====
$HOME_OTRS/scripts/database/otrs-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://db.apache.org/torque/

MySQL:
------
$HOME_OTRS/scripts/database/otrs-schema.mysql.sql

PostgreSQL:
-----------
$HOME_OTRS/scripts/database/otrs-schema.postgresql.sql

Initial insert file:
====================
$HOME_OTRS/scripts/database/initial_insert.sql contains all needed standard
values. At first use the otrs-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 < scripts/database/otrs-schema.mysql.sql

Insert inital data:
-------------------
shell> mysql -u root -p otrs < scripts/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

# --
# README.webserver - webserver description of OTRS
# Copyright (C) 2001-2004 Martin Edenhofer <martin+code@otrs.org<
# --
# $Id: install-cli.sgml,v 1.6 2005/08/04 10:51:51 cs Exp $
# --
# This software comes with ABSOLUTELY NO WARRANTY. For details, see
# the enclosed file COPYING for license information (GPL). If you
# did not receive this file, see http://www.gnu.org/licenses/gpl.txt.
# --

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
  [...]
  Alias /otrs-web/ "/opt/otrs/var/httpd/htdocs/"
  ScriptAlias /otrs/ "/opt/otrs/bin/cgi-bin/"
  [...]

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

  <Location /otrs>
    SetHandler  perl-script
    PerlHandler Apache::Registry
    Options ExecCGI
    PerlSendHeader On
    PerlSetupEnv 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! ,-)

  PS: If you use mod_perl2 use the scripts/apache2-* scripts!

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