OTRS CVS - Manual
Prev | Chapter 1. Install the beast. | Next

# 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

    # --
    # INSTALL description of OTRS
    # Copyright (C) 2001-2003 Martin Edenhofer <martin+code@otrs.org>
    # --
    # $Id: install-cli.sgml,v 1.3 2004/03/02 08:40:22 robert 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-2002 Martin Edenhofer <martin+code@otrs.org>
    # --
    # $Id: install-cli.sgml,v 1.3 2004/03/02 08:40:22 robert 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://jakarta.apache.org/turbine/turbine-2/howto/torque-howto.html

    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-2003 Martin Edenhofer <martin+code@otrs.org>
    # --
    # $Id: install-cli.sgml,v 1.3 2004/03/02 08:40:22 robert 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

Prev | Home | Next
Install the beast. | Up | Install OTRS on Microsoft Windows