Install OTRS on Microsoft Windows

This document describes the installation of the OTRS on systems running Microsoft Windows (Win32). It has been tested it on Windows 2000 and XP, it should run on Windows NT4 and 2003, too. Take care to keep your operating system up-to-date prior to installing. Please have a look at http://windowsupdate.microsoft.com/ therefore.

Please note that we do not support 16-Bit-Windows Systems with this installer (e.g. Windows 98, 98SE, ME).

otrs4win32 - The Automatic Installer

We provide an automatic installer for your convenience that will install all of the needed software components for you on a fresh (!) and up-to-date Win32 system and strongly recommend it's use.

Important: The contained software versions are: OTRS 1.2.0 beta 2 (http://otrs.org/), CRONw 1.4.1b (http://cronw.sourceforge.net/), Apache 2.0.47 (http://httpd.apache.org/docs-2.0/), MySQL 4.0.14 (http://www.mysql.com/products/mysql/), PHP 4.3.3 (http://www.php.net/), PEAR (http://pear.php.net/), Perl 5.8.0 (http://www.perl.org/), mod_php 4.3.3 (http://www.php.net/manual/en/install.apache2.php), mod_perl 1.99_10 (http://perl.apache.org/), mod_ssl 2.0.47 (http://www.modssl.org/), openssl 0.9.7b (http://www.openssl.org/), PHPMyAdmin 2.5.1 (http://www.phpmyadmin.net/), Webalizer 2.01-10 (http://www.mrunix.net/webalizer/), Mercury MailTransport System v3.32 (http://www.pmail.com/overviews/ovw_mercury.htm), JpGraph 1.12.1 (http://www.aditus.nu/jpgraph/), FileZilla FTP Server 0.8.5 (http://filezilla.sourceforge.net/).

Download

Download the current release - you may use our http://otrs.org/download as a starting point. It's an executable .exe file, it's name follows this conventions: otrs4win32-<OTRS-VERSION>-<STATUS>.exe. You may also want to verify the corresponding md5 sum after download - find it besides the files on the servers. We herefore recommend md5-summer: http://md5summer.org/. Give it a try, it's a fine piece of GPL software.

Installation

Obtain administrative rights on your box by logging in as an administrator or by using "Run as...". Start the installer and follow the instructions. No reboot should be required afterwards.

Installation Issues

This release is suitable only for OTRS systems that are about to be freshly installed, ie. you are currently not encouraged to upgrade your existing OTRS installation. In fact, the installer does not provide any mechanism to do so - see the subsequent part of this documentation that refers to Upgrading.

Start The OTRS System

Make sure there are no other server applications running on the ports 25 (smtp), 80 (http), 443 (https), 3306 (MySQL). If so, find out, what servers they are and if they are supposed and/or required to run at this time on your machine. Examples were Microsoft's IIS webserver running silently in the background or the correspnding SMTP service. You'll have to shut them down to start OTRS.

To start your system's servers now, you may use the provided option on the finishing page of the installer dialogue labeled 'Run otrs4win32'. This does the same as the Start Menu entry 'Start All Servers' in the section "Services" (see below), namely executing the script 'all_startservices.bat' located in the root directory of otrs4win32. By default, all servers needed for OTRS are installed as services.

Please be so patient to wait a little while until Apache has completed the start up phase - this may last for a few minutes. Per default, the ApacheMonitor is startetd after the installer has run as well as WinMySqlAdmin, a monitor for MySQL - watch their symbols in the taskbar, they change from 'Red' to 'Green' when Apache and MySQL are ready to serve you:

ApacheMonitor and WinMySqlAdmin both show 'Red' - be patient...

Wait while Apache still shows 'Red' - MySQL might show 'Yellow' for a short time.

Apache still is not ready - but MySQL is.

Both are 'Green' now - you're on Go!

Please note that both monitor programs are only started automatically after the installation has finished. After a reboot you can start them via the Start Menu.

Visit http://localhost/otrs/installer.pl to complete the Web installer, which will create and populate the database. Afterwards you're guided to the login page: http://localhost/otrs/index.pl.

The customer frontend is here: http://localhost/otrs/customer.pl

This release is built upon Apachefriends' XAMPP, and therefore you benefit from XAMPP's features, too. Visit http://localhost/index.html (include the filename!). This is XAMPP and its components - you'll find OTRS in the left-hand menu. Click on it to get to the informational page about OTRS.

There are some informational links in the Start Menu, f.e. to phpMyAdmin, WinMySqlAdmin and ApacheMonitor.

How To Stop The Servers (if ever...)

If you installed the servers as system services, you may use the system's service control area to stop them, although you don't need to, because they will be terminated at shutdown time properly. Additionally, they need not be shut down if you actually do not work in OTRS, but should be kept running to let the maintenance scripts perform their actions at their given times.

Regarding the Standalone versions of the servers: For Apache, you may simply close it's control window. To safely shut down MySQL, use it's Start Menu entry or issue the script mysql_stop.bat. Shut down Mercury via it's file menu or the keyboard shortcut Alt-F4 when the Mercury window has the focus. Stop the CRONw service via the Start Menu or by issuing net stop cron.

Uninstallation Instructions

If you ever want to remove otrs4win32 from your box, simply stop all of the servers, uninstall all of their eventually installed services and delete the directory holding the application. For all this we provide an uninstaller, found in the installation directory. You may perform some of the required steps manually via the Start Menu, if you want to.

The uninstall process will guide you through what will be uninstalled. No Reboot should be required.

Additionally, it provides some means to actually REinstall some aspects of the software. This were the service, the Start menu entries and the entries in Windows' Registry.

Upgrading

These instructions are for people upgrading their otrs4win32 installation from 1.1.3 or prior to 1.2.0:

Step-by-Step: The Manual Installation

This section of the installation instruction set deals step-by-step with installing OTRS manually on systems running Win32. Of course we do recomend the usage of our otrs4win32 Installer. It is much easier to use!

Needed Software

You will need three main components on your system, a webserver (Apache), a database (MySQL) and the programming language Perl.

The whole installation will assumingly take place on drive D:, but you may install wherever you like, for sure. All you have to do is replace every occurence of D: or d: with your choice, f.e. c:\Programs. It is *no* good idea to have spaces in the installation path, so c:\program Files\otrs won't be a lucky choice.

Install PERL

Download Perl, Version 5.6.1 build 633 from http://www.activestate.com/Products/Download/Download.plex?id=ActivePerl. We recommend chosing the MSI version.

Install Perl using the default values to D:\Perl.

Install Additional PERL Packages

Download the OTRS-Win32-Perl-Packages in one file (coming via FTP from ftp.otrs.org) and unpack it into D:\Perl, preserving directory structure.

Installing The Webserver

OTRS requires a webserver to run. You may choose the one of your choice, it will probably run on every perl-enabled webserver. We tested it on Sambar 5.2 & above and on Apache, both 1.3 and 2.0. mod_perl is only availabe for Apache. Currently, only mod_perl-1.0 on Apache 1.3.27 is covered in these instructions.

Installing Apache

Download the Apache of your choice (1.3.27 and/or 2.0.43) and install it/them. We recommend you choose D:\Apache as root for *both* versions. The resulting directory structure will be:

D:\Apache\           --- home of both
D:\Apache\Apache\    --- home of Apache 1.3
D:\Apache\Apache2\   --- home of Apache 2.0

Tip: You may install both 1.3 and 2.0 on the very same machine, they can both be running and may both be used at the same time, if you like to. All you have to do is to ensure they are not configured to run on the same port. The second installation willing to start on port 80 won't succeed in doing so. So configure Apache 1.3 to run on port 80, Apache 2.0 to run on port 81. You could even configure the Sambar webserver (see different section in this manual) to run on port 82, if you'd like to, or choose your own port configuration. Surely one webserver running one version would be enough - the rest is for geeks ;)

Install MySQL

Download MySQL from http://www.mysql.com/downloads/ and install it in D:\mysql, under Win 2000/XP as a service, too. Start it. Not thoroughly tested in this manual installation procedure is MySQL Version 4.0 - but as it is included in the automatic installer you may give this version a try instead of the older 3.23.

For a more comfortable configuration interface We recommend installing phpMyAdmin from http://www.phpmyadmin.net, too, location: D:\mysql\phpMyAdmin. This will require PHP to be installed, which always is a very good idea.

We change the passwort for root later.

Install OTRS

Last but least - the beast!

Download OTRS as a tarball (.tar.gz): http://otrs.org/download and unzip it to d:\, preserving the directory structure. A directory called otrs will be created on D:\

Configuration

Configuring Perl

We now patch our Perl because it doesn't suit our needs in the default installation, there are some so called "packages" missing. You did download them above, didn't you?

Open a command box and enter this:

C:\>cd /d D:\Perl\packages

D:\Perl\packages>install.bat
  [...returned ouput snipped...]

The install routine places the file mod_perl.so in \Apache\Apache\modules. By the time of this writing, you will have to manually adjust the path in install.bat, if you installed Apache in another place or copy mod_perl.so manually to your Apache's modules directory.

Your Perl should now look like this or even better:

D:\Perl\packages>ppm query
  [...returned ouput shortened...]
  Archive-Tar      [0.072      ]
    Authen-SASL      [2.03       ]
    Compress-Zlib    [1.16       ]
    Convert-ASN1     [0.16       ]
    DBD-Mysql        [1.2200     ]
    DBI              [1.27       ]
    Digest           [1          ]
    Digest-HMAC      [1.01       ]
    Digest-MD2       [2          ]
    Digest-MD4       [1.1        ]
    Digest-MD5       [2.20       ]
    Digest-SHA1      [2.01       ]
    File-CounterFile [0.12       ]
    Font-AFM         [1.18       ]
    GD               [1.27.2     ]
    GDGraph          [1.32       ]
    GDTextUtil       [0.80       ]
    HTML-Parser      [3.26       ]
    HTML-Tagset      [3.03       ]
    HTML-Tree        [3.11       ]
    IO-Socket-SSL    [0.92       ]
    IO-stringy       [2.108      ]
    MD5              [2.02       ]
    MIME-Base64      [2.12       ]
    MIME-tools       [5.411a     ]
    MailTools        [1.58       ]
    Net-DNS          [0.33       ]
    Net_SSLeay.pm    [1.22       ]
    PPM              [2.1.6      ]
    SOAP-Lite        [0.55       ]
    Storable         [1.0.12     ]
    Test-Simple      [0.47       ]
    Tk               [800.023    ]
    URI              [1.19       ]
    XML-Parser       [2.27       ]
    XML-Simple       [1.06       ]
    libnet           [1.12       ]
    libwin32         [0.19.1     ]
    libwww-perl      [5.64       ]
    mod_perl         [1.27_01-dev]
    perl-ldap        [0.26       ]

You may now delete the files in D:\Perl\packages, if you want to, but you don't have to.

That's it for Perl.

Configuring Apache

In the following, We will refer to 'Apache' only, the process is the same for both versions 1.3 and 2.0.

Open Apache's configuration file httpd.conf, it is located in d:\Apache\Apache\conf\. Append these lines to the end of the file, adjust them to your needs:

# uncomment the following two for Apache2!
LoadModule perl_module modules/mod_perl.so
AddModule mod_perl.c

### added for OTRS (http://otrs.org/)

<IfModule mod_alias.c>
    Alias /otrs/ "d:/otrs/bin/cgi-bin/"
    Alias /otrs-web/ "d:/otrs/var/httpd/htdocs/"
    PerlModule Apache::Registry
</IfModule>

<Location /otrs>
    Options ExecCGI
    Order deny,allow
    Deny from all
    allow from 127.0.0.1

    SetHandler cgi-script
    ScriptInterpreterSource registry

    <IfModule mod_perl.c>
        SetHandler  perl-script
        PerlHandler Apache::Registry
        PerlSendHeader On
    </IfModule>

</Location>

# load all otrs modules
Perlrequire d:/otrs/scripts/apache-perl-startup.pl

# MaxRequestsPerChild (so no apache child will be to big!)
#MaxRequestsPerChild 400
# depends on your RAM

Take a little time to configure the rest of httpd.conf, too. Open d:\otrs\scripts\apache-perl-startup.pl and change these lines:

1:
#! D:/Perl/bin/perl
10,11:
use lib "d:/otrs/";
use lib "d:/otrs/Kernel/cpan-lib";
38,39:
#use Kernel::System::AuthSession::IPC;
use Kernel::System::AuthSession::DB;
46,47:
#use Kernel::System::Log::SysLog;
use Kernel::System::Log::File;

That's it for Apapche. We will restart Apache later.

Configuring MySQL

Secure your MySQL by providing good passwords for the users @%, root@% und root@localhost. This can easily be done via phpMyAdmin.

Let's fill the database. You can do this via the command line, as show here (output not shown):

C:\>cd /d d:\mysql
D:\mysql>mysql -u root -p password -e 'create database otrs'
D:\mysql>mysql -u root -p password otrs < d:\otrs\scripts\database\otrs-schema.mysql.sql
D:\mysql>mysql -u root -p password otrs < d:\otrs\scripts\database\initial_insert.sql
D:\mysql>mysql -u root -p -e 'GRANT ALL PRIVILEGES ON otrs.* TO otrs@localhost IDENTIFIED BY "some-pass" WITH GRANT OPTION;'
D:\mysql>mysqladmin -u root -p password reload

We recommend using phpMyAdmin under http://localhost/phpMyAdmin instead of working on the command line. You create the database right on the start screen. Now you click the tab "SQL", and enter d:\otrs\scripts\database\otrs-schema.mysql.sql in the textfield labeled "or File:". Click OK. If all went ok, enter d:\otrs\scripts\database\initial_insert.sql and click OK.

Now commit this command:

GRANT ALL PRIVILEGES ON otrs.* TO otrs@localhost IDENTIFIED BY "irgendeinpasswort" WITH GRANT OPTION;

That's it for MySQL, which we provided with the database otrs, its corresponding tables and the user otrs@localhost.

Configuring OTRS

CONFIG.PM

Now you teach OTRS s.th. about you. First create your configuration file:

C:\>cd /d d:\otrs\Kernel
D:\otrs\bin>copy Config.pm.dist Config.pm

Despite your settings concerning FQDN etc., you set the following in d:\otrs\Kernel\Config.pm:

    # -----------------------------------------------------#
    # Sendmail
    # -----------------------------------------------------#
    $Self->{'SendmailModule'} = 'Kernel::System::Email::SMTP';
    $Self->{'SendmailModule::Host'} = 'smtp-server.of.your.provider';
    $Self->{'SendmailModule::AuthUser'} = 'smtp-username';
    $Self->{'SendmailModule::AuthPassword'} = 'smtp-password';
    # -----------------------------------------------------#
    # directories
    # -----------------------------------------------------#
    $Self->{Home} = 'd:/otrs';
    $Self->{CounterLog} = '<OTRS_CONFIG_Home>/var/log/TicketCounter.log';
    $Self->{ArticleDir} = '<OTRS_CONFIG_Home>/var/article';
    $Self->{StatsPicDir} = '<OTRS_CONFIG_Home>/var/pics/stats';
    $Self->{TemplateDir} = '<OTRS_CONFIG_Home>/Kernel/Output';
    $Self->{TempDir} = '<OTRS_CONFIG_Home>/var/tmp';
    # ----------------------------------------------------#
    # LogModule                                           #
    # ----------------------------------------------------#
    $Self->{LogModule} = 'Kernel::System::Log::File';
    # -----------------------------------------------------#
    # own config settings                                  #
    # config settings taken from Kernel/Config/Defaults.pm #
    # -----------------------------------------------------#
    # $Self->{SessionUseCookie} = 0;
    $Self->{SessionModule} = 'Kernel::System::AuthSession::DB';

A note about your FQDN: This is the called Full Qulified Domain Name of your PC, just like your IP adress it's unique across the universe ...ah... internet, of course. If you're using a dial-up line to connect to the internet, your FQDN will always be a different one each time you dial anew. This is indeed ok for OTRS, but it's not nice if exim announces itself with a wrong name. It can lead to difficulties in mail delivery.

To solve this problem you can use so called Dynamic DNS services like http://www.dyndns.org/. By using a client such as DirectUpdate (http://www.directupdate.net/) you submit your IP adress to dyndns.org each times it changes and can thereby obtain a FQDN, for example gogos-pc.home-ip.net. You can even forward your domain http://www.thisismydomain.com/ to your home PC. If you got further questions concerning Dynamic DNS services, don't hesitate to ask - but now back to OTRS :)

The First Start

(Re-)Start your Apache installation(s) using the Apache monitor, proabably located in your task bar. Sometimes it's a good idea to restart the whole box.

Now see OTRS in action for the first time. Call http://localhost/otrs/index.pl in your favourite browser.

The user name is "root@localhost", the password is "root", both without the quotes.

Important: It's a *very good* idea to exactly *now* change the above password on http://localhost/otrs/index.pl?Action=AdminUser

System Email Addresses & POP3

You set your system email addresses here: http://localhost/otrs/index.pl?Action=AdminSystemAddress. These are the addresses your customers lateron use to reach your OTRS.

You create POP3 accounts for each system email here: http://localhost/otrs/index.pl?Action=AdminPOP3

Your OTRS is now ready, you can start! Have a look around the interface and work on the test ticket provided.

Now write an email to one of the system email addresses. Enter this in your browser, it provides the email to OTRS. http://localhost/obin/PostMasterPOP3.pl. We will later automate this.

Your email will be visible in the queue Raw - that's here: http://localhost/otrs/index.pl?Action=AgentQueueView. Answer this first inquiry.

Tip: It is NO good idea to use one of the System Email Addresses to address the system, this will produce failures.

No CRON Jobs on Apache

Please note that Apache cannot CRON. You may therefore want to visit http://cronw.sourceforge.net/ for a Perl-based CRON solution for 32-Bit Windows that runs as a system service. The webserver Sambar has a built-in cron-service besides loads of other functionalities and can also be configured to serve OTRS.

Done!

Congratulations, you hopefully were successful in installing OTRS on Win32!

If s.th. still is not as clear as it should be or if you are getting nothing more than error messages instead of the interface of OTRS, don't hesitate to mail otrs-win32 at robertkehl.de. Hopefully you get a ticket back ;-)

We would be more enlighted if you'd send some success stories!

Have fun using your OTRS on Windows32!

Beginner's Help: Command Boxes: Throughout this document, we will need to enter commands directly into the system quite often. We do this in a so called command box. Other names are command line, (DOS) prompt or shell. Here is how to invoke a command box on Windows:

Click Start, then Execute and enter cmd in the dialogue box popping up. Hit Return on your keyboard or click OK. A (usually black) box appears - if it doesn't, you're not on a 32-bit system. The box will be showing something similar to this:

Microsoft Windows 2000 [Version 5.00.2195]
(C) Copyright 1985-2000 Microsoft Corp.

C:\>

You may now enter commands such as

Microsoft Windows 2000 [Version 5.00.2195]
(C) Copyright 1985-2000 Microsoft Corp.

C:\>cd /d d:\otrs\bin\cgi-bin

D:\otrs\bin\cgi-bin>dir
 Datenträger in Laufwerk D: ist Aurelia
 Datenträgernummer: C8F1-F408

 Verzeichnis von D:\otrs\bin\cgi-bin

20.01.03  00:20         <DIR>          .
20.01.03  00:20         <DIR>          ..
08.06.02  23:37                     10 .cvsignore
18.01.03  02:14                     20 .htaccess
09.01.03  16:06                 20.734 customer.pl
09.01.03  16:06                 19.014 index.pl
03.01.03  17:17                  4.203 installer.pl
03.01.03  17:17                  5.450 pic.pl
               6 Datei(en)         49.431 Bytes
               2 Verzeichnis(se),   9.825.726.464 Bytes frei
D:\otrs\bin\cgi-bin>

This will bring you to your OTRS executable directory and show it's contents. The /d switch tells Windows to also change the drive letter, if necessary, i.e. to directly switch to the given directory, even over partition boundaries.

Please note that this is a sample output only, and it's from my box, a german Windows 2000 installation, as you see. It will probably (hopefully!) look different on your box.

You can customize the appearance of command boxes by clicking in the upper left corner of the window and choosing Properties. This were esp. useful for the default colors and sizes of your command boxes.

It will help if you get a little bit comfortable with command boxes and working from the command line in general. Search with Google for help with command lines.