OTOBO Installation Tutorial

This work is copyrighted by OTRS AG (https://otrs.com), Zimmersmühlenweg 11, 61440 Oberursel, Germany.

Copyright © for modifications and amendments 2019-2022 ROTHER OSS GmbH (https://otobo.io), Oberwalting 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.io), Oberwalting 31, 94339 Leiblfing, Germany.

Authors: OTRS AG (original version), Rother OSS GmbH (https://otobo.io).

Contents

• Introduction
  • About This Manual
• Hardware and Software Requirements
  • Hardware Requirements
  • Software requirements
• OTOBO Installation
  • Preparation: Disable SELinux when it is installed and enabled
  • Step 1: Unpack and Install OTOBO
  • Step 2: Install Additional Programs and Perl Modules
  • Step 3: Create the OTOBO User
  • Step 4: Activate the Default Configuration File
  • Step 5: Configure the Apache Web Server
    • Configure Apache without SSL support
    • Configure Apache with SSL support
  • Step 6: Set File Permissions
  • Step 7: Setup the Database
  • Step 8: Setup Elasticsearch
    • Elasticsearch installation example based on Ubuntu 18.04 LTS
    • Elasticsearch Installation on another Linux distribution
    • Elasticsearch Module Installation
    • Elasticsearch Configuration
  • Step 9: Basic System Configuration
  • Step 10: First Login
  • Step 11: Start the OTOBO Daemon
  • Step 12: Cron jobs for the OTOBO user
  • Step 13: Setup Bash Auto-Completion (optional)
  • Step 14: Further Information
• Installing using Docker and Docker Compose
  • Requirements
  • Installation
    • 1. Clone the otobo-docker repo
    • 2. Create an initial .env file
    • 3. Configure the password for the database admin user
    • 4. Set up a volume with SSL configuration for the nginx webproxy (optional)
    • 5. Start the Docker containers with Docker Compose
    • 6. Install and start OTOBO
  • Additional technical information
    • List of Docker containers
    • Overview over the Docker volumes
    • Docker environment variables
  • Advanced topics
    • Custom configuration of the nginx webproxy
    • Single Sign On Using the Kerberos Support in Nginx
    • Choosing non-standard ports
    • Skip startup of specific services
    • Prepare offline installation
    • Customizing OTOBO Docker Compose
    • Customizing the OTOBO Docker image
    • Building local images
    • Automatic Installation
    • List of useful commands
  • Resources
• Migration from OTRS 6 or OTRS 7 / ((OTRS)) Community Edition to OTOBO version 10.1
  • Overview over the Supported Migration Szenarios
  • Migration Requirements
  • Step 1: Install the new OTOBO System
  • Step 2: Deactivate SecureMode on OTOBO
  • Step 3: Stop the OTOBO Daemon
  • Optional Step: Mount /opt/otrs for Convenient Access
  • Optional Step: Install sshpass and rsync when /opt/otrs Should be Copied via ssh
  • Step 4: Preparing the OTRS / ((OTRS)) Community Edition system
    • Stop All Relevant Services and the OTRS Daemon
    • Clear the Caches and the Operational Data
  • Optional Step for Docker: make required data available inside container
    • Copy /opt/otrs into the volume otobo_opt_otobo
  • Step 5: Perform the Migration!
  • Step 6: After Successful Migration!
  • Known Migration Problems
    • 1. Login after migration not possible
    • 2. Final page of the migration has a strange layout due to missing CSS files
    • 3. Migration stops due to MySQL errors
    • 4. Errors in Step 5 when migrating to PostgreSQL
    • 5. Problems with the Deployment the Merged System Configuration
  • Step 7: Manual Migration Tasks and Changes
    • 1. Password policy rules
    • 2. Under Docker: Manually migrate cron jobs
  • Special topics
    • Migration from Oracle to Oracle
    • Optional Step: Streamlined migration of the database (only for experts and spezial scenarios)
• Updating
  • Step 1: Stop All Relevant Services and the OTOBO Daemon
  • Step 2: Backup Files and Database
    • Example for a standard installation with Ubuntu and MySQL
    • Step 2.1: Delete CPAN-directory if you are upgrading from 10.1
  • Step 3: Install the New Release
    • Restore Old Configuration Files
    • Restore Article Data
    • Restore Already Installed Default Statistics
    • Set File Permissions
    • Check Apache configuration files
  • Step 4: Check for new needed Perl modules
  • Step 5: Update Installed Packages and reconfigure config
  • Step 6: Only for minor or major release upgrades (for example to upgrade from 10.1 to 11.0)
  • Step 7: Start your Services
• Updating a Docker-based Installation of OTOBO
  • Updating the Docker Compose files
  • Checking the Docker Compose .env file
  • Fetch the new Docker images
  • Update OTOBO
• Backup and Restore
  • Backup
  • Restore
  • Considerations for running OTOBO under Docker
• Backup and Restore using Docker
  • Considerations for running OTOBO under Docker
• Kerberos Single Sign On in OTOBO Docker installation
  • Generate Active Directory User
  • Generate Active Directory Keytab file
  • Create a new volume for your custom nginx configuration
  • Create new OTOBO .env file
  • Start OTOBO
  • Tell OTOBO to use the Kerberos-Authentication
  • Configure Browser to understand Kerberos SSO
  • Debugging and Problems
    • Kerberos debugging
• Adapt customer interface with corporate identity
  • Change colors in Customer Area
  • Change Logos and Pictures
    • Change Customer Login Pictures and Text
    • Change Customer Dashboard tiles and options
• Installing Perl Modules from CPAN
  • Docker-based installations
• Performance Tuning
  • Ticket Index Module
  • Ticket Search Index
  • Document Search
    • Heap Size
    • Disk Allocation
  • Article Storage
  • Archiving Tickets
  • Caching
    • Install a Redis Cache Server
    • RamDisk Caching
  • Clustering
• Documentation History