OTOBO Installation Guide Release 10.0 Rother OSS GmbH Sep 24, 2021 Contents 1 Introduction 3 1.1 About This Manual .......................................... 3 2 Hardware and Software Requirements 5 2.1 Hardware Requirements ...................................... 7 2.2 Software requirements ....................................... 7 3 OTOBO Installation 9 3.1 Preparation: Disable SELinux when it is installed and enabled ................. 9 3.2 Step 1: Unpack and Install OTOBO ................................ 10 3.3 Step 2: Install Additional Programs and Perl Modules ...................... 10 3.4 Step 3: Create the OTOBO User .................................. 11 3.5 Step 4: Activate the Default Configuration File .......................... 11 3.6 Step 5: Configure the Apache Web Server ............................ 11 3.6.1 Configure Apache without SSL support .......................... 12 3.6.2 Configure Apache with SSL support ........................... 12 3.7 Step 6: Set File Permissions .................................... 13 3.8 Step 7: Setup the Database .................................... 13 3.9 Step 8: Setup Elasticsearch .................................... 14 3.9.1 Elasticsearch installation example based on Ubuntu 18.04 LTS ............ 14 3.9.2 Elasticsearch Installation on another Linux distribution ................. 15 3.9.3 Elasticsearch Module Installation ............................. 15 3.9.4 Elasticsearch Configuration ................................ 15 3.10 Step 8: Basic System Configuration ................................ 15 3.11 Step 9: First Login .......................................... 15 3.12 Step 10: Start the OTOBO Daemon ................................ 16 3.13 Step 11: Cron jobs for the OTOBO user .............................. 16 3.14 Step 12: Setup Bash Auto-Completion (optional) ......................... 16 3.15 Step 13: Further Information .................................... 16 4 Installing using Docker and Docker Compose 17 4.1 Requirements ............................................ 17 4.2 Installation .............................................. 18 4.2.1 1. Clone the otobo-docker repo .............................. 18 4.2.2 2. Create an initial .env file ................................ 18 4.2.3 3. Configure the password for the database admin user ................ 19 4.2.4 4. Set up a volume with SSL configuration for the nginx webproxy (optional) ..... 19 i 4.2.5 5. Start the Docker containers with Docker Compose .................. 19 4.2.6 6. Install and start OTOBO ................................. 20 4.3 Additional technical information .................................. 20 4.3.1 List of Docker containers .................................. 20 4.3.2 Overview over the Docker volumes ............................ 20 4.3.3 Docker environment variables ............................... 21 4.4 Advanced topics ........................................... 22 4.4.1 Custom configuration of the nginx webproxy ....................... 22 4.4.2 Choosing non-standard ports ............................... 23 4.4.3 Customizing the OTOBO Docker image ......................... 23 4.4.4 Building local images .................................... 24 4.4.5 Automatic Installation .................................... 25 4.4.6 List of useful commands .................................. 25 4.5 Resources .............................................. 26 5 Migration from OTRS / ((OTRS)) Community Edition version 6 to OTOBO version 10 27 5.1 Overview over the Supported Migration Szenarios ........................ 27 5.2 Migration Requirements ....................................... 28 5.3 Step 1: Install the new OTOBO System .............................. 29 5.4 Step 2: Deactivate SecureMode on OTOBO ........................... 29 5.5 Step 3: Stop the OTOBO Daemon ................................. 30 5.6 Optional Step: Install sshpass and rsysnc ............................. 30 5.7 Step 4: Preparing the OTRS / ((OTRS)) Community Edition system .............. 31 5.7.1 Stop All Relevant Services and the OTRS Daemon ................... 31 5.8 Optional Step for Docker: make required data available inside container ............ 31 5.8.1 Copy /opt/otrs into the volume otobo_opt_otobo ..................... 31 5.9 Optional Step: Streamlined migration of the database ...................... 32 5.10 Step 5: Perform the Migration! ................................... 34 5.11 Step 6: After Successful Migration! ................................ 35 5.12 Known Migration Problems ..................................... 35 5.12.1 1. Login after migration not possible ........................... 35 5.12.2 2. Final page of the migration has a strange layout due to missing CSS files ..... 35 5.12.3 3. Migration stops due to MySQL errors ......................... 35 5.12.4 4. Errors in Step 5 when migrating to PostgreSQL ................... 35 5.12.5 5. Problems with the Deployment the Merged System Configuration ......... 36 5.13 Step 7: Manual Migration Tasks and Changes .......................... 36 5.13.1 1. Password policy rules .................................. 36 5.13.2 2. Under Docker: Manually migrate cron jobs ...................... 36 5.14 Special topics ............................................ 37 5.14.1 Migration from Oracle to Oracle .............................. 37 6 Updating 39 6.1 Step 1: Stop All Relevant Services and the OTOBO Daemon .................. 39 6.2 Step 2: Backup Files and Database ................................ 39 6.2.1 Example for a standard installation with Ubuntu and MySQL .............. 39 6.3 Step 3: Install the New Release .................................. 40 6.3.1 Restore Old Configuration Files .............................. 40 6.3.2 Restore Article Data .................................... 40 6.3.3 Restore Already Installed Default Statistics ........................ 40 6.3.4 Set File Permissions .................................... 41 6.4 Step 4: Update Installed Packages ................................ 41 6.5 Step 5: Start your Services ..................................... 41 7 Updating a Docker-based Installation of OTOBO 43 ii 7.1 Updating the Docker Compose files ................................ 43 7.2 Checking the Docker Compose .env file .............................. 44 7.3 Fetch the new Docker images ................................... 44 7.4 Update OTOBO ........................................... 44 8 Backup and Restore 47 8.1 Backup ................................................ 47 8.2 Restore ................................................ 48 8.3 Considerations for running OTOBO under Docker ........................ 48 9 Backup and Restore using Docker 51 9.1 Considerations for running OTOBO under Docker ........................ 51 10 Installing Perl modules 53 11 Performance Tuning 55 11.1 Ticket Index Module ......................................... 55 11.2 Ticket Search Index ......................................... 55 11.3 Document Search .......................................... 57 11.3.1 Heap Size .......................................... 57 11.3.2 Disk Allocation ....................................... 58 11.4 Article Storage ............................................ 58 11.5 Archiving Tickets ........................................... 59 11.6 Caching ................................................ 60 11.6.1 Install a Redis Cache Server ............................... 60 11.6.2 RamDisk Caching ..................................... 60 11.7 Clustering .............................................. 61 12 Documentation History 63 iii iv OTOBO Installation Guide, Release 10.0 This work is copyrighted by OTRS AG (https://otrs.com), Zimmersmühlenweg 11, 61440 Oberursel, Ger- many. Copyright © for modifications and amendments 2019-2020 ROTHER OSS GmbH(https://otobo.de), Ober- walting 31, 94339 Leiblfing, Germany Terms and Conditions OTRS: Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found on the GNU website. Terms and Conditions Rother OSS: Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “COPYING”. Published by: Rother OSS GmbH, (https://otobo.de), Oberwalting 31, 94339 Leiblfing, Germany. Authors: OTRS AG (original version), Rother OSS GmbH (https://otobo.de). Contents 1 OTOBO Installation Guide, Release 10.0 2 Contents CHAPTER 1 Introduction OTOBO is an open source ticket request system with many features to manage customer telephone calls and emails. It is distributed under the GNU General Public License (GPL) and is tested on various Linux platforms. 1.1 About This Manual This manual is intended for use by system administrators. The chapters describe the installation and updat- ing of the OTOBO software. There is no graphical user interface for installation and updating. System administrators have to follow the steps described in the following chapters. All console commands look like username> command-to-execute. Username indicates the user ac- count of the operating system, which need to use to execute the command.