Developer

I had my fair share of troubles with OTRS (Open source Ticket Request System) in the past, in particular on an old Fedora/Ensim powered dedicated server. Issues caused by OTRS like bugged package updates continue once in a while, but it looks like the move to MediaTemple (mt) has solved about every other problem – if not taking into account the still somewhat complicated installation/migration/upgrade procedure which won’t follow the official OTRS manuals in every step.

The major difference in both systems (dedicated server vs. MediaTemple) is that “root folder” refers to the main folder on the dedicated server’s drive versus referring to the main folder within a virtual account at (mt). On a dedicated server, OTRS had a number of confusions as to where this “root” would apply: while one configuration would start a path in the domain account’s hosting root, another configuration would go all the way to the drive’s root; despite having the domain account “jailed” (supposed to be unable to access outside-of-own-account destinations).

OTRS does not provide a simple upgrade procedure from within its admin control panel. The upgrade procedure is almost identical to setting up a new installation – minus the database part. I therefore can “merge” both procedures into a single document. Migrating is a rather simple procedure as it only requires the usual modifications like database connection settings and a couple of folder permissions (.htaccess settings…).

A note about the official OTRS documentation: I’ve written about this before, I’ve sent a document to OTRS upon their request, and I keep saying it as no change whatsoever until now: it’s not a good one. It gives you the general idea and for some systems it might work but it lacks crucial details and explanations which could save a lot of time figuring out on my own why something might not even be necessary or totally different.The instructions below refer to a (mt) Grid-Service (gs) account and assume you know your way around the control panel, setting up (sub-)domains and email accounts, have shell (ssh) access and now how to use text editor nano. If you don’t feel comfortable with these or have no idea at all what this is all about, you might want to consider someone’s help.
(As usual, no warranties, liabilities etc by the author; you know the drill.)

New Installation

1. Create the new domain in the control panel, or
   Login to shell and create a sub-domain folder in domains/
   mkdir -p domains/name_of_(sub-)domain/html
2. Having logged into the shell, prepare the installation destination, download the latest release and put all files in place with the right permissions:
   cd domains/name_of_(sub-)domain/html
   mkdir ../otrs-share
   mkdir opt
   cd opt
   wget (latest_release*)
   * copy link of latest “Source Archive” with extension “tar.gz” at download page
   tar -zxvf *.gz
   rm *.gz
   mv (otrs_folder_name) otrs
   chmod -R 755 otrs
3. Setting up the database:
   In your (mt) control panel, create a new MySQL database (and user if you like).
   You might want to change the database from “latin1″ to “utf-8″ encoding.
   Import file “otrs-schema.mysql.sql” from opt/otrs/scripts/database/ folder.
   Import file “otrs-initial_insert.mysql.sql” from same folder.
   Import file “otrs-schema-post.mysql.sql” from same folder.
4. Setting up the configuration file:
   cp otrs/Kernel/Config.pm.dist otrs/Kernel/Config.pm
   nano -w otrs/Kernel/Config.pm
   In the editor, update these lines:
   $Self->{DatabaseHost} = ‘internal-db.s#####.gridserver.com’;
   $Self->{Database} = ‘db#####_name’;
   $Self->{DatabaseUser} = ‘db#####_name’;
   $Self->{DatabasePw} = ‘yourpassword’;
   a few lines down the config file:
   $Self->{Home} = ‘/home/#####/domains/(sub-)domain/html/opt/otrs’;
   Save and quit.
   You might want to take a look at otrs/Kernel/Config/GenericAgent.pm.examples for this:
   cp otrs/Kernel/Config/GenericAgent.pm.dist otrs/Kernel/Config/GenericAgent.pm
   Save and quit.
5. OTRS requires a couple of rewrites which are not permitted by (mt) the way they’re given by the OTRS manual. An easy solution to this is to create symbolic links (symlinks) which won’t be affected by future upgrades either.
   cd .. (as we are currently still in the html/opt folder)
   ln -s opt/otrs/var/httpd/htdocs otrs-web
   ln -s opt/otrs/bin/cgi-bin otrs
6. (mt) executes Perl scripts in the cgi-bin folder but that is not where we run OTRS. We have to create a .htaccess file in 2 locations to allow the execution of .pl files in there as well as to take care of some permission settings.
   nano -w otrs/.htaccess
   Insert the 4 lines below:
   AddHandler cgi-script .pl
   Options +ExecCGI -Includes
   Order allow,deny
   Allow from all
   Save and quit.
   nano -w otrs-web/.htaccess
   Insert the 2 lines below:
   Order allow,deny
   Allow from all
   Save and quit.
7. Check if all Perl modules required by OTRS are working.
   opt/otrs/bin/otrs.checkModules
   It could be that LDAP and PDF is missing but those are not required unless you want to use those functions.
   perl -cw otrs/bin/cgi-bin/index.pl
   perl -cw opt/otrs/bin/PostMasterMailbox.pl
   Both should output “syntax OK”.
8. You should now be able to do your first login:

   http://your_(sub-)domain/otrs/index.pl

   Default admin username: root@localhost
   Default admin password: root

9. After login, switch to “Admin” section (control panel).
   Change username/password in “Users & Groups & Roles” > “Users”:
   Search for “root@localhost”, click name and do modifications.
10. Install additional packages (FAQ, FileManager…) in Misc > Package Manager.
11. Customize (text, emails and other settings) system parameters in Misc > SysConfig:
    - FrameWork > Core, Frontend:Agent, Frontend:Customer…
    - FAQ (if package installed) > Core…
    - FileManager (if package installed) > Core:
    change FileManager::Root: path to /home/#####/domains/(sub-)domain/otrs-share/
12. (mt) runs its servers on the PST time zone which could cause confusion for your installation. OTRS takes the time from the database server and assumes it is the UTC. While the UTC is the “central time” of which you add or subtract up to 12 hours based on what location you are, this won’t work in this case. OTRS time adjustments allow only adjustments in the range of +12 to -12 (thus 24 hours total) but because OTRS believes it runs on UTC which in fact is PST, we have to manually overwrite the time zone setting in the configuration file. Example Hong Kong as a location to run OTRS: Hong Kong time zone is UTC+8 whereas PST is UTC-8. That would be an adjustment of +16 hours which is beyond the default format.
    OTRS stores all custom settings (all the changes you made above in the admin control panel) in this file:
    opt/otrs/Kernel/Config/Files/ZZZAuto.pm
    Do not confuse this file with ZZZAAuto.pm (double-A), which is the template for the single-A.
    Updating the timezone setting if it is beyond +12:
    nano -w opt/otrs/Kernel/Config/Files/ZZZAuto.pm
    If you did not change the time setting in the admin control panel, add the line below. If you already changed the time setting, search for the line and update it. This is an example of the Hong Kong adjustment of +16 hours:
    $Self->{‘TimeZone’} = ‘+16′;
    Please note that after making this adjustment you might be kicked out of OTRS if you are still logged in as the session expired (increase of that many hours goes beyond the session time limit).
13. Setup of email accounts: Misc > Postmaster Mail Account
14. Take a look at the official OTRS Admin Manual, sections “first steps in OTRS” and “the admin area of OTRS”. Things to setup are agents, queues, groups, users… All to be found under “Users & Groups & Roles”.
15. When you’re done configuring your system and perhaps testing if it works, it’s time for some scheduled tasks (cronjobs).
    Still being in the html folder in shell, test if the tasks work fine before scheduling them.
    opt/otrs/bin/DeleteSessionIDs.pl –expired
    opt/otrs/bin/PendingJobs.pl
    opt/otrs/bin/PostMasterMailbox.pl
    opt/otrs/bin/RebuildTicketIndex.pl
    opt/otrs/bin/UnlockTickets.pl –timeout
    There are a number of other tasks but these are the most important. Refer to the admin manual for further information about these and other tasks.
    If all goes well, create a script file which includes the tasks above and which will be scheduled for automatic execution.
    nano -w ../../../data/script_name.sh
    Enter the lines below
    #!/bin/sh
    /home/#####/domains/(sub-)domain/html/opt/otrs/bin/DeleteSessionIDs.pl — expired >> /dev/null
    … Repeat the same with all tasks you want to execute, add ” >> /dev/null” for no output display.
    chmod 755 ../../../data/script_name.sh
    In (mt) control panel, go to the cronjob page and create an entry, calling the script above.
16. Templates / Customization:
    You can easily customize the look of the public and user pages here:
    cp -r opt/otrs/Kernel/Output/HTML/Standard
    opt/otrs/Kernel/Output/HTML/new_name
    Change files like “CustomerFooter.dtl”, “CustomerHeader.dtl”… in that folder.
    In the OTRS admin control panel, go to Misc > SysConfig, change Framework > Core:
    Change the name of the Template. If you don’t want that hassle, backup “Standard” folder and make your changes in the Standard folder itself.

Upgrade

This applies to upgrading the OTRS framework on a (mt) (gs) account.

Package upgrades (FAQ, FileManager…) are done from within OTRS’ admin control panel.

Framework upgrades (OTRS itself) cannot be done from a simple browser-based interface. Below the steps to upgrade a (mt) hosted OTRS installation.

1. Backup the database!
   You can do this from within the (mt) admin control panel or from shell.
2. Backup the existing otrs folder!
   Login to the shell and enter these commands:
   cd domains/(sub-)domain/html/opt
   mv otrs otr_BACKUP
3. Get the new release:
   wget (latest_release*)
   * copy link of latest “Source Archive” with extension “tar.gz” at download page
   tar -zxvf *.gz
   rm *.gz
   mv (otrs_folder_name) otrs
   chmod -R 755 otrs
4. Setting up the database:
   If you do a major OTRS upgrade such as 2.3 > 2.4:
   check in folder opt/otrs/scripts/ if any file “DBUpdate-to-X.Y.mysql.sql” where “X.Y” stands for the OTRS version you are upgrading to. If so, go to your (mt) control panel, select the OTRS database and import that file to upgrade the database.
5. Setting up the configuration file:
   cp otrs/Kernel/Config.pm.dist otrs/Kernel/Config.pm
   nano -w otrs/Kernel/Config.pm
   In the editor, update these lines:
   $Self->{DatabaseHost} = ‘internal-db.s#####.gridserver.com’;
   $Self->{Database} = ‘db#####_name’;
   $Self->{DatabaseUser} = ‘db#####_name’;
   $Self->{DatabasePw} = ‘yourpassword’;
   a few lines down the config file:
   $Self->{Home} = ‘/home/#####/domains/(sub-)domain/html/opt/otrs’;
   Save and quit.
   You might want to take a look at otrs/Kernel/Config/GenericAgent.pm.examples for this:
   cp otrs/Kernel/Config/GenericAgent.pm.dist otrs/Kernel/Config/GenericAgent.pm
   Save and quit.
6. Step 5 of the installation procedure is not necessary, so we skip to step 6.
   cp otrs_BACKUP/bin/cgi-bin/.htaccess otrs/bin/cgi-bin/
   cp otrs_BACKUP/var/httpd/htdocs/.htaccess otrs/var/httpd/htdocs/
7. Check if all Perl modules required by OTRS are working.
   otrs/bin/otrs.checkModules
   It could be that LDAP and PDF is missing but those are not required unless you want to use those functions.
   perl -cw otrs/bin/cgi-bin/index.pl
   perl -cw otrs/bin/PostMasterMailbox.pl
   Both should output “syntax OK”.
8. If you want to keep FileManager’s Trash, restore this folder with all content:
   cp -r otrs_BACKUP/bin/cgi-bin/*Trash otrs/bin/cgi-bin/
   If you opted for file-based instead of database storage of ticket attachments:
   cp -pr otrs_BACKUP/var/article/* otrs/var/article/
9. Restore the configuration modifications you did in the previous version:
   cp otrs_BACKUP/Kernel/Config/Files/ZZZAuto.pm otrs/Kernel/Config/Files/
10. In your web browser, login to the OTRS admin control panel.
    Go to Misc > Package Manager: reinstall (do NOT remove) incorrectly deployed packages.
    Removing would delete all their database data.
11. Script testing from shell:
    otrs/bin/DeleteSessionIDs.pl –expired
    otrs/bin/PendingJobs.pl
    otrs/bin/PostMasterMailbox.pl
    If already running: otrs/bin/PostMasterMailbox.pl -f 1
    otrs/bin/RebuildTicketIndex.pl
    otrs/bin/UnlockTickets.pl –timeout
12. Check if every package (FAQ, FileManager…) looks good for all users by opening these pages in your web browser and navigate around:
    http://(sub-)domain/public.pl (FAQ only)
    http://(sub-)domain/customer.pl

    http://(sub-)domain/index.pl

Be VERY CAREFUL with package upgrading (not related to framework upgrading)! It happened several times to me that – in particular the FAQ package – some upgrades of packages broke OTRS either partially (no admin login or no package for all accounts) or totally (no login for anyone).

Therefore, if you want to upgrade a package (not related to their reinstallation after a framework upgrade), it is most highly recommended you first backup the database AND the /opt/otrs folder. If anything goes wrong, simply restore the database backup and delete the botched opt/otrs folder with its backup, then wait for the next package upgrade (or try your luck at http://www.otrs.org).

Migrate

How to move OTRS to (mt). This assumes you have a working OTRS installation at another host or at least not on a (gs) account.

Moving OTRS is mostly the same as upgrading.

1. Backup the existing
   - database (mysqldump, export…),
   - opt folder (tar -czvf backup.tar.gz opt),
   - otrs-share folder (might be outside your html folder).
2. You can either follow step 3 from the “Upgrade” procedure above or restore your existing opt folder.
   Make sure you restore your existing otrs-share folder.
3. Import the database (or create a new one and import the tables).
   Maybe you want to create a separate user account for it.
4. Update your Config.pm file as detailed in step 5 of the “Upgrade” procedure.
   If you did not restore your old opt folder, don’t forget GenericAgent.pm.
5. Follow steps 5, 6, 7 of “New Installation”.
6. If you did not restore your old opt folder, do steps 8 and 9 of “Upgrade”.
7. In your web browser, login to the OTRS admin control panel.
8. Do step 11 of “Upgrade”.
9. Check if all Misc > SysConfig settings are in order.
   Update FileManager > FileManager::Root: path.
   Update your email accounts: “PostMaster Mail Accounts” and agents’ preferences.
   If you move from another timezone, check step 12 in “New Installation”.
10. Do steps 12 and 13 of “Upgrade”.
11. The cronjobs from step 15 in “New Installation”.
12. Template customization from step 16 in “New Installation”:
    You might have to restore it from your old setup and/or check if all in order.

Comments are closed.