Open-Xchange - User contributions [en]

AppSuite:ImageConverter Install

2021-10-08T08:53:29Z

Kai.ahrens: Adding sizing chapter

= Download & Installation Imageconverter =

=== General Information ===

OX App Suite displays images (photos and graphics) in many different ways as

* Thumbnails
* Icons
* Images embedded in documents
* in Emails
* in an own pop-up window.

The image processing is done by the OX middleware and not by a dedicated service, so that the middleware might consume a lot of cpu time just to convert images to different target formats. Furthermore the OX middleware does not cache images for a longer time. Only thumbnails get cached, either by the database or file system based. These images get converted into the required formats (e.g. jpeg, png) when requested by an user action in the user Interface.

With OX App Suite 7.10 there is an alternative to process images by the OX middleware. The image conversion and delivery can be delegated to an extra service, the OX Image Converter server. It's deployment model is exactly corresponding to the documentconverter server via a client/server service.

The separation of the Image Converter service has the following advantages:

Configuration and usage of one or more separate storages
Performance improvements via persistent cache
Pre-rendering of pre-defined formats and sizes (defaults are auto:200x150, auto:480x320, auto:640x480, auto:800x600, auto:1280x720, auto:1920x1080") if resolution of the source image allows this.
Best matching size will be delivered without new conversion, if an image is requested by the Middleware
Browser is able to cache those images
No limits for image sizes
The default target format is specified by configured, predefined formats. By using the 'auto' (beside 'jpg' or 'png') target format, opaque source images are converted to JPEG target images and transparent images are converted to PNG target images.
Reduce load of OX Middleware

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

== Mandatory Modules ==

Additional functional modules need to be installed separately on the user servicing OX App Suite middleware nodes:

* The Image Converter Client: See [[AppSuite:ImageConverterClientInstall|Image converter client installation instructions]]

== Installation ==

The Image Converter deployment consists of the package <tt>open-xchange-imageconverter-server</tt>.

=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 7.10.3) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|imageconverter}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}
$ yum install open-xchange-imageconverter-server

=== Redhat Enterprise Linux 7, CentOS 7 or Amazon Linux 2 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|imageconverter}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}

$ yum install open-xchange-imageconverter-server

=== Debian GNU/Linux 9.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|imageconverter}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}

$ apt-get update
$ apt-get install open-xchange-imageconverter-server

=== Debian GNU/Linux 10.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|imageconverter}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}

$ apt-get update
$ apt-get install open-xchange-imageconverter-server

=== SUSE Linux Enterprise Server 12 (valid until 7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|imageconverter}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}

$ zypper ref
$ zypper install open-xchange-imageconverter-server

== Monitoring ==

Image Converter offers runtime information via JMX about the Image Converter. This [[AppSuite:ImageConverterMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

The following property files need to be adjusted on the Image Converter node to ensure correct runtime behavior of the ImageConverter implementation

* fileitem.properties
* imageconverter.properties

=== Filestores ===

Since the Image Converter service uses the FileItemService, which itself needs a dedicated filestore and a dedicated database schema, the following steps need to be performed by the admin prior to starting the Image Converter WebService.

'''Please note:''' Initially file-system based filestores (NFS) were supported only. Object storage support (S3, [[AppSuite:Scality_File_Store|Scality sproxyd]]) has been added with 7.10.3.

Create a directory for the FileItemService filestore(s) with OS commands, that is writable for the user, running the OX backends:

$ mkdir -p /var/opt/fileitemstore
$ chown open-xchange:open-xchange /var/opt/fileitemstore

Register the FileItemService filestore(s) via the OX admin command registerfilestore after installation. Since the the RMI port for administrative calls to the Image Converter server is set to 1095 by default, this port has to be set within the environment, prior to making the registerfilestore call itself. If making the administration call on the system by using an already running middleware server, the port setting can be omitted.

Since the Image Converter filestore is a dedicated filestore for this service only, the number of allowed contexts for the filestore must be set to 0 (by using switch '-x 0') in order to prevent the middleware from using this filestore as an additional filestorage.

$ env RMI_HOSTNAME=rmi://localhost:1095 /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P ${AS_ADMINMASTER_PASS} -x 0 -t file:///var/opt/fileitemstore

Enter the id(s) of the FileItemService filestore(s) (put into the configdb database by using the registerfilestore command) into the fileitem.properties configuration file

Create a new, empty database schema to be used by the FileItemService:

$ /opt/open-xchange/imageconverter/sbin/initfileitemdb -i --fileitemdb-pass="${AS_DB_PASS}" --fileitemdb-user=openexchange --fileitemdb-host=localhost --fileitemdb-port=3306 --fileitemdb-dbname=fileitemdb

Enter the database connection data, used to initialize the FileItemService database in the previous 'initfileitemdb' call into the appropriate fields of the fileitem.properties configuration file. Please take care to enter the 'read' properties as well as the 'write' properties within the configuration file.

The following properties of the fileitem.properties need to be adjusted, at least (example values are provided):

$ com.openexchange.fileItem.fileStoreIds=3
$
$ com.openexchange.fileItem.readUrl=jdbc:mysql://localhost/fileitemdb
$ com.openexchange.fileItem.readProperty.1=user=openexchange
$ com.openexchange.fileItem.readProperty.2=password=${AS_DB_PASS}
$
$ com.openexchange.fileItem.writeUrl=jdbc:mysql://localhost/fileitemdb
$ com.openexchange.fileItem.writeProperty.1=user=openexchange
$ com.openexchange.fileItem.writeProperty.2=password=${AS_DB_PASS}

The Image Converter itself currently relies on the external ImageMagick framework, so that this package has to be installed on the node, the Image Converter is running on

=== ImageMagick ===

On Amazon Linux 2, ImageMagick is located under ''/bin''. Therefore the property ''com.openexchange.imageconverter.imagemagick.searchPath'' must be adjusted accordingly.

= Sizing and technical background =

== Summary ==

* One Image Converter node should have at least 4 cores
* One Image Converter node needs to have at least 4GB RAM
* Local storage space with a minimum of 10 GigaBytes needs to be available on an Image Converter node
* At least 2 Image Converter nodes should be available on a production system in parallel, each working on the same, shared database and shared file storage

== Background ==

Whenever the OX App Suite UI is going to display image representations of user provided content like thumbnails for arbitrary source documents, images in Viewer application or images contained in documents that are currently edited in one of the Ox Documents applications, the frontend sends an appropriate request to the middleware.
After pre processing the source content to create an image or after extracting a thumbnail image from a document to be returned, the middleware needs to process the resulting image according to different view constraints before the resulting image is returned to the OX App Suite UI to be displayed. Such image processing might include scaling, rotation and cropping operations, which can be expensive.
In order to remove that image processing load from the OX App Suite middleware, an Image Converter (IC) can be deployed on a dedicated node in order to perform those operations. In addition, the IC is able to cache image results after processing to speed up access to images that have already been processed before.
To get a best fit for most use case, the IC creates a set of differently processed target files (e.g.
different image resolutions) for each source image and stores those results within its configured cache.
The following hardware recommendations for an IC deployement are based on collected inhouse metrics and should fit for most customer deployments. Nevertheless, there might be scenarios where these recommendations do not fit well, so that the customer should track provided IC metrics to ensure proper operation of the IC deployment.
Detailed up to date documentation for all mentioned IC related configuration items can be found within the provided /opt/open-xchange/imageconverter/etc/imageconverter.properties file.

== Storage ==

=== Temporary files ===

For proper operation, the IC needs to rely on a working directory. This working directory is used to temporarily store source image attachments from processing requests, made by the middleware to the IC, as well as to store intermediate target images after processing before those target result images are cached in a persistent way.
Due to its nature as a spool and working directory, access times to the related working directory should be as fast as possible. As such this working directory should be located on a local, volume with fast access times that is not shared via NFS or similar.
Given a maximum default upload size for files in OX App Suite of 10 MegaBytes and a maximum default IC job queue length of 1024 entries, the total available size of this working directory should be able to store 10 GigaBytes of image files in its own format (e.g. JPEG, PNG) in the worst use case. All files, created by the IC within this working directory are automatically removed at runtime or shutdown of the IC. In case there was an unexpected, not intended shutdown of the IC or the whole system, a cleanup of all left over temporary files within the configured working directory will happen at IC startup as well in any case.
The working directory, that needs to have write access for the IC user can be configured via the following config item:

* com.openexchange.imageconverter.spoolPath

=== Persistent files ===

If an IC database and at least one FileStore is configured to be used by the IC, all processed result images are cached as persistent files, meaning that they will survive IC restarts and are preferably used before processing of the same source image happens again.
The number of image keys (number of source images, whose processed list of target images is to be stored), the totally occupied space of all target images and the time to live for the image keys and
corresponding files (based on last access time) within the cache are configured via the the following IC config properties:

* com.openexchange.imageconverter.cache.maxKeyCount
* com.openexchange.imageconverter.cache.maxSizeGB
* com.openexchange.imageconverter.cache.keyTimeoutMinutes

If one of the configured cache constraints is reached, the cache automatically removes the oldest image keys and corresponding target image files for each image key from the cache until all cache metrics are below the configured cache constraints again.
The value for each of the above cache constraints can be specified in detail or set to unlimited by the administrator. Please see the appropriate IC configuration documentation mentioned above for further details.

== Memory usage ==

The IC deployment consists of the Java VM based IC itself and the corresponding image processing backends, which are ImageMagick processes at the moment, separately started by the IC for each single image transformation process.
When the OX middleware performs an image based operation due to a request from the OX App Suite UI and is going to return an image response, it first checks, if the resulting image is already contained within the IC cache. If no appropriate cache entry can be retrieved, the OX middleware sends an image transformation request to the IC. The request is then put into an IC queue to be transformed by the image processing backends afterwards. The maximum length of this request queue can be specified by the following config property:

* com.openexchange.imageconverter.queueLength

If one image processing backend gets available, the IC takes the next job request from the FIFO queue and starts processing the list of target images via one started processing backend for each required target image. The number of processing backends that can be started in parallel is specified by the following config property:

* com.openexchange.imageconverter.threadCount

=== Java VM memory usage ===

The maximum available runtime memory that can be used by the IC Java VM process is set to 1024 MegaBytes by default. This value has been chosen as a sensible and appropriate value based on other configuration default properties. Request image attachments are extracted and stored as temporary files to be processed later, so that this maximum available Java VM memory limit should be sufficient with the default queue length configured.
If larger queue lengths are configured by the administrator, the maximum available Java VM memory limit should be increased as well.
Exact numbers for the increment of available Java VM memory cannot be given due to quite different source sizes of images in general.
A Java VM memory increment of 100 MegaBytes for an additional queue length of 100 entries should be sufficient.

=== Processing backend memory usage ===

Considering quite large high resolution images with alpha channel and an extent of e.g. 8000x6000 pixels (and sometimes even more), an image processing backend will import this image and use at least an input and output buffer for the unpacked image data of size 8000x6000x4 Bytes at maximum each when not scaling up the image. This sums up to about 366 MegaBytes for each image processing backend used in this example case. With a default of 8 processing backends, a pessimistic calculation would require about 3000 MegaBytes of runtime memory available for all image processing backends currently processing such kind of images.

== Request throughput ==

When talking about request throughput, we need to take two different scenarios into account.
The first one is the IC operation with no available cache or an available cache that has not been filled up much yet.
In the (virtual) 'no cache' case we need to take the processing time for time consuming requests into account. Such requests might be #CacheAndGetImage requests as well as #GetImage requests in some cases.
According to inhouse metrics we collected on different IC test deployments so far, we achieved a median request time for those two request types of about 0.15s/request. Since those requests use one processing backend, we can calculate a median request throughput per second without using a cache the following way.

* 1.0 / 0.15s = 6.7/s (median requests per second for 8 processing backends using no cache)

When the cache is enabled and already filled up by preceding requests, a cache hit ratio between 80% and 90% can be reached in general. This means that 8-9 out of 10 requests can be responded in a fast way with a result taken from the cache without using the expensive processing backend path. For the request throughput, this means that we can multiply the pure processing request throughput with (1.0 / ( 1.0 - cacheHitRatio)) to get the resulting request throughput when having access to cached results as well.
Assuming a conservative value of 75% cache hit ratio for a given system, meaning that 3 out of 4 requests can be responded in a fast way, the request throughput will be increased to:

* 6.7/s * (1.0 / (1.0 - 0.75)) = 26.8/s (median requests per second for 8 processing backends using a cache with a cache hit ratio of 75%)

== Multiple nodes and number of users per node ==

The minimum number of IC nodes deployed on a customer system should be 2 to have at least one remaining IC node in case of the outage of the other IC node. This also reduces load for one IC node at all. More than 2 IC nodes can be deployed the same way in parallel in case the number of requests indicates this.

To avoid multiple conversions for the same source image on different IC nodes, all nodes should work on the same IC cache and filestore. This requires the admin to configure the same cache database on all IC nodes and the usage of a shared file storage across all IC nodes. In addition, the /opt/open-xchange/imageconverter/imageconverter.properties config file should have the same content on all IC nodes.

Due to the fact that each user has a quite different usage scenario when working in OX App Suite and currently having no detailed image usage information available across a larger user base, the number of provisioned users per IC node, working in parallel with different kind of images or with no images at all on the customer deployment, the current recommendation for the number of IC nodes is to start with 2 IC nodes and to watch for the 'peak job count in queue' metric. In case this value is constantly at or near the maximum configured queue entry count (1024 by default), additional IC nodes should be added to the deployment in parallel to be able to process all user requests within an appropriate time frame.

AppSuite:Documents Installation Guide

2020-05-11T15:00:39Z

Kai.ahrens: /* OX Documents in Browser Tabs */

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

For releases until 7.10.3 the spell checking functionality was part of the Documents middleware bundles. Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:''' For releases valid from 7.10.4 on, the SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spell checking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file.

Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Valid until 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

==== Valid from 7.10.4 ====

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:
<pre>
open-xchange-spellcheck
</pre>

The target directory is /opt/open-xchange/spellcheck

The SpellCheck service internally uses ''hunspell'' for spell checking functionality.

When starting a SpellCheck service via ''systemd'', two ''oxspell'' processess are spawned as a ''systemd'' control group. The initial process acts as a loader and initializer for dictionaries as well as a watchdog for the spawned child process(es) that itself make up the spell checking HTTP service functionality.
<pre>
29582 29582 29582 ? 00:00:00 oxspell
29583 29582 29582 ? 00:00:02 |-oxspell
</pre>

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]

After installation of the ''open-xchange-spellcheck'' package for your platform the US English dictionaries are available by default. Please check the file location, the dictionaries were installed into and verify that the ''hunspell'' dictionary directory is present and not renamed to ''myspell'' etc. If the dictionary is renamed, you will have to use that in the config below.
<pre>
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell
</pre>

Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...
''myspell'' dictionaries might be used as well as long as they have the same format as ''hunspell'' dictionaries. Valid dictionaries consist of pairs of files with the suffixes ''*.aff'' and ''*.dic'', having the same unsuffixed file name and located side by side within the same directory.

The following entry needs to be reviewed and the value may need to be adjusted during the setup in case the SpellCheck service is running on a different node than the accessing Documents middleware client node. 
The configuration entry specifies the range of addresses, the SpellCheck service is accepting client connections from. Use 0.0.0.0 to allow connections from either client address. The default of 127.0.0.1 restricts connections to be established from localhost clients only.
<pre>
com.openexchange.spellcheck.listenAddress = 0.0.0.0
</pre>

===== SpellCheck Service Transport Security =====

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport should be enabled and the appropriate host related certificate files should be specified via the following configuration properties.
<pre>
com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile
</pre>

===== SpellCheck Monitoring =====

The SpellCheck service internally starts a ''Prometheus'' service in parallel to allow the administrator to get access to runtime metrics of the spell checking service like number of request counts and the usage of different locale dictionaries. The listen address and port of this ''Prometheus'' service can be specified via these configuration items.
<pre>
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002
</pre>
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.
<pre>
curl localhost:8002/metrics | sort
</pre>

== Templates ==

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

== OX Documents in Browser Tabs ==

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T14:57:52Z

Kai.ahrens: /* Templates */

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

For releases until 7.10.3 the spell checking functionality was part of the Documents middleware bundles. Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:''' For releases valid from 7.10.4 on, the SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spell checking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file.

Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Valid until 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

==== Valid from 7.10.4 ====

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:
<pre>
open-xchange-spellcheck
</pre>

The target directory is /opt/open-xchange/spellcheck

The SpellCheck service internally uses ''hunspell'' for spell checking functionality.

When starting a SpellCheck service via ''systemd'', two ''oxspell'' processess are spawned as a ''systemd'' control group. The initial process acts as a loader and initializer for dictionaries as well as a watchdog for the spawned child process(es) that itself make up the spell checking HTTP service functionality.
<pre>
29582 29582 29582 ? 00:00:00 oxspell
29583 29582 29582 ? 00:00:02 |-oxspell
</pre>

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]

After installation of the ''open-xchange-spellcheck'' package for your platform the US English dictionaries are available by default. Please check the file location, the dictionaries were installed into and verify that the ''hunspell'' dictionary directory is present and not renamed to ''myspell'' etc. If the dictionary is renamed, you will have to use that in the config below.
<pre>
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell
</pre>

Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...
''myspell'' dictionaries might be used as well as long as they have the same format as ''hunspell'' dictionaries. Valid dictionaries consist of pairs of files with the suffixes ''*.aff'' and ''*.dic'', having the same unsuffixed file name and located side by side within the same directory.

The following entry needs to be reviewed and the value may need to be adjusted during the setup in case the SpellCheck service is running on a different node than the accessing Documents middleware client node. 
The configuration entry specifies the range of addresses, the SpellCheck service is accepting client connections from. Use 0.0.0.0 to allow connections from either client address. The default of 127.0.0.1 restricts connections to be established from localhost clients only.
<pre>
com.openexchange.spellcheck.listenAddress = 0.0.0.0
</pre>

===== SpellCheck Service Transport Security =====

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport should be enabled and the appropriate host related certificate files should be specified via the following configuration properties.
<pre>
com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile
</pre>

===== SpellCheck Monitoring =====

The SpellCheck service internally starts a ''Prometheus'' service in parallel to allow the administrator to get access to runtime metrics of the spell checking service like number of request counts and the usage of different locale dictionaries. The listen address and port of this ''Prometheus'' service can be specified via these configuration items.
<pre>
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002
</pre>
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.
<pre>
curl localhost:8002/metrics | sort
</pre>

== Templates ==

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T14:53:24Z

Kai.ahrens: /* SpellCheck Service */

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

For releases until 7.10.3 the spell checking functionality was part of the Documents middleware bundles. Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:''' For releases valid from 7.10.4 on, the SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spell checking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file.

Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Valid until 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

==== Valid from 7.10.4 ====

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:
<pre>
open-xchange-spellcheck
</pre>

The target directory is /opt/open-xchange/spellcheck

The SpellCheck service internally uses ''hunspell'' for spell checking functionality.

When starting a SpellCheck service via ''systemd'', two ''oxspell'' processess are spawned as a ''systemd'' control group. The initial process acts as a loader and initializer for dictionaries as well as a watchdog for the spawned child process(es) that itself make up the spell checking HTTP service functionality.
<pre>
29582 29582 29582 ? 00:00:00 oxspell
29583 29582 29582 ? 00:00:02 |-oxspell
</pre>

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]

After installation of the ''open-xchange-spellcheck'' package for your platform the US English dictionaries are available by default. Please check the file location, the dictionaries were installed into and verify that the ''hunspell'' dictionary directory is present and not renamed to ''myspell'' etc. If the dictionary is renamed, you will have to use that in the config below.
<pre>
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell
</pre>

Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...
''myspell'' dictionaries might be used as well as long as they have the same format as ''hunspell'' dictionaries. Valid dictionaries consist of pairs of files with the suffixes ''*.aff'' and ''*.dic'', having the same unsuffixed file name and located side by side within the same directory.

The following entry needs to be reviewed and the value may need to be adjusted during the setup in case the SpellCheck service is running on a different node than the accessing Documents middleware client node. 
The configuration entry specifies the range of addresses, the SpellCheck service is accepting client connections from. Use 0.0.0.0 to allow connections from either client address. The default of 127.0.0.1 restricts connections to be established from localhost clients only.
<pre>
com.openexchange.spellcheck.listenAddress = 0.0.0.0
</pre>

===== SpellCheck Service Transport Security =====

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport should be enabled and the appropriate host related certificate files should be specified via the following configuration properties.
<pre>
com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile
</pre>

===== SpellCheck Monitoring =====

The SpellCheck service internally starts a ''Prometheus'' service in parallel to allow the administrator to get access to runtime metrics of the spell checking service like number of request counts and the usage of different locale dictionaries. The listen address and port of this ''Prometheus'' service can be specified via these configuration items.
<pre>
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002
</pre>
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.
<pre>
curl localhost:8002/metrics | sort
</pre>

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T14:50:26Z

Kai.ahrens: /* Valid from 7.10.4 */

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:''' The SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spell checking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file.

Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Valid until 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

==== Valid from 7.10.4 ====

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:
<pre>
open-xchange-spellcheck
</pre>

The target directory is /opt/open-xchange/spellcheck

The SpellCheck service internally uses ''hunspell'' for spell checking functionality.

When starting a SpellCheck service via ''systemd'', two ''oxspell'' processess are spawned as a ''systemd'' control group. The initial process acts as a loader and initializer for dictionaries as well as a watchdog for the spawned child process(es) that itself make up the spell checking HTTP service functionality.
<pre>
29582 29582 29582 ? 00:00:00 oxspell
29583 29582 29582 ? 00:00:02 |-oxspell
</pre>

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]

After installation of the ''open-xchange-spellcheck'' package for your platform the US English dictionaries are available by default. Please check the file location, the dictionaries were installed into and verify that the ''hunspell'' dictionary directory is present and not renamed to ''myspell'' etc. If the dictionary is renamed, you will have to use that in the config below.
<pre>
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell
</pre>

Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...
''myspell'' dictionaries might be used as well as long as they have the same format as ''hunspell'' dictionaries. Valid dictionaries consist of pairs of files with the suffixes ''*.aff'' and ''*.dic'', having the same unsuffixed file name and located side by side within the same directory.

The following entry needs to be reviewed and the value may need to be adjusted during the setup in case the SpellCheck service is running on a different node than the accessing Documents middleware client node. 
The configuration entry specifies the range of addresses, the SpellCheck service is accepting client connections from. Use 0.0.0.0 to allow connections from either client address. The default of 127.0.0.1 restricts connections to be established from localhost clients only.
<pre>
com.openexchange.spellcheck.listenAddress = 0.0.0.0
</pre>

===== SpellCheck Service Transport Security =====

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport should be enabled and the appropriate host related certificate files should be specified via the following configuration properties.
<pre>
com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile
</pre>

===== SpellCheck Monitoring =====

The SpellCheck service internally starts a ''Prometheus'' service in parallel to allow the administrator to get access to runtime metrics of the spell checking service like number of request counts and the usage of different locale dictionaries. The listen address and port of this ''Prometheus'' service can be specified via these configuration items.
<pre>
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002
</pre>
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.
<pre>
curl localhost:8002/metrics | sort
</pre>

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T14:48:55Z

Kai.ahrens: /* Valid from 7.10.4 */ Adding parent/child oxspell tree

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:''' The SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spell checking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file.

Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Valid until 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

==== Valid from 7.10.4 ====

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:
<pre>
open-xchange-spellcheck
</pre>

The target directory is /opt/open-xchange/spellcheck

The SpellCheck service internally uses ''hunspell'' for spell checking functionality.

When starting a SpellCheck service via ''systemd'', two ''oxspell'' processess are spawned as a ''systemd'' control group. The initial process acts as a loader and initializer for dictionaries as well as a watchdog for the spawned child process(es) that itself make up the spell checking HTTP service functionality.
<pre>
29582 29582 29582 ? 00:00:00 oxspell
29583 29582 29582 ? 00:00:02 |-oxspell
</pre>

After installation of the ''open-xchange-spellcheck'' package for your platform the US English dictionaries are available by default. Please check the file location, the dictionaries were installed into and verify that the ''hunspell'' dictionary directory is present and not renamed to ''myspell'' etc. If the dictionary is renamed, you will have to use that in the config below.
<pre>
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell
</pre>

Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...
''myspell'' dictionaries might be used as well as long as they have the same format as ''hunspell'' dictionaries. Valid dictionaries consist of pairs of files with the suffixes ''*.aff'' and ''*.dic'', having the same unsuffixed file name and located side by side within the same directory.

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]

The following entry needs to be reviewed and the value may need to be adjusted during the setup in case the SpellCheck service is running on a different node than the accessing Documents middleware client node. 
The configuration entry specifies the range of addresses, the SpellCheck service is accepting client connections from. Use 0.0.0.0 to allow connections from either client address. The default of 127.0.0.1 restricts connections to be established from localhost clients only.
<pre>
com.openexchange.spellcheck.listenAddress = 0.0.0.0
</pre>

===== SpellCheck Service Transport Security =====

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport should be enabled and the appropriate host related certificate files should be specified via the following configuration properties.
<pre>
com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile
</pre>

===== SpellCheck Monitoring =====

The SpellCheck service internally starts a ''Prometheus'' service in parallel to allow the administrator to get access to runtime metrics of the spell checking service like number of request counts and the usage of different locale dictionaries. The listen address and port of this ''Prometheus'' service can be specified via these configuration items.
<pre>
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002
</pre>
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.
<pre>
curl localhost:8002/metrics | sort
</pre>

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T14:31:23Z

Kai.ahrens: Adding SpellCheck service description for 7.10.4 and differences to prior releases

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:''' The SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spell checking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file.

Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Valid until 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

==== Valid from 7.10.4 ====

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:
<pre>
open-xchange-spellcheck
</pre>

The target directory is /opt/open-xchange/spellcheck

The SpellCheck service internally uses ''hunspell'' for spell checking functionality.

When starting a SpellCheck service via ''systemd'', two ''oxspell'' processess are spawned as a ''systemd'' control group. The initial process acts as a loader and initializer for dictionaries as well as a watchdog for the spawned child process(es) that itself make up the spell checking HTTP service functionality.

After installation of the ''open-xchange-spellcheck'' package for your platform the US English dictionaries are available by default. Please check the file location, the dictionaries were installed into and verify that the ''hunspell'' dictionary directory is present and not renamed to ''myspell'' etc. If the dictionary is renamed, you will have to use that in the config below.
<pre>
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell
</pre>

Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...
''myspell'' dictionaries might be used as well as long as they have the same format as ''hunspell'' dictionaries. Valid dictionaries consist of pairs of files with the suffixes ''*.aff'' and ''*.dic'', having the same unsuffixed file name and located side by side within the same directory.

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]

The following entry needs to be reviewed and the value may need to be adjusted during the setup in case the SpellCheck service is running on a different node than the accessing Documents middleware client node. 
The configuration entry specifies the range of addresses, the SpellCheck service is accepting client connections from. Use 0.0.0.0 to allow connections from either client address. The default of 127.0.0.1 restricts connections to be established from localhost clients only.
<pre>
com.openexchange.spellcheck.listenAddress = 0.0.0.0
</pre>

===== SpellCheck Service Transport Security =====

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport should be enabled and the appropriate host related certificate files should be specified via the following configuration properties.
<pre>
com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile
</pre>

===== SpellCheck Monitoring =====

The SpellCheck service internally starts a ''Prometheus'' service in parallel to allow the administrator to get access to runtime metrics of the spell checking service like number of request counts and the usage of different locale dictionaries. The listen address and port of this ''Prometheus'' service can be specified via these configuration items.
<pre>
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002
</pre>
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.
<pre>
curl localhost:8002/metrics | sort
</pre>

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T13:37:50Z

Kai.ahrens: /* Spell Checking */ Adding section unitl 7.10.3

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:'''The SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spellchecking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file, e.g.:

<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003 # Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
</pre>

=== Spell Checking ===

By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

==== Up to 7.10.3 ====

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T13:30:45Z

Kai.ahrens: /* Spell Checking */ Adding SpellCheck service section for 7.10.4 on

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

== SpellCheck Service ==

Starting with release 7.10.4 the SpellCheck service has been introduced.

'''Important:'''The SpellCheck service needs to be installed, configured and run. All Documents related core modules for Text, Spreadsheet and Presentation rely on this service in order to check spelling for typed words and text contained in opened documents.

By default, a Documents middleware node has its internal configuration set to connect to a SpellCheck service installed at the same node (localhost), that listens at port 8003 for spellchecking requests.

For larger deployments, it is possible to install one or more SpellCheck services at different nodes, in which case the appropriate configuration to access the related SpellCheck service needs to be provided at the /opt/open-xchange/etc/documents.properties file, e.g.:

<pre>
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003 # Http or Https transport protocols are available, depending on the configuration of the remote SpellCheck service. The final URL needs to contain the remote address and the used port (8003 by default) of the SpellCheck service.
</pre>

=== Spell Checking ===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-05-11T12:57:57Z

Kai.ahrens: /* Installation */ Adding install sections for 7.10.4 wrt. new SpellCheck service

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).

The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Notes:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates|spellcheck/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.

As soon as more than 1 DCS runs ActiveMQ Failover is used to form a symmetric high availability cluster. The Middleware initially connects to a random DCS. Should a DCS disappear a new connection is established choosing one of the others randomly.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors and the DCS as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide 7103

2019-11-22T13:23:11Z

Kai.ahrens: /* Documents Collaboration Service */

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes. The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enabled:
<pre>
a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide 7103

2019-11-22T13:20:15Z

Kai.ahrens: Reviewing and updating DCS setup

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service (DCS) needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by middleware nodes. The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the middleware.

Discovery of running DCS services is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as previously set for the DCS (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enabled:
<pre>
a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide 7103

2019-11-22T12:42:15Z

Kai.ahrens: Server => Service, adding link to DCS configuration documentation page

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for a small (even single node) environments.
The server can be run as one additional service (JVM) or for larger deployments several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.

=== Documents Collaboration Service (DCS) ===

prepare documents-collaboration repo as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

Target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is /etc/documents-collaboration/dcs.properties. All available configuration items are described at this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server location]

The following entries need to be reviewed and values adjusted to the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its connection data to a database for discovery by middleware nodes. The appropriate database schema for the DCS as well as appropriate database access data for the DCS user need to be set prior to starting up the DCS for the first time.

The appropriate database connection properties to be used by the DCS itself need to be set at the configuration file /etc/documents-collaboration/dcs.properties:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in //etc//documents-collaboration/logback-spring.xml and points to //var//log//open-xchange//documents-collaboration//documents-collaboration.log

The Documents Collaboration Service will be started with
systemctl start open-xchange-documents-collaboration.service

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

no new pkg repo, no new pkgs required for middleware

Discovery of the DCS service is configured in documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as set for the DCS above:
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enable

<pre>
a2enmod proxy_wstunnel
</pre>

and the apache configuration needs to be enhanced by:

<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

Template:InstallPlugin

2019-10-21T10:02:21Z

Kai.ahrens: Undo revision 24932 by Kai.ahrens (talk)

== Install on OX {{#if:{{{version|}}}|{{{version}}}| AppSuite}}==

=== Debian GNU/Linux 8.0 ===

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

deb https://{{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}@|}}software.open-xchange.com/{{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}/{{{sopath}}}/DebianJessie/ /{{#if:{{{ldbaccount|}}}||
<code>
# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/{{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}/{{{sopath}}}/updates/DebianJessie/ /
</code>
}}

and run

$ apt-get update
$ apt-get install {{{pluginname}}}

=== Debian GNU/Linux 9.0 ===

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

deb https://{{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}@|}}software.open-xchange.com/{{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}/{{{sopath}}}/DebianStretch/ /{{#if:{{{ldbaccount|}}}||
<code>
# if you have a valid maintenance subscription, please uncomment the
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/{{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}/{{{sopath}}}/updates/DebianStretch/ /
</code>
}}

and run

$ apt-get update
$ apt-get install {{{pluginname}}}

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <tt>zypper</tt> if not already present:

$ zypper ar https://{{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}@|}}software.open-xchange.com/{{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}/{{{sopath}}}/SLE_12 {{#if:{{{reponame|}}}|{{{reponame}}}|ox}}
{{#if:{{{ldbaccount|}}}||
If you have a valid maintenance subscription, please run the following command and add the ldb account data to the url so that
the most recent packages get installed:
$ zypper ar https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/{{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}/{{{sopath}}}/updates/SLES11 ox-updates
}}

and run

$ zypper ref
$ zypper in {{{pluginname}}}

{{InstallPluginRHEL|ldbaccount={{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}|}}|rheltitle=RedHat Enterprise Linux 6|rhelname=RHEL6|pluginname={{{pluginname}}}|sopath={{{sopath}}}|reponame={{#if:{{{reponame|}}}|{{{reponame}}}|ox}}|toplevel={{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}}}

{{InstallPluginRHEL|ldbaccount={{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}|}}|rheltitle=RedHat Enterprise Linux 7|rhelname=RHEL7|pluginname={{{pluginname}}}|sopath={{{sopath}}}|reponame={{#if:{{{reponame|}}}|{{{reponame}}}|ox}}|toplevel={{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}}}

{{InstallPluginRHEL|ldbaccount={{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}|}}|rheltitle=CentOS 6|rhelname=RHEL6|pluginname={{{pluginname}}}|sopath={{{sopath}}}|reponame={{#if:{{{reponame|}}}|{{{reponame}}}|ox}}|toplevel={{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}}}

{{InstallPluginRHEL|ldbaccount={{#if:{{{ldbaccount|}}}|{{{ldbaccount}}}|}}|rheltitle=CentOS 7|rhelname=RHEL7|pluginname={{{pluginname}}}|sopath={{{sopath}}}|reponame={{#if:{{{reponame|}}}|{{{reponame}}}|ox}}|toplevel={{#if:{{{toplevel|}}}|{{{toplevel}}}|OX6}}}}

Template:InstallPlugin

2019-10-21T09:58:00Z

Kai.ahrens: /* Install on OX {{#if:{{{version|}}}|{{{version}}}| AppSuite}} */

AppSuite:DocumentConverter Installation Guide

2019-09-13T16:46:31Z

Kai.ahrens: /* Conversion Job Priority */

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.
First, if this is a new AS installation, make sure that the node is allowing it's AS services to listen and be available for traffic. You can configure this by defining the "host to listen" in
/opt/open-xchange/etc/overwrite.properties:
com.openexchange.connector.networkListenerHost=0.0.0.0
Defined here as 0.0.0.0 as a wildcard address.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Processing Overwiew ==
In order to make use of the DocumentConverter to convert a document into an appropriate target format, the user
sends HTTP(s) requests to the DocumentConverter web service. The possible requests and request parameters are specified within the [[AppSuite:DocumentConverter_API|API reference]] section.

When a conversion request is received by the DocumentConverter web service, the document to be converted and specified by the URL parameter of the request is first retrieved and temporarily stored. The web service request handler in addition extracts and prepares all necessary parameters, creates a conversion job for the underlying DocumentConverter, makes the conversion call and waits for the result of the conversion to be returned. The temporary, locally stored source document gets deleted automatically before the DocumentConverter web service request returns the response.

A call for document conversion is first scheduled within a queue by the DocumentConverter to be able to convert a high amount of documents in parallel, even with limited system resources and parallel conversion engines running. This is necessary since the conversion of one document might consume a lot of processing time (up to 60s by default per configured conversion engine by default).

If one of the configured, parallel conversion engines gets available, it retrieves the next job from the queue and performs the conversion itself.

After the conversion by one of the parallel running conversion engines of the DocumentConverter has finished, the result of the conversion is returned to the caller of the conversion request. The whole conversion process in this case is a synchronous process from the point of view of the caller.

=== Conversion Job Priority ===
In case of larger deployments with different document conversion demands like in the Appsuite case, it is often needed to specify some constraints wrt. the calling performance for conversion requests.
E.g. in case of conversion requests as a result of direct user input within the frontend, the conversion result should be available as soon as possible for a better UI experience for the user.
There are other scenarios for which there's no need for a fast conversion response, e.g. in case of a background pre conversion of documents, that are not visible for the customer at the moment of the conversion request.
For such cases, the DocumentConverter provides a mechanism to set a priority at each conversion request via the 'priority' parameter.
The currently available priority parameter values in increasing order are:

* background
* '''low'''
* medium
* high
* instant

In case no priority is set within the request, the default priority 'low' is used internally.

The set priority of a conversion job affects the sorting order of the conversion queue of the DocumentConverter. Conversion jobs with a higher priority will always be processed before jobs with a lower priority. Conversion jobs with the same priority are added to the queue in a time based, sequential order according to their set priority.

Due to this fact and a possible high amount of other conversion jobs with a higher priority due to e.g. direct user interaction, the caller of a conversion request should ensure to set the appropriate priority with respect to her current conversion task. In case of conversion results, intended to be seen by the user as soon as possible, setting the highest conversion priority 'instant' should be taken into account in general.

== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-09-13T16:45:15Z

Kai.ahrens: /* Conversion Job Priority */

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.
First, if this is a new AS installation, make sure that the node is allowing it's AS services to listen and be available for traffic. You can configure this by defining the "host to listen" in
/opt/open-xchange/etc/overwrite.properties:
com.openexchange.connector.networkListenerHost=0.0.0.0
Defined here as 0.0.0.0 as a wildcard address.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Processing Overwiew ==
In order to make use of the DocumentConverter to convert a document into an appropriate target format, the user
sends HTTP(s) requests to the DocumentConverter web service. The possible requests and request parameters are specified within the [[AppSuite:DocumentConverter_API|API reference]] section.

When a conversion request is received by the DocumentConverter web service, the document to be converted and specified by the URL parameter of the request is first retrieved and temporarily stored. The web service request handler in addition extracts and prepares all necessary parameters, creates a conversion job for the underlying DocumentConverter, makes the conversion call and waits for the result of the conversion to be returned. The temporary, locally stored source document gets deleted automatically before the DocumentConverter web service request returns the response.

A call for document conversion is first scheduled within a queue by the DocumentConverter to be able to convert a high amount of documents in parallel, even with limited system resources and parallel conversion engines running. This is necessary since the conversion of one document might consume a lot of processing time (up to 60s by default per configured conversion engine by default).

If one of the configured, parallel conversion engines gets available, it retrieves the next job from the queue and performs the conversion itself.

After the conversion by one of the parallel running conversion engines of the DocumentConverter has finished, the result of the conversion is returned to the caller of the conversion request. The whole conversion process in this case is a synchronous process from the point of view of the caller.

=== Conversion Job Priority ===
In case of larger deployments with different document conversion demands like in the Appsuite case, it is often needed to specify some constraints wrt. the calling performance for conversion requests.
E.g. in case of conversion requests as a result of direct user input within the frontend, the conversion result should be available as soon as possible for a better UI experience for the user.
There are other scenarios for which there's no need for a fast conversion response, e.g. in case of a background pre conversion of documents, that are not visible for the customer at the moment of the conversion request.
For such cases, the DocumentConverter provides a mechanism to set a priority at each conversion request via the 'priority' parameter.
The currently available priority parameter values in increasing order are:

* background
* '''low'''
* medium
* high
* instant

In case no priority is set within the request, the default priority 'low' is used internally.

The set priority of a conversion job affects the sorting order of the conversion queue of the DocumentConverter. Conversion jobs with a higher priority will always be processed before jobs with a lower priority. Conversion jobs with the same priority are added to the queue in a time based, sequential order according to their set priority.
Due to this fact and a possible high amount of other conversion jobs with a higher priority due to e.g. direct user interaction, the caller of a conversion request should ensure to set the appropriate priority with respect to her current conversion task. In case of conversion results, intended to be seen by the user as soon as possible, setting the highest conversion priority 'instant' should be taken into account in general.

== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-09-13T16:39:43Z

Kai.ahrens: /* Processing Overwiew */

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.
First, if this is a new AS installation, make sure that the node is allowing it's AS services to listen and be available for traffic. You can configure this by defining the "host to listen" in
/opt/open-xchange/etc/overwrite.properties:
com.openexchange.connector.networkListenerHost=0.0.0.0
Defined here as 0.0.0.0 as a wildcard address.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Processing Overwiew ==
In order to make use of the DocumentConverter to convert a document into an appropriate target format, the user
sends HTTP(s) requests to the DocumentConverter web service. The possible requests and request parameters are specified within the [[AppSuite:DocumentConverter_API|API reference]] section.

When a conversion request is received by the DocumentConverter web service, the document to be converted and specified by the URL parameter of the request is first retrieved and temporarily stored. The web service request handler in addition extracts and prepares all necessary parameters, creates a conversion job for the underlying DocumentConverter, makes the conversion call and waits for the result of the conversion to be returned. The temporary, locally stored source document gets deleted automatically before the DocumentConverter web service request returns the response.

A call for document conversion is first scheduled within a queue by the DocumentConverter to be able to convert a high amount of documents in parallel, even with limited system resources and parallel conversion engines running. This is necessary since the conversion of one document might consume a lot of processing time (up to 60s by default per configured conversion engine by default).

If one of the configured, parallel conversion engines gets available, it retrieves the next job from the queue and performs the conversion itself.

After the conversion by one of the parallel running conversion engines of the DocumentConverter has finished, the result of the conversion is returned to the caller of the conversion request. The whole conversion process in this case is a synchronous process from the point of view of the caller.

=== Conversion Job Priority ===
In case of larger deployments with different document conversion demands like in the Appsuite case, it is often needed to specify some constraints wrt. the calling performance for conversion requests.
E.g. in case of conversion requests as a result of direct user input within the frontend, the conversion result should be available as soon as possible for a better UI experience for the user.
There are other scenarios for which there's no need for a fast conversion response, e.g. in case of a background pre conversion of documents, that are not visible for the customer at the moment of the conversion request.
For such cases, the DocumentConverter provides a mechanism to set a priority at each conversion request via the 'priority' parameter.
The currently available priority parameter values in increasing order are:

* background
* '''low'''
* medium
* high
* instant

In case no priority is set within the request, the default priority 'low' is used internally.

The set priority of a conversion job affects the sorting order of the conversion queue of the DocumentConverter. Conversion jobs with a higher priority will always be processed before jobs with a lower priority. Conversion jobs with the same priority are added to the queue in a time based, sequential order according to their set priority.
Due to this fact and a possible high amount of other conversion jobs with a higher priority due to e.g. direct user interaction, the caller of a conversion request should ensure to set the appropriate priority with respect to her current conversion task. In case of conversion results, intended to be seen by the user as soon as possible, setting the highest conversion priority 'instant' should be taken into account in general.

== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-09-13T13:32:52Z

Kai.ahrens: /* Processing Overwiew */

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.
First, if this is a new AS installation, make sure that the node is allowing it's AS services to listen and be available for traffic. You can configure this by defining the "host to listen" in
/opt/open-xchange/etc/overwrite.properties:
com.openexchange.connector.networkListenerHost=0.0.0.0
Defined here as 0.0.0.0 as a wildcard address.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Processing Overwiew ==
In order to make use of the DocumentConverter to convert a document into an appropriate target format, the user
sends HTTP(s) requests to the DocumentConverter web service. The possible requests and request parameters are specified within the [[AppSuite:DocumentConverter_API|API reference]] section.

When a conversion request is received by the DocumentConverter web service, the document to be converted and specified by the URL parameter of the request is first retrieved and temporarily stored. The web service request handler in addition extracts and prepares all necessary parameters, creates a conversion job for the underlying DocumentConverter, makes the conversion call and waits for the result of the conversion to be returned. The temporary, locally stored source document gets deleted automatically before the DocumentConverter web service request returns the response.

A call for document conversion is first scheduled within a queue by the DocumentConverter to be able to convert a high amount of documents in parallel, even with limited system resources and parallel conversion engines running. This is necessary since the conversion of one document might consume a lot of processing time (up to 60s by default per configured conversion engine by default).

If one of the configured, parallel conversion engines gets available, it retrieves the next job from the queue and performs the conversion itself.

After the conversion by one of the parallel running conversion engines of the DocumentConverter has finished, the result of the conversion is returned to the caller of the conversion request. The whole conversion process in this case is a synchronous process from the point of view of the caller.

== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-09-13T13:29:17Z

Kai.ahrens: Adding 'Processing Overview' section

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.
First, if this is a new AS installation, make sure that the node is allowing it's AS services to listen and be available for traffic. You can configure this by defining the "host to listen" in
/opt/open-xchange/etc/overwrite.properties:
com.openexchange.connector.networkListenerHost=0.0.0.0
Defined here as 0.0.0.0 as a wildcard address.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Processing Overwiew ==
In order to make use of the DocumentConverter to convert a document into an appropriate target format, the user
sends HTTP(s) requests to the DocumentConverter web service. The possible requests and request parameters are specified within the [[AppSuite:DocumentConverter_API|API reference]] section.

When a conversion request is received by the DocumentConverter web service, the document to be converted and specified by the URL parameter of the request is first retrieved and temporarily stored. The web service request handler in addition extracts and prepares all necessary parameters, creates a conversion job for the underlying DocumentConverter, nmakes trher and waitsall nec This temporary, locally stored source document gets deleted automatically before the DocumentConverter web service request returns. The DocumentConverter web service itself makes use of the underlying DocumentConverter

A request for document conversion is first scheduled within a queue by the DocumentConverter to be able to convert a high amount of documents even with limited system resources and conversion engines running in parallel. This is necessary since the conversion of one document might consume a lot of processing time (up to 60s by default per configured conversion by default).

If one of the configured, parallel conversion engines gets available, it retrieves the next job from the head of the queue and performs the conversion itself.

After the conversion by one of the parallel running conversion engines of the DocumentConverter has finished, the result of the conversion is returned to the caller of the conversion request. The whole conversion process in this case is a synchronous process from the point of view of the caller.

== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter API

2019-09-13T12:24:48Z

Kai.ahrens: Added 'priority' parameter to API description

== OX Document Converter API ==

== Overview ==

Beside the primary implementation design goals of stability and robustness, one of the API design goals was ease of use, combined with a reasonable, but easily extensible feature set.
The sole purpose of the [[AppSuite:DocumentConverter_Installation_Guide|OX Document Converter]] web service is to offer conversion functionality of a wide range of commonly available, often proprietary, document formats into well known standards, that can be displayed and post processed by standard tools like web browsers, image tools or pdf viewers.

Having this single purpose as its main feature, the API of this web service indeed consists of one call, receiving the data of an arbitrary input document and returning the result of the conversion in another format, that the user can specify.

=== Base URL ===
The base URL to initiate a conversion is as follows:
http://host:port/documentconverterws

=== Parameters ===

To initiate a conversion via the OX Document Converter WebService, an XMLHttpRequest object is created on client side, containig the basic URL as given above and setting the following parameters at the request:
* 'action': the action to be performed; currently, only 'convert' is supported
* 'fileformat': the file format of the conversion result; currently supported file fomats are:
* 'html': the result is returned as a HTML document, containing SVG elements for each page of the converted document
* 'pdf': the result is returned as a PDF document
* 'data'; the Base64 encoded file content to be converted

The XMLHttpRequest has to be executed as a POST request. As such, the parameters of the request need to be set within the body of the request.
The data parameter contains the content of the source document to be converted. It needs to be encoded as Base64 data.
The result of the conversion can be obtained from the HTTP response.

== Reference ==
The Open-Xchange DocumentConverter WebService API consists of a set of possible HTTP requests, with each different call defined by a set of HTTP request parameters.

If not stated otherwise, the listed parameters for each call are mandatory. A set of possible parameter values for a call parameter is denoted by a pipe symbol within this documentation. Parameter values in quotes are fixed values. The quote character itself must not be set within the real call. Parameter values without quotes are placeholders for user defined values

URLs within the call can be either specified as a data URL, a HTTP URL or a file URL. In the case of data URLs, the caller needs to take care of using only the POST method for making the HTTP request in order to allow the upload of large data. Some possible example URLs are given below:

data:mimeType;base64,dataSequence (HTTPRequest via POST method only)
http://www.example.com/test.odf (HTTPRequest via GET or POST method)
file:///home/example/test.odf (HTTPRequest via GET or POST method)

Return values are either file attachments or objects according to the JSON notation within the response body of the HTTP request. Depending on the chosen/available return type of the call, the receiver of the call needs to handle this return value accordingly.

=== convert ===
Stateless conversion of a file, specified by an URL, to a target format.

The conversion result data is given back as an archive in the file case as well as in the JSON case.\\ In the JSON case, the returned mime type parameter contains the mime type of the single pages within the returned archive.\\ The extension parameter contains the default file extension for the returned mime type for convenience reasons at further processing steps within the client code.

:Call Parameters
* action: "convert"
* url: dataURL | fileURL | httpURL
* targetformat: "html" | "pdf" | "odf" | "ooxml" | "jpeg" | "png"
* firstpageonly: ["false" | "true"] (Optional, Default: "false")
* returntype: ["file" | "json"] (Optional, Default: "file")
* priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

:Return Value
* file | json {errorcode: "errorCode", mimetype: "mimeType", extension: "extension", result: "dataURL"}

=== getpreview ===
Stateless retrieval of a preview from a file, specified by an URL, as an image.

The result as a file or as the dataURL of the JSON response is given back in the native format of the image.

:Call Parameters
* action: "getpreview"
* url: dataURL | fileURL | httpURL
* targetformat: "jpeg" | "png"
* returntype: ["file" | "json"] (Optional, Default: "file")
* priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

:Return Value
* file | json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

=== getthumbnail ===
Stateless retrieval of a thumbnail preview from a file, specified by an URL, as an image.

The result as a file or as the dataURL of the JSON response is given back in the native format of the image.

:Call Parameters
* action: "getthumbnail"
* url: dataURL | fileURL | httpURL
* targetformat: "jpeg" | "png"
* returntype: [“file” | “json”] (Optional, Default: “file”)
* priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

:Return Value
* file | json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

=== beginconvert ===
Initiating a stateful/cached conversion of a file, specified by an URL, to a target format. The result object contains the jobId to work with in subsequent calls to "getpage" and "endconvert".

The result is returned in JSON format.

:Call Parameters
* action: "beginconvert"
* targetformat: "html" | "jpeg" | "png"
* url: dataURL | fileURL | httpURL
* priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

:Return Value
* json {errorcode: "errorCode", jobid: "jobId", pagecount: "pageCount"}

=== getpage ===
Stateful call to retrieve a specified page from a previously initiated conversion job. 'beginconvert' must have been called before in order to acquire the correct 'jobid'.

The result as a file or as the dataURL of the JSON response is given back in the native format of the converted page.

:Call Parameters
* action: "getpage"
* jobid: jobID
* pagenumber: pageNumber
* returntype: [“file” | “json”] (Optional, Default: “file”)

:Return Value
* file | json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

=== endconvert ===
Finishing a previously initiated conversion job. This call needs to be made in order to free any cached resources, that have been allocated since the 'beginconvert' call. The initially returned jobId is not valid after this call anymore.

:Call Parameters:
* action: "endconvert"
* jobid: jobID

:Return Value
* json {errorcode: "errorCode"}

== Sample Code ==

A small example shows the usage of the API.
Adapt the [[Media:DocumentConverterSample.java|sample code]] to match your installation.
There are two occurrences of ''host.example.com'' with have to replaced with the server running the conversion service.

AppSuite:DocumentsMonitoring

2019-08-21T13:17:45Z

Kai.ahrens: Adding table of DC server metrics / Updating DC server metrics sample output

= OX Documents / OX Documentconverter Monitoring =

== General ==

The Open-Xchange JMX offers the ability to fetch runtime information of the Java virtual machine, and about the Open-Xchange Middleware (aka groupware backend) including OX Documents and Documentconverter.

For general information about the JMX interface see: [[OX_monitoring_interface]]

The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]

Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]

== OX Documentconverter ==

Monitoring data for OX Documentconverter can be obtained after installation of the package open-xchange-munin-scripts-jolokia. It uses Jolokia if available and configured.

The following table shows all available Documentconverter server metrics, provided via the JMX interface:

{| class="wikitable"
!colspan="6"|Documentconverter server metrics
|-
|'''Metrics Name'''
|'''Description'''
|'''Instance / LongTerm'''
|'''Remarks'''
|-
|CacheEntryCount
|The current count of entries, stored within the persistent cache
|Instance
|
|-
|CacheFreeVolumeSize
|The current free size in bytes of the volume, the cache root directory is located on. The size is calculated on a volume block size basis to reflect the correct size of the free volume.
|Instance
|
|-
|CacheHitRatio
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient
|Instance
|
|-
|CacheOldestEntrySeconds
|The age of the oldest entry within the cache in seconds
|Instance
|From 7.10.3 on
|-
|CachePersistentSize
|The current size in bytes of all persistent entries, stored within the cache directory. The size is calculated on a volume block size basis to reflect the correct summed up size.
|Instance
|
|-
|ConversionCount
|The total number of all physical ReaderEngine and PDFTool conversions
|Instance
|
|-
|ConversionCountPDFTool
|The total number of all physical PDFTool conversions
|Instance
|
|-
|ConversionCountReaderEngine
|The total number of all physical ReaderEngine conversions
|Instance
|
|-
|ConversionCountWithMultipleRuns
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance
|Instance
|
|-
|ConversionErrorsGeneral
|The total number of physical ReaderEngine conversions, that resulted in a general error
|Instance
|
|-
|ConversionErrorsTimeout
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error
|Instance
|
|-
|ConversionErrorsDisposed
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)
|Instance
|
|-
|ConversionErrorsPassword
|The total number of physical ReaderEngine conversions, that resulted in a password error
|Instance
|
|-
|ConversionErrorsNoContent
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)
|Instance
|
|-
|ConversionErrorsOutOfMemory
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error
|Instance
|
|-
|ConversionErrorsPDFTool
|The total number of physical PDFTool conversions, that resulted in an error
|Instance
|
|-
|ErrorCacheHitRatio
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient
|Instance
|
|-
|JobErrorsTimeout
|The total number of jobs, that returned with a timeout error
|Instance
|
|-
|JobErrorsTotal
|The total number of jobs, that returned with an error
|Instance
|
|-
|JobsProcessed
|The total number of jobs that have been processed
|Instance
|
|-
|MedianConversionTimeMillis_Background
|The median time in milliseconds, a physical ReaderEngine conversion with background priority lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianConversionTimeMillis_Low
|The median time in milliseconds, a physical ReaderEngine conversion with low priority lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianConversionTimeMillis_Medium
|The median time in milliseconds, a physical ReaderEngine conversion with medium priority lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianConversionTimeMillis_High
|The median time in milliseconds, a physical ReaderEngine conversion with high priority lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianConversionTimeMillis_Instant
|The median time in milliseconds, a physical ReaderEngine conversion with instant priority lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianConversionTimeMillis_Total
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianJobTimeMillis_Background
|The median time in milliseconds, a job with background priority needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianJobTimeMillis_Low
|The median time in milliseconds, a job with low priority needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianJobTimeMillis_Medium
|The median time in milliseconds, a job with medium priority needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianJobTimeMillis_High
|The median time in milliseconds, a job with high priority needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianJobTimeMillis_Instant
|The median time in milliseconds, a job with instant priority needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianJobTimeMillis_Total
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianQueueTimeMillis_Background
|The median time in milliseconds, a background job waited in the queue for processing, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianQueueTimeMillis_Low
|The median time in milliseconds, a low priority job waited in the queue for processing, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianQueueTimeMillis_Medium
|The median time in milliseconds, a medium priority job waited in the queue for processing, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianQueueTimeMillis_High
|The median time in milliseconds, a high priority job waited in the queue for processing, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianQueueTimeMillis_Instant
|The median time in milliseconds, an instant priority job waited in the queue for processing, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|MedianQueueTimeMillis_Total
|The median time in milliseconds, a job waited in the queue for processing, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInQueue_Background
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInQueue_Low
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInQueue_Medium
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInQueue_High
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInQueue_Instant
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInQueue_Total
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PeakJobCountInAsyncQueue_Total
|The peak number of jobs in the queue for asynchronous jobs, measured from the beginning of the last reset/initialization on (default period: 5 minutes)
|Instance
|
|-
|PendingStatefulJobCount
|The number of stateful job conversions for that no endConvert has been called up to now
|Instance
|From 7.10.3 on
|-
|QueueLimitHighReachedCountInstance
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance
|Instance
|From 7.10.3 on
|-
|QueueLimitLowReachedCountInstance
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance
|Instance
|From 7.10.3 on
|-
|QueueLimitHighReachedCountLongTerm
|The accumulated number of times the job queue high limit has been reached for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|From 7.10.3 on
|-
|QueueLimitLowReachedCountLongTerm
|The accumulated number of times the job queue low limit has been reached all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|From 7.10.3 on
|-
|QueueTimeoutCountInstance
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance
|Instance
|From 7.10.3 on
|-
|QueueTimeoutCountLongTerm
|The accumulated number of times the job queue timeout has been reached for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|From 7.10.3 on
|-
|RuntimeSecondsInstance
|The runtime in seconds for the current DocumentConverter server instance
|Instance
|
|-
|RuntimeSecondsLongTerm
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|ScheduledJobCountInQueue
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed
|Instance
|From 7.10.3 on
|-
|UserRequestCountInstance_Total
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstance_Text
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstance_Spreadsheet
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstance_Presentation
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstance_Image
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountLongTerm_Total
|The accumulated number of all WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTerm_Text
|The accumulated number of text document related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTerm_Spreadsheet
|The accumulated number of spreadsheet document related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTerm_Presentation
|The accumulated number of presentation document related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTerm_Image
|The accumulated number of image related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountInstanceFailed_Total
|The number of all WebService requests, that failed with an error and that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstanceFailed_Text
|The number of text document related WebService requests, that failed with an error and that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstanceFailed_Spreadsheet
|The number of spreadsheet document related WebService requests, that failed with an error and that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstanceFailed_Presentation
|The number of presentation document related WebService requests, that failed with an error and that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountInstanceFailed_Image
|The number of image related WebService requests, that failed with an error and that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestCountLongTermFailed_Total
|The accmulated number of all WebService requests, that failed with an error and that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTermFailed_Text
|The accmulated number of text document related WebService requests, that failed with an error and that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTermFailed_Spreadsheet
|The accmulated number of spreadsheet document related WebService requests, that failed with an error and that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTermFailed_Presentation
|The accmulated number of presentation document related WebService requests, that failed with an error and that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestCountLongTermFailed_Image
|The accmulated number of image related WebService requests, that failed with an error and that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestSuccessRatioInstance_Total
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestSuccessRatioInstance_Text
|The ratio of successful text document related WebService requests against failed text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestSuccessRatioInstance_Spreadsheet
|The ratio of successful spreadsheet document related WebService requests against failed spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestSuccessRatioInstance_Presentation
|The ratio of successful presentation document related WebService requests against failed presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestSuccessRatioInstance_Image
|The ratio of successful image related WebService requests against failed image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance
|Instance
|
|-
|UserRequestSuccessRatioLongTerm_Total
|The accumulated ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestSuccessRatioLongTerm_Text
|The accumulated ratio of successful text document related WebService requests against failed text document related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestSuccessRatioLongTerm_Spreadsheet
|The accumulated ratio of successful spreadsheet document related WebService requests against failed spreadsheet document related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestSuccessRatioLongTerm_Presentation
|The accumulated ratio of successful presentation document related WebService requests against failed presentation document related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|-
|UserRequestSuccessRatioLongTerm_Image
|The accumulated ratio of successful image related WebService requests against failed image related WebService requests, that have the user flag set to true, for all previously started DocumentConverter server instances and the current DocumentConverter server instance
|Long term
|
|}

Here is a list of sample data provided by
<pre>
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort

CacheEntryCount = 10258
CacheFreeVolumeSize = 2709409792
CacheHitRatio = 0.9642857142857143
CacheOldestEntrySeconds = 1998029
CachePersistentSize = 564215808
ConversionCount = 1
ConversionCountPDFTool = 0
ConversionCountReaderEngine = 1
ConversionCountWithMultipleRuns = 0
ConversionErrorsDisposed = 0
ConversionErrorsGeneral = 0
ConversionErrorsNoContent = 0
ConversionErrorsOutOfMemory = 0
ConversionErrorsPassword = 1
ConversionErrorsPDFTool = 0
ConversionErrorsTimeout = 0
ErrorCacheHitRatio = 0.0
JobErrorsTimeout = 0
JobErrorsTotal = 1
JobsProcessed = 28
MedianConversionTimeMillis_Background = 0
MedianConversionTimeMillis_High = 0
MedianConversionTimeMillis_Instant = 0
MedianConversionTimeMillis_Low = 0
MedianConversionTimeMillis_Medium = 0
MedianConversionTimeMillis_Total = 0
MedianJobTimeMillis_Background = 0
MedianJobTimeMillis_High = 0
MedianJobTimeMillis_Instant = 0
MedianJobTimeMillis_Low = 0
MedianJobTimeMillis_Medium = 0
MedianJobTimeMillis_Total = 0
MedianQueueTimeMillis_Background = 0
MedianQueueTimeMillis_High = 0
MedianQueueTimeMillis_Instant = 0
MedianQueueTimeMillis_Low = 0
MedianQueueTimeMillis_Medium = 0
MedianQueueTimeMillis_Total = 0
PeakJobCountInAsyncQueue_Total = 0
PeakJobCountInQueue_Background = 0
PeakJobCountInQueue_High = 0
PeakJobCountInQueue_Instant = 0
PeakJobCountInQueue_Low = 0
PeakJobCountInQueue_Medium = 0
PeakJobCountInQueue_Total = 0
PendingStatefulJobCount = 0
QueueLimitHighReachedCountInstance = 33
QueueLimitHighReachedCountLongTerm = 66
QueueLimitLowReachedCountInstance = 33
QueueLimitLowReachedCountLongTerm = 66
QueueTimeoutCountInstance = 22
QueueTimeoutCountLongTerm = 44
RuntimeSecondsInstance = 6707
RuntimeSecondsLongTerm = 28607051
ScheduledJobCountInQueue = 0
UserRequestCountInstanceFailed_Image = 0
UserRequestCountInstanceFailed_Presentation = 0
UserRequestCountInstanceFailed_Spreadsheet = 0
UserRequestCountInstanceFailed_Text = 0
UserRequestCountInstanceFailed_Total = 0
UserRequestCountInstance_Image = 0
UserRequestCountInstance_Presentation = 0
UserRequestCountInstance_Spreadsheet = 0
UserRequestCountInstance_Text = 0
UserRequestCountInstance_Total = 0
UserRequestCountLongTermFailed_Image = 0
UserRequestCountLongTermFailed_Presentation = 10694
UserRequestCountLongTermFailed_Spreadsheet = 2598
UserRequestCountLongTermFailed_Text = 6369
UserRequestCountLongTermFailed_Total = 19661
UserRequestCountLongTerm_Image = 0
UserRequestCountLongTerm_Presentation = 121394
UserRequestCountLongTerm_Spreadsheet = 33453
UserRequestCountLongTerm_Text = 130801
UserRequestCountLongTerm_Total = 285648
UserRequestSuccessRatioInstance_Image = 1.0
UserRequestSuccessRatioInstance_Presentation = 1.0
UserRequestSuccessRatioInstance_Spreadsheet = 1.0
UserRequestSuccessRatioInstance_Text = 1.0
UserRequestSuccessRatioInstance_Total = 1.0
UserRequestSuccessRatioLongTerm_Image = 1.0
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227
</pre>

=== OX Documentconverter and munin ===

The Documentconverter uses a different port to provide monitoring data via Jolokia. The corresponding oxJolokiaURL is has to be configured with an entry in the settings.

<pre>
[ox_documentconverter*]
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia
</pre>

== OX Documents ==

Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.

Here is a list of sample data provided by

<pre>
# /opt/open-xchange/sbin/showruntimestats -f
DocumentsSizeMedian_Spreadsheet = 0
DocumentsCreated_Presentation = 2
DocumentsCreated_Spreadsheet = 2
RestoreDocCurrent = 40
RestoreDocRestoredSuccess = 0
RestoreDocRestoredFailure = 0
DocumentsSizeMedian_Text = 0
DocumentsSizeMedian_Presentation = 0
RestoreDocCreated_Total = 40
RestoreDocRemoved_Total = 0
DocumentsSizeMedian_Total = 0
DocumentsCreated_Total = 4
DocumentsCreated_Text = 0
DocumentsClosed_Text_Timeout = 0
DocumentsSaved_Text_Total = 2
DocumentsSaved_Text_Close = 2
DocumentsSaved_Text_100ops = 0
DocumentsSaved_Text_15mins = 0
DocumentsOperations_Text_Incoming = 8
DocumentsOperations_Text_Distributed = 0
DocumentsOpened_Text_Total = 2
DocumentsOpened_Text_OOXML = 1
DocumentsOpened_Text_Binary = 0
DocumentsOpened_Text_ODF = 1
DocumentsClosed_Text_Total = 2
DocumentsOpened_Spreadsheet_Total = 22
DocumentsOpened_Spreadsheet_OOXML = 16
DocumentsOpened_Spreadsheet_Binary = 0
DocumentsOpened_Spreadsheet_ODF = 6
DocumentsClosed_Spreadsheet_Total = 19
DocumentsClosed_Spreadsheet_Timeout = 0
DocumentsSaved_Spreadsheet_Total = 10
DocumentsSaved_Spreadsheet_Close = 10
DocumentsSaved_Spreadsheet_100ops = 0
DocumentsSaved_Spreadsheet_15mins = 0
DocumentsOperations_Spreadsheet_Incoming = 46
DocumentsOperations_Spreadsheet_Distributed = 0
</pre>

== Further Reading ==

Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].

A call derived from this example for OX Documentconverter looks like

<pre>
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}
</pre>

AppSuite:Documents Installation Guide 7103

2019-06-25T14:22:42Z

Kai.ahrens: /* Documents Collaboration Server (DCS) */

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.

== Mandatory Modules ==

Additional functional modules need to be installed separately:

* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for a small (even single node) environments.
The server can be run as one additional service (JVM) or for larger deployments several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.

=== Documents Collaboration Server (DCS) ===

prepare documents-collaboration repo as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration-server
</pre>

Target directory is /usr/share/open-xchange-documents-collaboration

Configuration file is /etc/documents-collaboration/dcs.properties. The following entries need to be reviewed and values adjusted to the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its connection data to a database for discovery by middleware nodes. The appropriate database schema for the DCS as well as appropriate database access data for the DCS user need to be set prior to starting up the DCS for the first time.

The appropriate database connection properties to be used by the DCS itself need to be set at the configuration file /etc/documents-collaboration/dcs.properties:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in //etc//documents-collaboration/logback-spring.xml and points to //var//log//open-xchange//documents-collaboration//documents-collaboration.log

The DCS Service will be started with
systemctl start open-xchange-documents-collaboration.service

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Middleware node===

no new pkg repo, no new pkgs required for middleware

Discovery of the DCS service is configured in documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as set for the DCS above:
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enable

<pre>
a2enmod proxy_wstunnel
</pre>

and the apache configuration needs to be enhanced by:

<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

AppSuite:Documents Installation Guide 7103

2019-06-25T14:21:34Z

Kai.ahrens: Reading defaults for initdcsdb script from dcs.properties file

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.

== Mandatory Modules ==

Additional functional modules need to be installed separately:

* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for a small (even single node) environments.
The server can be run as one additional service (JVM) or for larger deployments several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.

=== Documents Collaboration Server (DCS) ===

prepare documents-collaboration repo as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration-server
</pre>

Target directory is /usr/share/open-xchange-documents-collaboration

Configuration file is /etc/documents-collaboration/dcs.properties. The following entries need to be reviewed and values adjusted to the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its connection data to a database for discovery by middleware nodes. The appropriate database schema for the DCS as well as appropriate database access data for the DCS user need to be set prior to starting up the DCS for the first time.

The appropriate database connection properties to be used by the DCS itself need to be set at the configuration file /etc/documents-collaboration/dcs.properties:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overriden by the admin via the command line. Passworda need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in //etc//documents-collaboration/logback-spring.xml and points to //var//log//open-xchange//documents-collaboration//documents-collaboration.log

The DCS Service will be started with
systemctl start open-xchange-documents-collaboration.service

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Middleware node===

no new pkg repo, no new pkgs required for middleware

Discovery of the DCS service is configured in documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as set for the DCS above:
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enable

<pre>
a2enmod proxy_wstunnel
</pre>

and the apache configuration needs to be enhanced by:

<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

AppSuite:Documents Installation Guide 7103

2019-06-24T15:38:42Z

Kai.ahrens: /* Documents Collaboration Server (DCS) */

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.

== Mandatory Modules ==

Additional functional modules need to be installed separately:

* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for a small (even single node) environments.
The server can be run as one additional service (JVM) or for larger deployments several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.

=== Documents Collaboration Server (DCS) ===

prepare documents-collaboration repo as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration-server
</pre>

Target directory is /usr/share/open-xchange-documents-collaboration

Configuration file is /etc/documents-collaboration/dcs.properties. The following entries need to be reviewed and values adjusted to the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its connection data to a database for discovery by middleware nodes. The appropriate database schema for the DCS as well as appropriate database access privileges for the DCS user need to be set prior to starting up the DCS for the first time. To ease this process, the admin can call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-host=192.168.10.172 --dcsdb-user=db_user --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The appropriate database connection properties to be used by the DCS itself need to be set at the configuration file /etc/documents-collaboration/dcs.properties:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

The default logging path is set in //etc//documents-collaboration/logback-spring.xml and points to //var//log//open-xchange//documents-collaboration//documents-collaboration.log

The DCS Service will be started with
systemctl start open-xchange-documents-collaboration.service

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Middleware node===

no new pkg repo, no new pkgs required for middleware

Discovery of the DCS service is configured in documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as set for the DCS above:
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enable

<pre>
a2enmod proxy_wstunnel
</pre>

and the apache configuration needs to be enhanced by:

<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

AppSuite:Documents Installation Guide 7103

2019-06-24T15:37:24Z

Kai.ahrens: /* Documents Collaboration Server (DCS) */

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.

== Mandatory Modules ==

Additional functional modules need to be installed separately:

* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for a small (even single node) environments.
The server can be run as one additional service (JVM) or for larger deployments several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.

=== Documents Collaboration Server (DCS) ===

prepare documents-collaboration repo as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration-server
</pre>

Target directory is /usr/share/open-xchange-documents-collaboration

Configuration file is /etc/documents-collaboration/dcs.properties. The following entries need to be reviewed and values adjusted to the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its connection data to a database for discovery by middleware nodes. The appropriate database schema for the DCS as well as appropriate database access privileges for the DCS user need to be set prior to starting up the DCS for the first time. To ease this process, the admin can call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-host=192.168.10.172 --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The appropriate database connection properties to be used by the DCS itself need to be set at the configuration file /etc/documents-collaboration/dcs.properties:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

The default logging path is set in //etc//documents-collaboration/logback-spring.xml and points to //var//log//open-xchange//documents-collaboration//documents-collaboration.log

The DCS Service will be started with
systemctl start open-xchange-documents-collaboration.service

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Middleware node===

no new pkg repo, no new pkgs required for middleware

Discovery of the DCS service is configured in documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as set for the DCS above:
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enable

<pre>
a2enmod proxy_wstunnel
</pre>

and the apache configuration needs to be enhanced by:

<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

AppSuite:Documents Installation Guide 7103

2019-06-24T15:14:27Z

Kai.ahrens: /* Documents Collaboration Server (DCS initdcsdb Script)

{{Version|7.10.3}}

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally there is the support of websockets proxy by the webserver required, this is e.g. available in Apache 2.4.5 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.

== Mandatory Modules ==

Additional functional modules need to be installed separately:

* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed (since 7.10.3)
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

With 7.10.3 the Documents Collaboration Service has been introduced.

The Documents Collaboration Service needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for a small (even single node) environments.
The server can be run as one additional service (JVM) or for larger deployments several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.

=== Documents Collaboration Server (DCS) ===

prepare documents-collaboration repo as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration-server
</pre>

Target directory is /usr/share/open-xchange-documents-collaboration

Configuration file is /etc/documents-collaboration/dcs.properties. The following entries need to be reviewed and values adjusted to the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its connection data to a database for discovery by middleware nodes. The appropriate database schema for the DCS as well as appropriate database access privileges for the DCS user need to be set prior to starting up the DCS for the first time. To ease this process, the admin can call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-host=192.168.10.172 --dcsdb-pass=db_password ----mysql-root-passwd=mysql_password
</pre>

The appropriate database connection properties to be used by the DCS itself need to be set at the configuration file /etc/documents-collaboration/dcs.properties:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

The default logging path is set in //etc//documents-collaboration/logback-spring.xml and points to //var//log//open-xchange//documents-collaboration//documents-collaboration.log

The DCS Service will be started with
systemctl start open-xchange-documents-collaboration.service

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Middleware node===

no new pkg repo, no new pkgs required for middleware

Discovery of the DCS service is configured in documents-collaboration-client.properties.
Add the appropriate values to access the dcsdb Database as set for the DCS above:
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

The Apache module proxy_wstunnel has to be enable

<pre>
a2enmod proxy_wstunnel
</pre>

and the apache configuration needs to be enhanced by:

<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

AppSuite:DocumentConverter Installation Guide

2019-03-27T14:47:51Z

Kai.ahrens: Using correct package names

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-03-27T14:44:55Z

Kai.ahrens: Using correct package names

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.

'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''documentconverter-api''' and the '''documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''documentconverter-webservice''' package needs to be installed beside the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the documentconverter-api and the documentconverter-client packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''documentconverter-server''' package needs to be installed beside the '''documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-03-27T14:41:32Z

Kai.ahrens: Using correct package names

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Documentconversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversionAttention: this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice). hardware available.

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''documentconverter-api''' and the '''documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''documentconverter-webservice''' package needs to be installed beside the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the documentconverter-api and the documentconverter-client packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''documentconverter-server''' package needs to be installed beside the '''documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2019-03-27T14:39:07Z

Kai.ahrens: Using correct package names

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.

The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.

In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Monitoring ===

The '''documentconverter-jolokia''' package is primarily useful to be installed on an OX documentconverter-server node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Documentconversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversionAttention: this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice). hardware available.

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''documentconverter-api''' and the '''documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''documentconverter-webservice''' package needs to be installed beside the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the documentconverter-api and the documentconverter-client packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''documentconverter-server''' package needs to be installed beside the '''documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.

'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:ReaderEngineConfig

2019-03-22T13:47:38Z

Kai.ahrens: /* Handling of temporary files */

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.

; com.openexchange.documentconverter.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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/opt/readerengine"

; com.openexchange.documentconverter.cacheDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.cache"

; com.openexchange.documentconverter.scratchDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.scratch"

; com.openexchange.documentconverter.errorDir=

This item specifies a directory for files that could not be loaded due to an error condition or due to a timeout.
 
'''Note:''' The used disk space will grow with retained files. Files have to be removed manually.
 
Default value: n/a

; com.openexchange.documentconverter.blacklistFile=/opt/open-xchange/etc/readerengine.blacklist

The list of external document content URLs that are not allowed to be loaded
by the readerengine after loading a document.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is first checked against the list of blacklist URL regular
expressions.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.blacklist"

; com.openexchange.documentconverter.whitelistFile=/opt/open-xchange/etc/readerengine.whitelist

The list of external document content URLs that are allowed to be loaded
by the readerengine after an external URL matched a blacklist pattern.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is only checked against the list of whitelist URL regular
expressions if it previously matched a pattern in the blacklist file.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.whitelist"

; com.openexchange.documentconverter.urlLinkLimit=200

The external URL link limit specifies the maximum amount of
valid external internet URLs (filtered by blacklist and whitelist before),
that are tried to get resolved by the engine when loading a document.
When this limit is reached, no more external internet URLs are resolved
for the current document.
 
'''Important:''' Please take note than one externally linked object within the document does not automatically correspond to one external URL call. In general, there are - at least - two URL calls necessary to display one externally linked object. Such additional calls are in most cases based on a format detection, happening prior to resolving the object data itself.
 
Set to -1 for no upper limit or to 0 to disable the resolving of internet URLs completely
 
Default value: 200

; com.openexchange.documentconverter.urlLinkProxy =

The external URL link proxy entry specifies a proxy server that is used by the readerengine
to resolve external links, contained within a document. Such links are e.g. external http://
graphic links, that are going to be resolved during the filtering process of a readerengine
instance.
Set this entry to the address of the proxy server: host:port
Recognized protocols are ''<nowiki>http://, https:// and ftp://</nowiki>''
Leave empty, if no proxy server should be used by the readerengine
 
Default value: n/a

; com.openexchange.documentconverter.RemoteBaseUrl =

Use a remote document conversion webservice to do the actual conversion;
Set this entry to the base URL of the remote host ''<nowiki>http://host[:port]/documentconverterPath</nowiki>'';
leave empty if conversion should happen on the local machine
 
Default value: n/a

'''From 7.8.2 on:''' The com.openexchange.documentconverter.RemoteBaseUrl is not valid for the documentconverter.properties file anymore.
The corresponding documentconverter server needs to be set on the Ox backend node, where the documentconverter-client package has been installed. The name of the new entry is ''<nowiki>com.openexchange.documentconverter.client.remoteDocumentConverterUrl</nowiki>''. The entry itself is located within the ''<nowiki>documentconverter-client.properties</nowiki>'' configuration file>

; com.openexchange.documentconverter.RemoteCacheUrls =

Use one or more remote converter cache(s) to speedup the conversion. The first entry, if set, is treated as the remote master cache, receiving cache updates from the local cache. Additional entries are treated as remote slave caches for read purposes only. 
Set the (whitespace separated) entries to the base URL('s) of the appropriate remote host(s): ''<nowiki>http://host[:port]/documentconverterCachePath</nowiki>'' 
Leave empty if only the local filesystem cache should be used
 
Default value: n/a


; com.openexchange.documentconverter.RemoteSharePointUrl =

Use a remote SharePoint service to do MSO to PDF conversions. 
Set this entry to the URL of the SharePoint host: ''<nowiki>http://host[:port]/_vti_bin/oxconvert.svc/mex?wsdl</nowiki>'' 
If left empty, the corresponding conversion job always returns false. 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointUsername =

The login user name to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointPassword =

The password to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.jobProcessorCount=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.
 
Default value: 3

; com.openexchange.documentconverter.jobRestartCount=50

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,
 
Default value: 50

; com.openexchange.documentconverter.jobExecutionTimeoutMilliseconds=60000

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

; com.openexchange.documentconverter.maxVMemMB=2048

This item determines the maximum size in megabytes (MB) of virtual memory that each started readerengine process is allowed to consume. If a job tries to consume more VMem than set via this config item, the processing of the current job for the appropriate readerengine process will be aborted and the underlying process is restarted to avoid memory corruption.
 
Set this value to -1 for no upper limit.
 
Default value: 2048

; com.openexchange.documentconverter.maxCacheSizeMB=-1

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.
 
Default value: -1

; com.openexchange.documentconverter.maxCacheEntries=-1

This item determines the maximum number of converter jobs cached at runtime. The value affects the amount of runtime job information to be cached as well as the number of file entries within the cache directory.
 
Set this value to -1 for no upper limit.
 
Default value: -1

; com.openexchange.documentconverter.cacheEntryTimeoutSeconds=2592000

This item determines the timeout in seconds, after which a cached job result is automatically removed from the cache.
 
Set this value to 0 to disable the timeout based removal of cached job results.
 
Default value: 2592000

; com.openexchange.documentconverter.enableCacheLookup=false

Setting this flag to true enables the caller of the RemoteInternalPreviewService#getCachedPreviewFor implementation (OfficePreviewService) to retrieve the cached only result of a previous conversion call, without scheduling a new job in case of a non existing cache entry, which might run for a long period time, up to the given job timeout time.
 
Set to false to disable the cache lookup within the RemoteInternalPreviewService#getCachedPreviewFor implementation.
 
Default value: false

; com.openexchange.documentconverter.errorCacheTimeoutSeconds=600

This value determines, how long an error, associated with a job hash value, is held within the error cache. If the timeout has not been reached, additional RemoteInternalPreviewService#getPreviewFor calls with the same job hash will instantly return with the cached error code instead of processing the job again.
 
Set to 0 to disable the error cache handling.
 
Default value: 0

; com.openexchange.documentconverter.errorCacheMaxCycleCount=5

This value determines the number of cycles, a job, associated with a job hash value, is added to the error cache.
One cycle starts after adding a job to the error cache and ends after the errorCacheTimeout has been reached.
After reaching the given maximum cycle count, the job is not removed from the error cache anymore and will be held within the error cache for the rest of the runtime of the current backend instance.
Since the error cache is not persistent, the cycle counter for each job hash is reset after a restart of the
backend instance.
 
Set to 0 to disable the error cache handling.
 
Default value: 5

; com.openexchange.documentconverter.servletLocalFileUrls=false

This item determines, if the documentconverter servlet should be allowed to handle file Urls of the form file://... The file Url itself is a resource that locates files that are locally accessible on the machine, the documentconverter backend is running on.
 
Default value: false

; com.openexchange.capability.sharepointconversion=false

Capability to enable the usage of a SharePoint conversion server; capability is only
checked, if a valid SharePoint remote converter has been configured appropriately
 
Default value: false

==== Handling of temporary files ====

The DocumentConverter server needs to store files at runtime for different purposes at different volume locations:

* '''Persistent files (Cache)''' The files that should last longer than the runtime of one converter instance are stored at the configurable ''com.openexchange.documentconverter.cacheDir'' directory. As the name of the property implies, such files are result cache entries used by multiple converter instances. This directory is monitored at runtime and all files are managed by the converter. Constraints for this directory are set via the converter properties ''com.openexchange.documentconverter.minFreeVolumeSizeMB'', ''com.openexchange.documentconverter.maxCacheSizeMB'', ''com.openexchange.documentconverter.maxCacheEntries'' and ''com.openexchange.documentconverter.cacheEntryTimeoutSeconds''.

* '''Medium lasting files''' These files are only valid for the runtime of one converter instance (e.g. ReaderEngine related runtime config files for each ReaderEngine instance). They are stored within the configurable ''com.openexchange.documentconverter.scratchDir'' directory. This directory is not constantly monitored at runtime but all files, contained in the ''${com.openexchange.documentconverter.scratchDir}/oxdc.tmp'' sub directory are managed by the converter during the startup and shutdown phase of one converter server instance. In this case, the whole ''${com.openexchange.documentconverter.scratchDir}/oxdc.tmp'' directory gets cleaned up during converter server shutdown as well as converter server startup. Initial cleanup during startup is necessary due to the fact, that the last converter instance might have aborted for unknown reasons, like e.g. power outage, VM abort etc.

* '''Short lasting files''' These files are stored within the Java VM specific I/O temporary directory, whose location is configurable via the Java VM system property ''java.io.tmpdir''. This directory is used by the converter to temporarily store request attachments in most cases. The files stored within this directory have a lifetime equal to the duration of the request itself. When the request has been finished, the appropriate files are cleaned up. For the converter, this means that e.g. source files to be converted and attached to the request are extracted from the request and stored in order to prevent exceeding memory consumption by source file buffers. When the conversion request is finished, the stored temporary file gets deleted.

'''From 7.10.2 on:''' The ''java.io.tmpdir'' Java system property specified directory will not be used by the converter anymore. Instead, even short living temporary files will be stored at the ''${com.openexchange.documentconverter.scratchDir}/oxdc.tmp'' location. By this change, even short living files will be stored inside this managed directory, so that a server shutdown/start cleans up this directory automatically. This change affects all files created by the converter implementation itself. Temporary files from other baseline bundles might still be stored within the configured ''java.io.tmpdir''.

;

AppSuite:ReaderEngineConfig

2019-03-22T13:39:11Z

Kai.ahrens: Adding section for handling of temporary files

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.

; com.openexchange.documentconverter.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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/opt/readerengine"

; com.openexchange.documentconverter.cacheDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.cache"

; com.openexchange.documentconverter.scratchDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.scratch"

; com.openexchange.documentconverter.errorDir=

This item specifies a directory for files that could not be loaded due to an error condition or due to a timeout.
 
'''Note:''' The used disk space will grow with retained files. Files have to be removed manually.
 
Default value: n/a

; com.openexchange.documentconverter.blacklistFile=/opt/open-xchange/etc/readerengine.blacklist

The list of external document content URLs that are not allowed to be loaded
by the readerengine after loading a document.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is first checked against the list of blacklist URL regular
expressions.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.blacklist"

; com.openexchange.documentconverter.whitelistFile=/opt/open-xchange/etc/readerengine.whitelist

The list of external document content URLs that are allowed to be loaded
by the readerengine after an external URL matched a blacklist pattern.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is only checked against the list of whitelist URL regular
expressions if it previously matched a pattern in the blacklist file.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.whitelist"

; com.openexchange.documentconverter.urlLinkLimit=200

The external URL link limit specifies the maximum amount of
valid external internet URLs (filtered by blacklist and whitelist before),
that are tried to get resolved by the engine when loading a document.
When this limit is reached, no more external internet URLs are resolved
for the current document.
 
'''Important:''' Please take note than one externally linked object within the document does not automatically correspond to one external URL call. In general, there are - at least - two URL calls necessary to display one externally linked object. Such additional calls are in most cases based on a format detection, happening prior to resolving the object data itself.
 
Set to -1 for no upper limit or to 0 to disable the resolving of internet URLs completely
 
Default value: 200

; com.openexchange.documentconverter.urlLinkProxy =

The external URL link proxy entry specifies a proxy server that is used by the readerengine
to resolve external links, contained within a document. Such links are e.g. external http://
graphic links, that are going to be resolved during the filtering process of a readerengine
instance.
Set this entry to the address of the proxy server: host:port
Recognized protocols are ''<nowiki>http://, https:// and ftp://</nowiki>''
Leave empty, if no proxy server should be used by the readerengine
 
Default value: n/a

; com.openexchange.documentconverter.RemoteBaseUrl =

Use a remote document conversion webservice to do the actual conversion;
Set this entry to the base URL of the remote host ''<nowiki>http://host[:port]/documentconverterPath</nowiki>'';
leave empty if conversion should happen on the local machine
 
Default value: n/a

'''From 7.8.2 on:''' The com.openexchange.documentconverter.RemoteBaseUrl is not valid for the documentconverter.properties file anymore.
The corresponding documentconverter server needs to be set on the Ox backend node, where the documentconverter-client package has been installed. The name of the new entry is ''<nowiki>com.openexchange.documentconverter.client.remoteDocumentConverterUrl</nowiki>''. The entry itself is located within the ''<nowiki>documentconverter-client.properties</nowiki>'' configuration file>

; com.openexchange.documentconverter.RemoteCacheUrls =

Use one or more remote converter cache(s) to speedup the conversion. The first entry, if set, is treated as the remote master cache, receiving cache updates from the local cache. Additional entries are treated as remote slave caches for read purposes only. 
Set the (whitespace separated) entries to the base URL('s) of the appropriate remote host(s): ''<nowiki>http://host[:port]/documentconverterCachePath</nowiki>'' 
Leave empty if only the local filesystem cache should be used
 
Default value: n/a


; com.openexchange.documentconverter.RemoteSharePointUrl =

Use a remote SharePoint service to do MSO to PDF conversions. 
Set this entry to the URL of the SharePoint host: ''<nowiki>http://host[:port]/_vti_bin/oxconvert.svc/mex?wsdl</nowiki>'' 
If left empty, the corresponding conversion job always returns false. 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointUsername =

The login user name to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointPassword =

The password to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.jobProcessorCount=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.
 
Default value: 3

; com.openexchange.documentconverter.jobRestartCount=50

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,
 
Default value: 50

; com.openexchange.documentconverter.jobExecutionTimeoutMilliseconds=60000

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

; com.openexchange.documentconverter.maxVMemMB=2048

This item determines the maximum size in megabytes (MB) of virtual memory that each started readerengine process is allowed to consume. If a job tries to consume more VMem than set via this config item, the processing of the current job for the appropriate readerengine process will be aborted and the underlying process is restarted to avoid memory corruption.
 
Set this value to -1 for no upper limit.
 
Default value: 2048

; com.openexchange.documentconverter.maxCacheSizeMB=-1

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.
 
Default value: -1

; com.openexchange.documentconverter.maxCacheEntries=-1

This item determines the maximum number of converter jobs cached at runtime. The value affects the amount of runtime job information to be cached as well as the number of file entries within the cache directory.
 
Set this value to -1 for no upper limit.
 
Default value: -1

; com.openexchange.documentconverter.cacheEntryTimeoutSeconds=2592000

This item determines the timeout in seconds, after which a cached job result is automatically removed from the cache.
 
Set this value to 0 to disable the timeout based removal of cached job results.
 
Default value: 2592000

; com.openexchange.documentconverter.enableCacheLookup=false

Setting this flag to true enables the caller of the RemoteInternalPreviewService#getCachedPreviewFor implementation (OfficePreviewService) to retrieve the cached only result of a previous conversion call, without scheduling a new job in case of a non existing cache entry, which might run for a long period time, up to the given job timeout time.
 
Set to false to disable the cache lookup within the RemoteInternalPreviewService#getCachedPreviewFor implementation.
 
Default value: false

; com.openexchange.documentconverter.errorCacheTimeoutSeconds=600

This value determines, how long an error, associated with a job hash value, is held within the error cache. If the timeout has not been reached, additional RemoteInternalPreviewService#getPreviewFor calls with the same job hash will instantly return with the cached error code instead of processing the job again.
 
Set to 0 to disable the error cache handling.
 
Default value: 0

; com.openexchange.documentconverter.errorCacheMaxCycleCount=5

This value determines the number of cycles, a job, associated with a job hash value, is added to the error cache.
One cycle starts after adding a job to the error cache and ends after the errorCacheTimeout has been reached.
After reaching the given maximum cycle count, the job is not removed from the error cache anymore and will be held within the error cache for the rest of the runtime of the current backend instance.
Since the error cache is not persistent, the cycle counter for each job hash is reset after a restart of the
backend instance.
 
Set to 0 to disable the error cache handling.
 
Default value: 5

; com.openexchange.documentconverter.servletLocalFileUrls=false

This item determines, if the documentconverter servlet should be allowed to handle file Urls of the form file://... The file Url itself is a resource that locates files that are locally accessible on the machine, the documentconverter backend is running on.
 
Default value: false

; com.openexchange.capability.sharepointconversion=false

Capability to enable the usage of a SharePoint conversion server; capability is only
checked, if a valid SharePoint remote converter has been configured appropriately
 
Default value: false

==== Handling of temporary files ====

The DocumentConverter server needs to store files at runtime for different purposes at different volume locations:

* '''Persistent files (Cache)''' The files that should last longer than the runtime of one converter instance are stored at the configurable ''com.openexchange.documentconverter.cacheDir'' directory. As the name of the property implies, such files are result cache entries used by multiple converter instances. This directory is monitored at runtime and all files are managed by the converter.

* '''Medium lasting files''' These files are only valid for the runtime of one converter instance (e.g. ReaderEngine related runtime config files for each ReaderEngine instance). They are stored within the configurable ''com.openexchange.documentconverter.scratchDir'' directory. This directory is not constantly monitored at runtime but all files, contained in the ''${com.openexchange.documentconverter.scratchDir}/oxdc.tmp'' sub directory are managed by the converter during the startup and shutdown phase of one converter server instance. In this case, the whole ''${com.openexchange.documentconverter.scratchDir}/oxdc.tmp'' directory gets cleaned up during converter server shutdown as well as converter server startup. Initial cleanup during startup is necessary due to the fact, that the last converter instance might have aborted for unknown reasons, like e.g. power outage, VM abort etc.

* '''Short lasting files''' These files are stored within the Java VM specific I/O temporary directory, whose location is configurable via the Java VM system property ''java.io.tmpdir''. This directory is used by the converter to temporarily store request attachments in most cases. The files stored within this directory have a lifetime equal to the duration of the request itself. When the request has been finished, the appropriate files are cleaned up. For the converter, this means that e.g. source files to be converted and attached to the request are extracted from the request and stored in order to prevent exceeding memory consumption by source file buffers. When the conversion request is finished, the stored temporary file gets deleted.

'''From 7.10.2 on:''' The ''java.io.tmpdir'' Java system property specified directory will not be used by the converter anymore. Instead, even short living temporary files will be stored at the ''${com.openexchange.documentconverter.scratchDir}/oxdc.tmp'' location. By this change, even short living files will be stored inside this managed directory, so that a server shutdown/start cleans up this directory automatically. This change affects all files created by the converter implementation itself. Temporary files from other baseline bundles might still be stored within the configured ''java.io.tmpdir''.

;

AppSuite:ImageConverter Install

2018-07-09T14:40:20Z

Kai.ahrens:

AppSuite:ImageConverter Install

2018-07-09T14:37:37Z

Kai.ahrens:

AppSuite:ImageConverter Install

2018-07-09T14:37:05Z

Kai.ahrens:

AppSuite:ImageConverter Install

2018-07-09T14:35:44Z

Kai.ahrens:

AppSuite:ImageConverter Install

2018-06-14T14:17:17Z

Kai.ahrens: /* Permissions */

AppSuite:ImageConverterMonitoring

2018-06-04T12:46:54Z

Kai.ahrens: /* OX Imageconverter */

= OX Imageconverter Monitoring =

== General ==

The Open-Xchange JMX offers the ability to fetch runtime information of the Java virtual machine, and about the Open-Xchange Middleware (aka groupware backend) including Imageconverter.

For general information about the JMX interface see: [[OX_monitoring_interface]]

The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]

Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]

== OX Imageconverter ==

Monitoring data for Imageconverter can be obtained after installation of the packages open-xchange-munin-scripts-jolokia and open-xchange-imageconverter-monitoring. It uses Jolokia if available and configured.

Here is a list of Imageconverter sample data provided by
<pre>
# /opt/open-xchange/sbin/showruntimestats --port 9995 -I
MedianKeyQueueTimeMillis_Background = 0
RequestCount_Total = 20
CacheHitRatio = 0.0
RequestCount_Get = 10
RequestCount_CacheAndGet = 10
RequestCount_Cache = 0
MedianKeyQueueTimeMillis_Instant = 0
CacheKeyCount = 9
RequestCount_Admin = 0
MedianRequestTimeMillis_Total = 0
MedianKeyQueueTimeMillis_Medium = 0
MedianKeyQueueTimeMillis_Total = 0
PeakKeyCountInQueue_Background = 0
PeakKeyCountInQueue_Medium = 0
PeakKeyCountInQueue_Instant = 0
MedianRequestTimeMillis_Get = 0
KeysProcessedCount = 10
CacheSize = 9670276
MedianKeyProcessTimeMillis = 466
MedianRequestTimeMillis_Admin = 0
MedianRequestTimeMillis_CacheAndGet = 0
MedianRequestTimeMillis_Cache = 0
</pre>

=== OX Imageconverter and munin ===

The Imageconverter uses a different port to provide monitoring data via Jolokia. The corresponding oxJolokiaURL has to be configured with an entry in the settings.

<pre>
[ox_imageconverter*]
env.oxJolokiaUrl http://localhost:8005/monitoring/jolokia
</pre>

== Further Reading ==

Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].

A call derived from this example for OX Imageconverter looks like

<pre>
$ curl http://yourname:yourpassword@localhost:8005/monitoring/jolokia/read/com.openexchange.imageconverter:name=ImageConverterMonitoring/CacheKeyCount
{"request":{"mbean":"com.openexchange.imageconverter:name=ImageConverterMonitoring","attribute":"CacheKeyCount","type":"read"},"value":232,"timestamp":1528111005,"status":200}
</pre>

AppSuite:ImageConverterMonitoring

2018-06-04T11:24:26Z

Kai.ahrens: /* OX Imageconverter */

= OX Imageconverter Monitoring =

== General ==

The Open-Xchange JMX offers the ability to fetch runtime information of the Java virtual machine, and about the Open-Xchange Middleware (aka groupware backend) including Imageconverter.

For general information about the JMX interface see: [[OX_monitoring_interface]]

The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]

Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]

== OX Imageconverter ==

Monitoring data for Imageconverter can be obtained after installation of the packages open-xchange-munin-scripts-jolokia and open-xchange-imageconverter-monitoring. It uses Jolokia if available and configured.

Here is a list of Imageconverter sample data provided by
<pre>
# /opt/open-xchange/sbin/showruntimestats --port 9995 -I
</pre>

=== OX Imageconverter and munin ===

The Imageconverter uses a different port to provide monitoring data via Jolokia. The corresponding oxJolokiaURL has to be configured with an entry in the settings.

<pre>
[ox_imageconverter*]
env.oxJolokiaUrl http://localhost:8005/monitoring/jolokia
</pre>

== Further Reading ==

Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].

A call derived from this example for OX Imageconverter looks like

<pre>
$ curl http://yourname:yourpassword@localhost:8005/monitoring/jolokia/read/com.openexchange.imageconverter:name=ImageConverterMonitoring/CacheKeyCount
{"request":{"mbean":"com.openexchange.imageconverter:name=ImageConverterMonitoring","attribute":"CacheKeyCount","type":"read"},"value":232,"timestamp":1528111005,"status":200}
</pre>

AppSuite:ImageConverterMonitoring

2018-06-04T11:22:09Z

Kai.ahrens:

AppSuite:ImageConverterMonitoring

2018-06-04T11:12:43Z

Kai.ahrens: /* OX Imageconverter */

AppSuite:ReaderEngineConfig

2016-07-11T16:14:54Z

Kai.ahrens:

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.

; com.openexchange.documentconverter.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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/opt/readerengine"

; com.openexchange.documentconverter.cacheDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.cache"

; com.openexchange.documentconverter.scratchDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.scratch"

; com.openexchange.documentconverter.errorDir=

This item specifies a directory for files that could not be loaded due to an error condition or due to a timeout.
 
'''Note:''' The used disk space will grow with retained files. Files have to be removed manually.
 
Default value: n/a

; com.openexchange.documentconverter.blacklistFile=/opt/open-xchange/etc/readerengine.blacklist

The list of external document content URLs that are not allowed to be loaded
by the readerengine after loading a document.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is first checked against the list of blacklist URL regular
expressions.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.blacklist"

; com.openexchange.documentconverter.whitelistFile=/opt/open-xchange/etc/readerengine.whitelist

The list of external document content URLs that are allowed to be loaded
by the readerengine after an external URL matched a blacklist pattern.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is only checked against the list of whitelist URL regular
expressions if it previously matched a pattern in the blacklist file.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.whitelist"

; com.openexchange.documentconverter.urlLinkLimit=200

The external URL link limit specifies the maximum amount of
valid external internet URLs (filtered by blacklist and whitelist before),
that are tried to get resolved by the engine when loading a document.
When this limit is reached, no more external internet URLs are resolved
for the current document.
 
'''Important:''' Please take note than one externally linked object within the document does not automatically correspond to one external URL call. In general, there are - at least - two URL calls necessary to display one externally linked object. Such additional calls are in most cases based on a format detection, happening prior to resolving the object data itself.
 
Set to -1 for no upper limit or to 0 to disable the resolving of internet URLs completely
 
Default value: 200

; com.openexchange.documentconverter.urlLinkProxy =

The external URL link proxy entry specifies a proxy server that is used by the readerengine
to resolve external links, contained within a document. Such links are e.g. external http://
graphic links, that are going to be resolved during the filtering process of a readerengine
instance.
Set this entry to the address of the proxy server: host:port
Recognized protocols are ''<nowiki>http://, https:// and ftp://</nowiki>''
Leave empty, if no proxy server should be used by the readerengine
 
Default value: n/a

; com.openexchange.documentconverter.RemoteBaseUrl =

Use a remote document conversion webservice to do the actual conversion;
Set this entry to the base URL of the remote host ''<nowiki>http://host[:port]/documentconverterPath</nowiki>'';
leave empty if conversion should happen on the local machine
 
Default value: n/a

'''From 7.8.2 on:''' The com.openexchange.documentconverter.RemoteBaseUrl is not valid for the documentconverter.properties file anymore.
The corresponding documentconverter server needs to be set on the Ox backend node, where the documentconverter-client package has been installed. The name of the new entry is ''<nowiki>com.openexchange.documentconverter.client.remoteDocumentConverterUrl</nowiki>''. The entry itself is located within the ''<nowiki>documentconverter-client.properties</nowiki>'' configuration file>

; com.openexchange.documentconverter.RemoteCacheUrls =

Use one or more remote converter cache(s) to speedup the conversion. The first entry, if set, is treated as the remote master cache, receiving cache updates from the local cache. Additional entries are treated as remote slave caches for read purposes only. 
Set the (whitespace separated) entries to the base URL('s) of the appropriate remote host(s): ''<nowiki>http://host[:port]/documentconverterCachePath</nowiki>'' 
Leave empty if only the local filesystem cache should be used
 
Default value: n/a


; com.openexchange.documentconverter.RemoteSharePointUrl =

Use a remote SharePoint service to do MSO to PDF conversions. 
Set this entry to the URL of the SharePoint host: ''<nowiki>http://host[:port]/_vti_bin/oxconvert.svc/mex?wsdl</nowiki>'' 
If left empty, the corresponding conversion job always returns false. 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointUsername =

The login user name to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointPassword =

The password to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.jobProcessorCount=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.
 
Default value: 3

; com.openexchange.documentconverter.jobRestartCount=50

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,
 
Default value: 50

; com.openexchange.documentconverter.jobExecutionTimeoutMilliseconds=60000

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

; com.openexchange.documentconverter.maxVMemMB=2048

This item determines the maximum size in megabytes (MB) of virtual memory that each started readerengine process is allowed to consume. If a job tries to consume more VMem than set via this config item, the processing of the current job for the appropriate readerengine process will be aborted and the underlying process is restarted to avoid memory corruption.
 
Set this value to -1 for no upper limit.
 
Default value: 2048

; com.openexchange.documentconverter.maxCacheSizeMB=-1

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.
 
Default value: -1

; com.openexchange.documentconverter.maxCacheEntries=-1

This item determines the maximum number of converter jobs cached at runtime. The value affects the amount of runtime job information to be cached as well as the number of file entries within the cache directory.
 
Set this value to -1 for no upper limit.
 
Default value: -1

; com.openexchange.documentconverter.cacheEntryTimeoutSeconds=2592000

This item determines the timeout in seconds, after which a cached job result is automatically removed from the cache.
 
Set this value to 0 to disable the timeout based removal of cached job results.
 
Default value: 2592000

; com.openexchange.documentconverter.enableCacheLookup=false

Setting this flag to true enables the caller of the RemoteInternalPreviewService#getCachedPreviewFor implementation (OfficePreviewService) to retrieve the cached only result of a previous conversion call, without scheduling a new job in case of a non existing cache entry, which might run for a long period time, up to the given job timeout time.
 
Set to false to disable the cache lookup within the RemoteInternalPreviewService#getCachedPreviewFor implementation.
 
Default value: false

; com.openexchange.documentconverter.errorCacheTimeoutSeconds=600

This value determines, how long an error, associated with a job hash value, is held within the error cache. If the timeout has not been reached, additional RemoteInternalPreviewService#getPreviewFor calls with the same job hash will instantly return with the cached error code instead of processing the job again.
 
Set to 0 to disable the error cache handling.
 
Default value: 0

; com.openexchange.documentconverter.errorCacheMaxCycleCount=5

This value determines the number of cycles, a job, associated with a job hash value, is added to the error cache.
One cycle starts after adding a job to the error cache and ends after the errorCacheTimeout has been reached.
After reaching the given maximum cycle count, the job is not removed from the error cache anymore and will be held within the error cache for the rest of the runtime of the current backend instance.
Since the error cache is not persistent, the cycle counter for each job hash is reset after a restart of the
backend instance.
 
Set to 0 to disable the error cache handling.
 
Default value: 5

; com.openexchange.documentconverter.servletLocalFileUrls=false

This item determines, if the documentconverter servlet should be allowed to handle file Urls of the form file://... The file Url itself is a resource that locates files that are locally accessible on the machine, the documentconverter backend is running on.
 
Default value: false

; com.openexchange.capability.sharepointconversion=false

Capability to enable the usage of a SharePoint conversion server; capability is only
checked, if a valid SharePoint remote converter has been configured appropriately
 
Default value: false

;

AppSuite:DocumentConverter Installation Guide

2016-07-11T16:09:18Z

Kai.ahrens: /* Setup And Best Practices 7.8.2*/

= 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 behavior 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 Service allows customers the flexible integration of document conversion in their offering.

The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.

== Requirements ==

OX Document Converter requires a 64bit systems; 32bit systems are not supported. 
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.

== Update to 7.8.2 ==

'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].

Details for deployments from 7.8.2 on can be found within the articles itself.

== Download and Installation ==

The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.

=== ReaderEngine ===

See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]

=== Server ===

See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]

See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]

See [[AppSuite:DocumentConverterWSInstall|Document converter Webservice instructions]]

=== Configuration ===

After deployment of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.

In order to enable users to use the functionality, they must be given the appropriate permission, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].

The component readerengine works with the default configuration.
The settings are in the file '''documentconverter.properties'''
located in the directory "/opt/open-xchange/etc" as described below.

{{AppSuite:ReaderEngineConfig}}



== Setup And Best Practices ==

The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.

=== Readerengine ===
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.

The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.

=== PDF2SVG ===
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.

=== Documentconverter OSGi bundles ===
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.

After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.

==== Documentconverter system packages ====
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):

===== Deployments until 7.8.1 =====
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend.

===== Deployments from 7.8.2 on =====

* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.
* '''documentconverter-jolokia''' This bundle is the same as in pre 7.8.2 releases and needs to be installed on the documentconverter server side.

=== General ===
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed are the '''documentconverter-api''' and the '''documentconverter (until 7.8.1)''' / '''documentconverter-client (from 7.8.2 on)''' packages.

If the current OX backend node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.

In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.

'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''documentconverter-webservice''' package needs to be installed beside the '''documentconverter-api''', the
'''documentconverter''', the '''readerengine''' and the the '''readerengine-pdf2svg''' packages.

The '''documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''documentconverter-server''' package needs to be installed beside the '''documentconverter-api''', the '''readerengine''' and the the '''readerengine-pdf2svg''' packages.

The '''documentconverter-jolokia''' package only makes sense to be installed on an OX documentconverter-server node, that acts as ''real'' converter node.

In summary, the following packages must be installed in order to act as a real converter node:

open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database

The package open-xchange-authentication-database is just needed to fulfill the dependencies.

=== Single OX backend with documentconverter / Single converter node ===
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).

The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.

'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.

Documentconversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.

So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversionAttention: this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice). hardware available.

=== Configuration and Hardware ===
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.

'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.

In addition, you should check the following entries for their validity/sensibility:

* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.
* The upper limit for the Java VM memory allocation should not be below 2048MB (-Xmx2048m). Please adjust this value accordingly, but don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests.

=== OX backend(s) with one remote documentconverter ===
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.

'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''documentconverter-api''' and the '''documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.

For the remote converter node, the '''documentconverter-webservice''' package needs to be installed beside the '''documentconverter-api''', '''documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws
</blockquote>

No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the documentconverter-api and the documentconverter-client packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.

For the remote converter node (webservice), the '''documentconverter-server''' package needs to be installed beside the '''documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.

There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.

In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\

<blockquote>
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws
</blockquote>

In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.

=== OX backend cluster with one remote documentconverter ===
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.

The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:

<blockquote>
<Proxy /documentconverterws> 
ProxyPass balancer://oxcluster/documentconverterws 
<proxy> 
</blockquote>

=== Sample cluster installation ===

A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).

=== OX backend cluster with two or more documentconverters ===
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.

In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.

A typical Proxy configuration with proper stickysession handling looks as follows:

<blockquote>
<Proxy balancer://oxcluster> 
Order deny,allow 
Allow from all 
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2 
ProxySet stickysession=JSESSIONID 
SetEnv proxy-initial-not-pooled 
SetEnv proxy-sendchunked 
</Proxy> 
</blockquote>

'''Deployments from 7.8.2 on''' Since the Ox backend and the dedicated Ox Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment.

=== Remote caching with two or more documentconverters ===
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.

In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.

The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.

The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:

<blockquote>
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache
</blockquote>

In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.

If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.

If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).

=== Sharepoint support ===

It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.

No OX user credentials are needed on the Sharepoint server, as shown in this overview:

[[File:OX_Document_Converter_Overview.jpg]]

AppSuite:DocumentConverter Installation Guide

2016-07-11T15:27:49Z

Kai.ahrens: /* Documentconverter system packages 7.8.2*/

AppSuite:ReaderEngineConfig

2016-07-11T15:21:24Z

Kai.ahrens: Changed for 7.8.2

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.

; com.openexchange.documentconverter.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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/opt/readerengine"

; com.openexchange.documentconverter.cacheDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.cache"

; com.openexchange.documentconverter.scratchDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.scratch"

; com.openexchange.documentconverter.errorDir=

This item specifies a directory for files that could not be loaded due to an error condition or due to a timeout.
 
'''Note:''' The used disk space will grow with retained files. Files have to be removed manually.
 
Default value: n/a

; com.openexchange.documentconverter.blacklistFile=/opt/open-xchange/etc/readerengine.blacklist

The list of external document content URLs that are not allowed to be loaded
by the readerengine after loading a document.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is first checked against the list of blacklist URL regular
expressions.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.blacklist"

; com.openexchange.documentconverter.whitelistFile=/opt/open-xchange/etc/readerengine.whitelist

The list of external document content URLs that are allowed to be loaded
by the readerengine after an external URL matched a blacklist pattern.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is only checked against the list of whitelist URL regular
expressions if it previously matched a pattern in the blacklist file.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.whitelist"

; com.openexchange.documentconverter.urlLinkLimit=200

The external URL link limit specifies the maximum amount of
valid external internet URLs (filtered by blacklist and whitelist before),
that are tried to get resolved by the engine when loading a document.
When this limit is reached, no more external internet URLs are resolved
for the current document.
 
'''Important:''' Please take note than one externally linked object within the document does not automatically correspond to one external URL call. In general, there are - at least - two URL calls necessary to display one externally linked object. Such additional calls are in most cases based on a format detection, happening prior to resolving the object data itself.
 
Set to -1 for no upper limit or to 0 to disable the resolving of internet URLs completely
 
Default value: 200

; com.openexchange.documentconverter.urlLinkProxy =

The external URL link proxy entry specifies a proxy server that is used by the readerengine
to resolve external links, contained within a document. Such links are e.g. external http://
graphic links, that are going to be resolved during the filtering process of a readerengine
instance.
Set this entry to the address of the proxy server: host:port
Recognized protocols are ''<nowiki>http://, https:// and ftp://</nowiki>''
Leave empty, if no proxy server should be used by the readerengine
 
Default value: n/a

; com.openexchange.documentconverter.RemoteBaseUrl =

Use a remote document conversion webservice to do the actual conversion;
Set this entry to the base URL of the remote host ''<nowiki>http://host[:port]/documentconverterPath</nowiki>'';
leave empty if conversion should happen on the local machine
 
Default value: n/a

'''From 7.8.2 on:''' The com.openexchange.documentconverter.RemoteBaseUrl is not valid for the documentconverter.properties file anymore.
The corresponding documentconverter server needs to be set on the Ox backend node, where the documentconverter-client package has been installed. The name of the new entry is ''<nowiki>com.openexchange.documentconverter.client.remoteDocumentConverterUrl</nowiki>''. The entry itself is located within the ''<nowiki>documentconverter-client.properties</nowiki>'' configuration file>

; com.openexchange.documentconverter.RemoteCacheUrls =

Use one or more remote converter cache(s) to speedup the conversion. The first entry, if set, is treated as the remote master cache, receiving cache updates from the local cache. Additional entries are treated as remote slave caches for read purposes only. 
Set the (whitespace separated) entries to the base URL('s) of the appropriate remote host(s): ''<nowiki>http://host[:port]/documentconverterCachePath</nowiki>'' 
Leave empty if only the local filesystem cache should be used
 
Default value: n/a


; com.openexchange.documentconverter.RemoteSharePointUrl =

Use a remote SharePoint service to do MSO to PDF conversions. 
Set this entry to the URL of the SharePoint host: ''<nowiki>http://host[:port]/_vti_bin/oxconvert.svc/mex?wsdl</nowiki>'' 
If left empty, the corresponding conversion job always returns false. 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointUsername =

The login user name to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.RemoteSharePointPassword =

The password to be used for calls to the SharePoint service 
Default value: n/a

; com.openexchange.documentconverter.jobProcessorCount=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.
 
Default value: 3

; com.openexchange.documentconverter.jobRestartCount=50

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,
 
Default value: 50

; com.openexchange.documentconverter.jobExecutionTimeoutMilliseconds=60000

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

; com.openexchange.documentconverter.maxVMemMB=2048

This item determines the maximum size in megabytes (MB) of virtual memory that each started readerengine process is allowed to consume. If a job tries to consume more VMem than set via this config item, the processing of the current job for the appropriate readerengine process will be aborted and the underlying process is restarted to avoid memory corruption.
 
Set this value to -1 for no upper limit.
 
Default value: 2048

; com.openexchange.documentconverter.maxCacheSizeMB=-1

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.
 
Default value: -1

; com.openexchange.documentconverter.maxCacheEntries=-1

This item determines the maximum number of converter jobs cached at runtime. The value affects the amount of runtime job information to be cached as well as the number of file entries within the cache directory.
 
Set this value to -1 for no upper limit.
 
Default value: -1

; com.openexchange.documentconverter.cacheEntryTimeoutSeconds=2592000

This item determines the timeout in seconds, after which a cached job result is automatically removed from the cache.
 
Set this value to 0 to disable the timeout based removal of cached job results.
 
Default value: 2592000

; com.openexchange.documentconverter.enableCacheLookup=false

Setting this flag to true enables the caller of the RemoteInternalPreviewService#getCachedPreviewFor implementation (OfficePreviewService) to retrieve the cached only result of a previous conversion call, without scheduling a new job in case of a non existing cache entry, which might run for a long period time, up to the given job timeout time.
 
Set to false to disable the cache lookup within the RemoteInternalPreviewService#getCachedPreviewFor implementation.
 
Default value: false

; com.openexchange.documentconverter.errorCacheTimeoutSeconds=600

This value determines, how long an error, associated with a job hash value, is held within the error cache. If the timeout has not been reached, additional RemoteInternalPreviewService#getPreviewFor calls with the same job hash will instantly return with the cached error code instead of processing the job again.
 
Set to 0 to disable the error cache handling.
 
Default value: 0

; com.openexchange.documentconverter.errorCacheMaxCycleCount=5

This value determines the number of cycles, a job, associated with a job hash value, is added to the error cache.
One cycle starts after adding a job to the error cache and ends after the errorCacheTimeout has been reached.
After reaching the given maximum cycle count, the job is not removed from the error cache anymore and will be held within the error cache for the rest of the runtime of the current backend instance.
Since the error cache is not persistent, the cycle counter for each job hash is reset after a restart of the
backend instance.
 
Set to 0 to disable the error cache handling.
 
Default value: 5

; com.openexchange.documentconverter.servletLocalFileUrls=false

This item determines, if the documentconverter servlet should be allowed to handle file Urls of the form file://... The file Url itself is a resource that locates files that are locally accessible on the machine, the documentconverter backend is running on.
 
Default value: false

; com.openexchange.capability.sharepointconversion=false

Capability to enable the usage of a SharePoint conversion server; capability is only
checked, if a valid SharePoint remote converter has been configured appropriately
 
Default value: false

;

AppSuite:DocumentConverter Installation Guide

2016-07-11T15:11:41Z

Kai.ahrens: /* Update to 7.8.2 */

AppSuite:ReaderEngineConfig

2014-11-17T16:22:48Z

Kai.ahrens: Added com.openexchange.documentconverter.errorCacheMaxCycleCount

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.

; com.openexchange.documentconverter.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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/opt/readerengine"

; com.openexchange.documentconverter.cacheDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.cache"

; com.openexchange.documentconverter.scratchDir=/var/spool/open-xchange/documentconverter/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.
 
'''VERY IMPORTANT:''' If not set correctly, the complete web service will be nonfunctional.
 
Default value: "/var/spool/open-xchange/documentconverter/readerengine.scratch"

; com.openexchange.documentconverter.errorDir=

The temporary directory, containing files that could not be loaded due to an error condition or due to a timeout
 
Default value: n/a

; com.openexchange.documentconverter.blacklistFile=/opt/open-xchange/etc/readerengine.blacklist

The list of external document content URLs that are not allowed to be loaded
by the readerengine after loading a document.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is first checked against the list of blacklist URL regular
expressions.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.blacklist"

; com.openexchange.documentconverter.whitelistFile=/opt/open-xchange/etc/readerengine.whitelist

The list of external document content URLs that are allowed to be loaded
by the readerengine after an external URL matched a blacklist pattern.
The file itself contains a list of (newline separated) regular expressions.
Each external URL is only checked against the list of whitelist URL regular
expressions if it previously matched a pattern in the blacklist file.
If the external URL matches one blacklist entry, the external URL is
then checked against the list of whitelist URL regular expressions.
The behavior in summary is as follows:
If the URL is not blacklisted and not whitelisted, it is resolved at runtime.
If the URL is blacklisted but not whitelisted, it is not resolved at runtime.
If the URL is not blacklisted but whitelisted, it is resolved at runtime.
If the URL is blacklisted and whitelisted, it is resolved at runtime.
In boolean notation: valid = (!blacklisted) || whitelisted
Please note that the regular expressions need to fully qualify the patterns that
the URL should be checked against.
Upper/Lower cases need to be handled by the regular expression as well.
The file itself needs to be UTF-8 encoded to be read appropriately.
 
Default value: "/opt/open-xchange/etc/readerengine.whitelist"

; com.openexchange.documentconverter.urlLinkLimit=200

The external URL link limit specifies the maximum amount of
valid external internet URLs (filtered by blacklist and whitelist before),
that are tried to get resolved by the engine when loading a document.
When this limit is reached, no more external internet URLs are resolved
for the current document.
 
'''Important:''' Please take note than one externally linked object within the document does not automatically correspond to one external URL call. In general, there are - at least - two URL calls necessary to display one externally linked object. Such additional calls are in most cases based on a format detection, happening prior to resolving the object data itself.
 
Set to -1 for no upper limit or to 0 to disable the resolving of internet URLs completely
 
Default value: 200

; com.openexchange.documentconverter.urlLinkProxy =

The external URL link proxy entry specifies a proxy server that is used by the readerengine
to resolve external links, contained within a document. Such links are e.g. external http://
graphic links, that are going to be resolved during the filtering process of a readerengine
instance.
Set this entry to the address of the proxy server: host:port
Recognized protocols are http://, https:// and ftp://
Leave empty, if no proxy server should be used by the readerengine
 
Default value: n/a

; com.openexchange.documentconverter.RemoteBaseUrl =

Use a remote document conversion webservice to do the actual conversion;
Set this entry to the base URL of the remote host http://host[:port]/documentconverterPath;
leave empty if conversion should happen on the local machine
 
Default value: n/a


; com.openexchange.documentconverter.jobProcessorCount=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.
 
Default value: 3

; com.openexchange.documentconverter.jobRestartCount=50

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,
 
Default value: 50

; com.openexchange.documentconverter.jobExecutionTimeoutMilliseconds=60000

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

; com.openexchange.documentconverter.maxVMemMB=2048

This item determines the maximum size in megabytes (MB) of virtual memory that each started readerengine process is allowed to consume. If a job tries to consume more VMem than set via this config item, the processing of the current job for the appropriate readerengine process will be aborted and the underlying process is restarted to avoid memory corruption.
 
Set this value to -1 for no upper limit.
 
Default value: 2048

; com.openexchange.documentconverter.maxCacheSizeMB=-1

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.
 
Default value: -1

; com.openexchange.documentconverter.maxCacheEntries=-1

This item determines the maximum number of converter jobs cached at runtime. The value affects the amount of runtime job information to be cached as well as the number of file entries within the cache directory.
 
Set this value to -1 for no upper limit.
 
Default value: -1

; com.openexchange.documentconverter.cacheEntryTimeoutSeconds=2592000

This item determines the timeout in seconds, after which a cached job result is automatically removed from the cache.
 
Set this value to 0 to disable the timeout based removal of cached job results.
 
Default value: 2592000

; com.openexchange.documentconverter.enableCacheLookup=false

Setting this flag to true enables the caller of the RemoteInternalPreviewService#getCachedPreviewFor implementation (OfficePreviewService) to retrieve the cached only result of a previous conversion call, without scheduling a new job in case of a non existing cache entry, which might run for a long period time, up to the given job timeout time.
 
Set to false to disable the cache lookup within the RemoteInternalPreviewService#getCachedPreviewFor implementation.
 
Default value: false

; com.openexchange.documentconverter.errorCacheTimeoutSeconds=0

This value determines, how long an error, associated with a job hash value, is held within the error cache. If the timeout has not been reached, additional RemoteInternalPreviewService#getPreviewFor calls with the same job hash will instantly return with the cached error code instead of processing the job again.
 
Set to 0 to disable the error cache handling.
 
Default value: 0

; com.openexchange.documentconverter.errorCacheMaxCycleCount=5

This value determines the number of cycles, a job, associated with a job hash value, is added to the error cache.
One cycle starts after adding a job to the error cache and ends after the errorCacheTimeout has been reached.
After reaching the given maximum cycle count, the job is not removed from the error cache anymore and will be held within the error cache for the rest of the runtime of the current backend instance.
Since the error cache is not persistent, the cycle counter for each job hash is reset after a restart of the
backend instance.
 
Set to 0 to disable the error cache handling.
 
Default value: 5

; com.openexchange.documentconverter.servletLocalFileUrls=false

This item determines, if the documentconverter servlet should be allowed to handle file Urls of the form file://... The file Url itself is a resource that locates files that are locally accessible on the machine, the documentconverter backend is running on.
 
Default value: false

; com.openexchange.capability.sharepointconversion=false

Capability to enable the usage of a SharePoint conversion server; capability is only
checked, if a valid SharePoint remote converter has been configured appropriately
 
Default value: false

AppSuite:ReaderEngineConfig

2014-10-16T15:54:12Z

Kai.ahrens: Added note for multiple external URL calls per object

AppSuite:ReaderEngineConfig

2014-10-16T15:43:33Z

Kai.ahrens: Added enableCacheLookup and errorCacheTimeoutSeconds config item descriptions