OTRS - Manual
Prev | Chapter 1. Install the biest. | Next

# 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

Prev | Home | Next
Install the biest. | Up | Basics about a Trouble Ticket System