⚠️ NOTICE:
On February 24th OTRS AG announced they would be discontinuing the OTRS ((Community Edition)) until further notice. This means no more security or bug fixes from that day onward. Due to this we have switched to the Znuny release of OTRS ((Community Edition)), as they will continue to provide new releases with their LTS version. Znuny has been providing consulting services for OTRS customers for a long time and runs the OTRS community forum. More information about this here.
You can follow the discussion about the migration process, report any bugs you find or do any suggestion on this issue.
Znuny - The ((OTRS)) Community Edition Fork docker image. This repository contains the Dockerfiles and all other files needed to build and run the container.
Current community edition is at version 6.
We also include a MariaDB Dockerfile for a pre-configured image with the required database settings.
The OTRS image doesn't include a SMTP service, decoupling applications into multiple containers makes it much easier to scale horizontally and reuse containers. If you don't have access to a SMTP server, you can instead link against this SMTP relay postfix container.
These images are based on the official CentOS images and include the latest OTRS version. Older images will be tagged with the OTRS version they run.
Note:
- OTRS 6 image sources are still available in otrs-6_0_x branch.
- OTRS 5 image sources are still available in otrs-5_0_x branch.
- OTRS 4 image sources are still available in otrs-4_0_x branch.
If you want to follow the development of this project check out my blog.
- OTRS 6 Ticketing System
- Table of Contents
We use docker-compose to build the images. Clone this repo and then:
cd docker-otrs
sudo docker-compose build
This command will build all the images and pull the missing ones like the SMTP relay. This SMTP relay container has its own configuration, you need to specify the environment variables for the SMTP account that will be used to send OTRS email notifications. Please take a look at the documentation.
The container behavior is controlled by environment variables (see full list below). By default, when the container is run it will load a default vanilla OTRS installation (OTRS_INSTALL=no) that is ready to be configured as you need. However, you can load a backup or run the installer by defining one of these environment variables:
-
OTRS_INSTALL=restoreWill restore the backup specified byOTRS_BACKUP_DATEenvironment variable. See bellow for more details on backup and restore procedures. -
OTRS_DROP_DATABASE=yesWill drop the otrs database it if already exists (by default the container will fail if the database already exists). -
OTRS_INSTALL=yes(currently unsupported) Will run the installer which you can access at:
If you are running the container remotely, replace localhost with the server's hostname. If starting with the default mode (OTRS__INSTALL=no), you will need to configure it before starting it. Copy the example env file as .env on the same directory as the docker-compose file and configure it as you need (don't forget to configure the SMTP relay section at the end). You can then test the service with docker-compose:
sudo docker-compose -f docker-compose.yml up
This will pull and bring up all needed containers, link them and mount volumes according
to the docker-compose.yml configuration file. This is a sample output of the boot up process:
The default database password is changeme, to change it, edit your copy of the env file file and change the
MYSQL_ROOT_PASSWORD environment variable on the mariadb image definition before
running docker-compose.
To start the containers in production mode the the -d parameter to the previous command:
sudo docker-compose -f docker-compose.yml -p companyotrs up -d
After the containers finish starting up you can access the OTRS system at the following addresses:
NOTE: OTRS_INSTALL=yes was used to run the installer but currently is unsupported and have not been tested in a long time so please do not use it, it will be removed soon.
http://$OTRS_HOSTNAME/otrs/index.pl
http://$OTRS_HOSTNAME/otrs/customer.pl
There are also some other environment variables that can be set to customize the default install:
OTRS_HOSTNAMESets the container's hostname (auto-generated if not defined).OTRS_DB_NAMEName of database to use. Default isotrs.OTRS_DB_HOSTHostname or IP address of the database server. Default ismariadb.OTRS_DB_PORTPort of the database server. Default is3306.OTRS_DB_USERDatabase user. Default isotrs.OTRS_DB_PASSWORDotrs user database password. Default password ischangeme.OTRS_ROOT_PASSWORDroot@localhost user password. Default password ischangeme.MYSQL_ROOT_USERDatabase root user name so it can be setup when using an external database. Default user isroot.MYSQL_ROOT_PASSWORDDatabase root password so it can be setup. Default password ischangeme.OTRS_SECRETS_FILEPath to the docker secret file inside the container.OTRS_LANGUAGESet the default language for both agent and customer interfaces (For example, "es" for spanish).OTRS_TIMEZONEto set the default timezone.OTRS_TICKET_COUNTERSets the starting point for the ticket counter.OTRS_NUMBER_GENERATORSets the ticket number generator, possible values are : DateChecksum, Date, AutoIncrement or Random.OTRS_SET_PERMISSIONSConfigure OTRS permissions, possible values are: yes, no or skip-article-dir (if using OTRS_ARTICLE_STORAGE_TYPE=ArticleStorageFS, useful with big articles directories). Default isyes.OTRS_BACKUP_SCRIPTPath to a custom backup script to be called by cron by default /etc/cron.d/otrs_backup script. The script must be added by custom image. Default value is /otrs_backup.sh.OTRS_CRON_BACKUP_SCRIPTPath to a custom backup script to be called by cron. The script must be added by custom image. Default value is /etc/cron.d/otrs_backup.OTRS_ARTICLE_STORAGE_TYPEChange the article storage type (attachments), possible values are ArticleStorageFS and ArticleStorageDB. This feature will also move the articles from the database to the filesystem or vice-versa.OTRS_ALLOW_NOT_VERIFIED_PACKAGESEnable the installation of unverified addons. Useful when installing addons downladed form 3rd party sources like OPAR at startup.SHOW_OTRS_LOGOTo disable the OTRS ASCII logo at container startup.OTRS_SENDMAIL_MODULEModule OTRS should use to send mails (e.gSMTP,SMTPS,Sendmail).OTRS_SMTP_SERVERServer address of the SMTP server to use.OTRS_SMTP_PORTPort of the SMTP server to use.OTRS_SMTP_USERNAMEUsername to authenticate with.OTRS_SMTP_PASSWORDPassword to authenticate with.
Those environment variables is what you can configure by running the installer for a default install, plus other useful ones.
You can also add your own Config.pm file configured as you need, by creating a custom image and adding your custom configuration file to /Kernel/ (NOT /opt/otrs/Kernel), where the container stores OTRS's default configuration files, which are copied back to /opt/otrs on container start, if they have not been already copied and you are using host volumes. This means that configuration files will not be overwritten on container restart. An example Dockerfile:
FROM juanluisbaptiste/otrs:latest
LABEL maintainer='xxxxxx'
COPY Config.pm /Kernel
The article storage type can be controlled using the OTRS_ARTICLE_STORAGE_TYPE environment variable, useful when the database size is getting out of hands so a filesystem based storage is better suited. Possible values are ArticleStorageFS and ArticleStorageDB (this is the default).
This feature will also move the articles from the database to the filesystem or vice-versa as described in the documentation. If you change the storage type to ArticleStorageFS you have to mount /opt/otrs/var/article directory so exported articles from the database aren't lost at container restart/recreation. The example docker-compose files has this commented out.
As a convenience, a pre-made systemd service file otrs.service is included as part of the repository to automatically start the container as a host service.
To use it you will need to update /opt/docker-otrs/docker-compose-prod.yml to the path to your docker compose file, then copy the service file from the repository to /usr/lib/systemd/system/, and run the command systemctl daemon-reload. You will then be able to use systemd to control your container.
In order to keep your repositories and images free from any sensitive information you can specify a path to you secrets file to deploy the container easier and safer within a docker swarm/kubernetes environment. You can store any key/value-pair from the list above exactly like the .env file.
e.g.
OTRS_DB_PASSWORD=12345
MYSQL_ROOT_PASSWORD=67890
OTRS_ROOT_PASSWORD=54321And add the path to this secret file (within the container) to OTRS_SECRETS_FILE. Docker stores those files in /run/secrets/.
services:
otrs:
environment:
- OTRS_SECRETS_FILE=/run/secrets/my_otrs_secretsTo install any addon at container start, map /opt/otrs/addons directory to a volume and place the /opm files there. The container will install them when starting up.
If you have installed any additional addon, the OTRS container will reinstall them after an upgrade or when a container is removed so they continue working.
- The included docker-compose file uses
host mounted data containersto store the database and configuration contents outside the containers. Please take a look at thedocker-compose.ymlfile to see the directory mappings and adjust them to your needs. - Any setting set using the previous environment variables cannot be edited later through the web interface, if you need to change them then you need to update it in your docker-compose/env file and restart your container. The reason for this is that OTRS sets as read-only any setting set on
$OTRS_ROOT/Kernel/Config.pm. - For production use there's another
docker-composefile that points to the pre-built images.
The default skins and logos for the agent and customer interfaces can be controlled with the following environment variables:
To set the agent interface skin set OTRS_AGENT_SKIN environment variable, for example:
OTRS_AGENT_SKIN: "ivory"
To set the customer interface skin set OTRS_CUSTOMER_SKIN environment variable, for example:
OTRS_CUSTOMER_SKIN: "ivory"
If you are adding your own skins, the easiest way is create your own Dockerfile inherited from this image and then COPY the skin files there. Take a look at the official documentation on instructions on how to create one. You can also set all the environment variables in there too, for example:
FROM juanluisbaptiste/otrs:latest
MAINTAINER Foo Bar <[email protected]>
ENV OTRS_AGENT_SKIN mycompany
ENV OTRS_AGENT_LOGO skins/Agent/mycompany/img/logo.png
ENV OTRS_CUSTOMER_LOGO skins/Customer/default/img/logo_customer.png
COPY skins/ $SKINS_PATH/
RUN mkdir -p $OTRS_ROOT/Kernel/Config/Files/
COPY skins/Agent/MyCompanySkin.xml $OTRS_ROOT/Kernel/Config/Files/
By default, automated backups are done daily at 6:00 AM. Backups are compressed using gzip and are stored in /var/otrs/backups. If you mounted that directory as a host volume then you will have access to the backups files from the docker host server.
You can control the backup behavior with the following variables:
OTRS_BACKUP_TIME: Sets the backup excecution time, in cron format. If set to disable automated backups will be disabled.OTRS_BACKUP_TYPE: Sets the type of backup, it receives the same values as the OTRS backup script:- fullbackup: Saves the database and the whole OTRS home directory (except /var/tmp and cache directories). This is the default.
- nofullbackup: Saves only the database, /Kernel/Config* and /var directories.
- dbonly: Only the database will be saved.
OTRS_BACKUP_COMPRESSION: Sets the backup compression method to use, it receives the same values as the OTRS backup script (gzip|bzip2). The default is gzip.OTRS_BACKUP_ROTATION: Sets the number of days to keep the backup files. The default is 30 days.OTRS_BACKUP_STOP_SERVICES: Controls whether OTRS services should be stopped before doing a backup. The default is yes.
For example, to change the backup time to database only backups, compress them using bzip2 and run twice each day set those variables like this:
OTRS_BACKUP_TYPE=dbonly
OTRS_BACKUP_TIME="0 12,12 * * *"
OTRS_BACKUP_COMPRESSION=bzip2
To restore an OTRS backup file (not necessarily created with this container) the following environment variables must be added:
OTRS_INSTALL=restoreWill restore the backup specified byOTRS_BACKUP_DATEenvironment variable.OTRS_BACKUP_DATEis the backup name to restore. It can have two values:- Uncompressed backup: A directory with its name in the same date_time format that the OTRS backup script uses, for example
OTRS_BACKUP_DATE="2015-05-26_00-32"with the backup files inside. A backup file created with this image or with any OTRS installation will work (the backup script creates the directory with that name). This feature is useful when migrating from another OTRS install to this container. - Compressed backup file: A gzip tarball of the previously described directory with the backup files. These tarballs are created by this container when doing a backup.
- Uncompressed backup: A directory with its name in the same date_time format that the OTRS backup script uses, for example
Backups must be inside the /var/otrs/backups directory (host mounted by default in the docker-compose file).
❗ Remember to remove the OTRS_INSTALL=restore from the docker-compose file environment variables afterwards.
There are two types of upgrades When upgrading OTRS: minor and major version upgrades. This section describes how to upgrade on each case.
For example from 6.0.1 to 6.0.5, just pull the new image and restart your services:
sudo docker-compose -f docker-compose-prod.yml pull
sudo docker-compose -f docker-compose-prod.yml stop
sudo docker-compose -f docker-compose-prod.yml up -d
This upgrade option will do a major version upgrade of OTRS. For example from OTRS 5.0x to 6.0.x. The upgrade process will also upgrade installed packages only from the official repository.
To do a major version upgrade, follow these steps:
- Set the
OTRS_UPGRADE=yesenvironment variable in the docker-compose file - Replace the current image version tag with the new one on the image: configuration option. For example, change:
image: juanluisbaptiste/otrs:latest-5x
with:
image: juanluisbaptiste/otrs:latest
- Pull the release image you are upgrading to:
sudo docker-compose -f docker-compose-prod.yml pull
- Restart the containers:
sudo docker-compose -f docker-compose-prod.yml stop
sudo docker-compose -f docker-compose-prod.yml up -d
The upgrade procedure will pause the boot process for 10 seconds to give the user the chance to cancel the upgrade.
The first thing done by the upgrade process is to do a backup of the current version before starting with the upgrade process. Then it will follow the official upgrade instructions (run db upgrade script and upgrade modules, software was updated when pulling the new image). You can use these variables to control the upgrade process:
OTRS_UPGRADE_BACKUP=yes|noto control if a backup should be done before starting an upgrade (default: yes).
Sometimes there are fixes needed to be done to the database when doing an upgrade. When the database upgrade script is executed it will do some inconsistencies checks and it will spit out the sql commands needed to be run to fix the database and continue with the upgrade process. Map /opt/otrs/db_upgrade to a host directory and put the sql files in it, they will get loaded before the database upgrade script is run.
Since OTRS 6 the location and XML schema of configuration files has changed. OTRS can try to migrate this configuration files and put them in the new location. For this set OTRS_UPGRADE_XML_FILES=yes (default value: no).
The upgrade process will upgrade official modules (FAQ, Survey, etc). If you have additional 3rd party modules you will need to manually update them in the Package Manager.
As mentioned before, the XML files of custom skins can be migrated to the new location and updated schema setting OTRS_UPGRADE_XML_FILES=yes.
- If after upgrade you can't login with any account, delete the cookies for your OTRS website and try again.
- If you get an 500 error after login it could mean that a module could not be automatically upgraded. Check the container output and look for the messages about modules upgrade.
❗ Remember to remove the OTRS_UPGRADE=yes from the docker-compose file environment variables afterwards.
If you are having issues starting up the containers you can set OTRS_DEBUG=yes to print a more verbose container startup output. It will also install some tools to aid with troubleshooting like telnet and dig.
Do you need help setting your OTRS ticketing system or configuring it to match your organization's needs ? I also offer consulting services, drop me a line at: juan at juanbaptiste dot tech