AppSuite:DocumentConverter Installation Guide

Product Description

Open-Xchange Inc. (“Open-Xchange”) has created a proprietary software program called the Open-Xchange Document Converter (the “Software”), which converts Microsoft (OOXML) und OpenOffice (ODF) office documents to PDF or to HTML5 with embedded SVG files (Scalable Vector Graphics). Additional the OX Document Converter converts PDF format files to SVG files and Microsoft files to OpenOffice files and backwards. So users can view and print documents in the existing infrastructure without any necessary additional plugins.

Introduction

Offering document preview functionality within Open-Xchange App Suite, the user expects to be able to open as much different document formats as possible or - to get a better picture - she doesn't need to take care of the document format she just received. It should just work, without knowing anything about document formats at all.

To offer such transparent behaviour to the user, OX App Suite needs to take care of converting a lot of document formats into the display formats needed by OX Files. OX Files is extended with document preview functionality by the module OX Document Viewer.

The conversion functionality is also available as stand-alone product OX Document Converter. The OX Document Converter WebService allows customers the flexible integration of document conversion in their offering.

The API reference describes the available actions with request parameters and results.

Download and Installation

The OX Document Converter deployment consists of two functional modules, that need to be intalled separately: the //readerengine// component and the //Document Converter Webservice// component.

Description

Readerengine is a document conversion engine based on OpenOffice. It contains some tunings special for our requirements, too. Additional there is implemented a completely new export filter for exporting any doc type to SVG.

System requirements

All available readerengine packages need to be installed on the target machine running Linux 64bit that is used for hosting the OX Document Converter.

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/readerengine/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install readerengine

Debian GNU/Linux 12.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/readerengine/DebianBookworm/ /

and run

$ apt-get update
$ apt-get install readerengine

RedHat Enterprise Linux 7

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/readerengine.repo

[readerengine]
name=Open-Xchange
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/readerengine/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update
$ yum install readerengine

RedHat Enterprise Linux 8

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/readerengine.repo

[readerengine]
name=Open-Xchange
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/readerengine/RHEL8/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ dnf update
$ dnf install readerengine

CentOS 7

Start a console and create a software repository file if not already present:

$ vim /etc/yum.repos.d/readerengine.repo

[readerengine]
name=Open-Xchange
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/readerengine/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update
$ yum install readerengine

Fonts

Since Appsuite 7.4.2 the readerengine comes with the packages open-xchange-documents-fonts which includes an appropriate set of fonts.

Webservice

Installation of Document Converter Web service

Install on OX App Suite

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-documentconverter-webservice

Debian GNU/Linux 12.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter/DebianBookworm/ /

and run

$ apt-get update
$ apt-get install open-xchange-documentconverter-webservice

extending the proxypath

in /etc/apache/conf.d/ox-proxy_http.conf the proxy paths needs to be extended by

ProxyPass /documentconverterws balancer://oxcluster_docs/documentconverterws

Configuration

After deployment of both components readerengine and Web service, the administrator needs to make some adjustments to the configuration of the OX Document Converter installation.

The component readerengine works with the default configuration settings.

OSGi variant: The configuration is located at

/opt/open-xchange/etc/documentconverter.properties 

war variant: All settings necessary for the web service to find the corresponding readerengine installation and definition of working directories and service parameters are configured within the documentconverterws.war package in the WebContent/web.xml file.

A summary of all configuration items, together with each default value, is given below. Although the defaults have been carefully chosen for a real life deployment, the admin should take a closer look at each of them and adjust them accordingly, if necessary.

String ENGINE_INSTALLDIR = "/opt/readerengine"

This item contains the the directory of the libreaderengine installation. The libreaderengine installation directory in general contains the ./program directory, which itself contains the engine executables.
Attention: If not set correctly, the complete web service will be nonfuntional.

String ENGINE_CACHEDIR = "/var/opt/open-xchange/readerengine.cache“

This item contains the directory that will make up the cache for persistent job data. The directory itself does not need to exist at startup, but the parent directory needs to exist and needs to have write permissions for the user running the servlet, in order for the servlet to create this cache directory at runtime.

String ENGINE_SCRATCHDIR = "/var/opt/open-xchange/readerengine.scratch"

This item contains the directory, that will make up the runtime enironment for the readerengine. The directory itself does not need to exist at startup, but the parent directory needs to exist and needs to have write permissions for the user running the servlet , in order for the servlet to create this cache directory at runtime.
Attention: If not set correctly, the complete web service will be nonfunctional.

String ENGINE_LOGFILE = "/var/log/open-xchange/readerengine.log"

This item contains the path to the log file for recording informational output from the servlet. The file itself does not need to exist at startup, but the parent directory needs to exist and needs to have write permissions for the user running the servlet, in order for the servlet to create this file at runtime.

int ENGINE_LOGLEVEL = 1

This item determines the amount and detail of logging data. Possible values are:

 * 0 = disabled
 * 1 = errors and warnings and infos
 * 2 = errors and warnings
 * 3 = errors only

int ENGINE_JOB_PROCESSOR_COUNT = 3

This item determines the number of engines working in parallel for job execution. The value needs to be greater or equal to 1, with best performance results about (n+1), where n specifies the number of available CPU cores of the machine the service is running on.

int ENGINE_JOB_RESTART_COUNT = 16

This item determines the maximum number of executed jobs after which a single engine is automatically restarted in order to avoid memory fragmentation and possible memory leaks within one libreaderengine instance,

long ENGINE_JOB_EXECUTION_TIMEOUT_MILLISECONDS = 60000

This item determines the timeout in milliseconds, after which the execution of a single job is terminated.

long ENGINE_MAX_CACHESIZE_MB = 1024

This item determines the maximum size in megabytes (MB) of all persistently cached converter job entries at runtime. A larger value may drastically reduce the time for conversion jobs, e.g. in case of a repeated creation of document previews.
Set this value to -1 for no upper limit.

long ENGINE_MAX_CACHEENTRIES = -1

This item determines the maximum count of converter jobs cached at runtime. The value only affects the amount of runtime job information to be cached.
Set this value to -1 for no upper limit.