AppSuite:Documents Installation Guide

This information is valid from 7.10.3

For earlier versions see Guide for 7.10.2

Download & Installation OX Documents v7

General Information

OX Documents v7 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 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 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 open-xchange-documents-backend and open-xchange-documents-ui. The open-xchange-documents-backend package also requires and installs these packages:

• open-xchange-file-distribution
• open-xchange-sessionstorage-hazelcast

The following Packages are no longer needed since 7.10.3

• open-xchange-realtime-core
• open-xchange-realtime-json

Furthermore all open-xchange-realtime-* packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

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

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

Redhat Enterprise Linux 7 or CentOS 7

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

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

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

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

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

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

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

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

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

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

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

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

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

Redhat Enterprise Linux 8

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

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

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

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

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

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

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

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

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

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

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

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

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

Debian GNU/Linux 11.0 (valid from v7.10.6)

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

deb https://software.open-xchange.com/products/appsuite/stable/office/DebianBullseye /
deb https://software.open-xchange.com/products/appsuite/stable/office-web/DebianBullseye /
deb https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/DebianBullseye /
deb https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/DebianBullseye /
deb https://software.open-xchange.com/products/appsuite/stable/spellcheck/DebianBullseye /

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

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/DebianBullseye /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/DebianBullseye /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/DebianBullseye /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/updates/DebianBullseye /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/spellcheck/updates/DebianBullseye /

$ 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 12.0 (valid from v7.10.6)

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

deb https://software.open-xchange.com/products/appsuite/stable/office/DebianBookworm /
deb https://software.open-xchange.com/products/appsuite/stable/office-web/DebianBookworm /
deb https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/DebianBookworm /
deb https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/DebianBookworm /
deb https://software.open-xchange.com/products/appsuite/stable/spellcheck/DebianBookworm /

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

deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/DebianBookworm /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/DebianBookworm /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/DebianBookworm /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/updates/DebianBookworm /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/spellcheck/updates/DebianBookworm /

$ 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

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. One DCS cluster is always tied to one Hazelcast cluster of Middleware nodes. 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:

open-xchange-documents-collaboration

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 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

dcs.host = 192.168.10.25       # Interface of the DCS node
dcs.port = 61616

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 advertiseURL can be set to the name of the DCS node.

dcs.advertiseURL=dcs.example.com:61616

Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like

192.168.10.25 dcs.example.com

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:

db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password

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:

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

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:

sudo systemctl start open-xchange-documents-collaboration.service

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.

# 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 |
+---------------------+---------------+---------------+---------+

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

jmx.enabled=true

SSL configuration

The DCS supports to secure the network traffic between DCS nodes and between DCS and middleware nodes using Java key- and truststore files. SSL support has to be enabled by using the config item:

dcs.usessl=true

If the optional config item advertiseURL is used it has to be adapted by adding the protocol part ssl which also reflects the secure connection. E.g.

dcs.advertiseURL=ssl://dcs.example.com:61616

For security reasons it's recommended to enable host name verification for SSL connections. If you enable this option, you have to configure dcs.host or dcs.advertiseURL with a valid host name including the domain which is bound to your certificate you want to use. If you prefer to use IP addresses, you have to use the default false for verifyHostname.

dcs.ssl.verifyHostname=true

Enabling SSL needs valid certificates which must be provided via key- and optional truststore. The DCS expects that you provide the path to the key- and truststore files with the following config items.

dcs.ssl.server.keystore.path=/opt/open-xchange/etc/example-broker.ks

You have to provide the password for the keystore which you have set while creating the keystore.

dcs.ssl.server.keystore.password=my-ks-password

If you use a truststore you have to provide the path to the file, too.

dcs.ssl.server.truststore.path=/opt/open-xchange/etc/example-broker.ts

The truststore is also secured with a password which must be provided by the config item:

dcs.ssl.server.truststore.password=my-ts-password

Every DCS node is also a client which connects to other DCS nodes. Therefore the DCS needs valid certificates for this client connection, too. You can re-use the server key- and truststore for the client connection, but it also possible to provide different key- and truststore files.

dcs.ssl.client.keystore.path=/opt/open-xchange/etc/example-client.ks
dcs.ssl.client.keystore.password=my-ks-password

If you use a truststore you have to provide the path to the file, too. The truststore is also secured with a password which must be provided by a config item.

dcs.ssl.client.truststore.path=/opt/open-xchange/etc/example-client.ts
dcs.ssl.client.truststore.password=my-ts-password

Middleware node

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):

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

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

$ /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 |
+---------------------+---------------+---------------+---------+

SSL configuration

If you enable SSL connections for your DCS nodes you also have to configure the DCS client on the middleware side, otherwise the DCS client won't be able to connect to any DCS node. The configuration for the SSL properties is also located in the configuration file /opt/open-xchange/etc/documents-collaboration-client.properties.

To enable SSL connections for the DCS client the following config must be set to true.

com.openexchange.dcs.client.ssl.enabled=true

For security reasons it's recommended to enable host name verification for SSL connections. If you enable this option, you have to configure the DCS nodes with a valid host name including the domain which is bound to your server certificate you want to use. If you prefer to use IP addresses, you have to use the default value false for verifyHostname.

com.openexchange.dcs.client.ssl.verifyHostname=true

The DCS client also needs key- and optional truststore config items to be set.

com.openexchange.dcs.client.ssl.keystore.path=/opt/open-xchange/etc/example-client.ks
com.openexchange.dcs.client.ssl.keystore.password=my-ks-password
com.openexchange.dcs.client.ssl.truststore.path=/opt/open-xchange/etc/example-client.ts
com.openexchange.dcs.client.ssl.truststore.password=my-ts-password

Note:
Please keep in mind that mixed setups of SSL and non-SSL configured DCS nodes or DCS clients (Middleware nodes) are not supported.

Apache configuration

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

The Apache module proxy_wstunnel has to be enabled:

sudo a2enmod proxy_wstunnel

and the the following entries need to be added to the Apache configuration:

<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

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 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 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:

# 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

The following line enables the functionality:

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

Starting with 7.6.2, you can disable the text portal app. In permissions.properties:

permissions=textportaldisabled

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

# 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

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.

com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003

Spell Checking

By default Spellchecking is enabled in /opt/open-xchange/etc/settings/office.properties with the following entry

# 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

Integrated Functionality valid up to and including 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:

# 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

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.

Separate Service valid from 7.10.4 on

Prepare spellcheck repository as described above.

The SpellCheck service will be installed via the package:

open-xchange-spellcheck

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.

29582 29582 29582 ?        00:00:00   oxspell
29583 29582 29582 ?        00:00:02   |-oxspell

The SpellCheck service configuration file is located at /opt/open-xchange/spellcheck/etc/spellcheck.properties. All available configuration items are described on this 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.

com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell

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 configuration entry needs to be reviewed and the value may need adjustment during installation in case the SpellCheck service runs on a different node than the accessing Documents middleware node.
The entry specifies the range of addresses the SpellCheck service is accepting client connections from. The default of 127.0.0.1 restricts connections to be established from localhost clients only. Use 0.0.0.0 to allow connections from any client address.

com.openexchange.spellcheck.listenAddress = 0.0.0.0

If the default listening port 8003 doesn't fit your needs the following property needs to be set.

com.openexchange.spellcheck.port=4711

The Spellcheck service is used by OX App Suite Middleware nodes (running OX Documents) only. No support for external connections is required (e.g. from browsers run by users). The service itself does not actively start any connections. It is stateless and agnostic to contexts, tenants, ...

SpellCheck Service Transport Security

By default the SpellCheck service accepts HTTP connections. For production environments the HTTPS secured transport could be enabled and the appropriate host related certificate files should be specified via the following configuration properties.

com.openexchange.spellcheck.ssl.enable=true
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile

Sizing and performance

Requests are submitted from the OX App Suite Middleware to the SpellCheck service when a user opens an existing document or she enters text. The processing of these requests is CPU-bound, i.e. CPU-usage is limited by the configured number of available threads. By default the service is configured to use 3 threads

com.openexchange.spellcheck.threadCount = 3

A heavily used service thus would consume 3 CPU cores.

Depending on your requirements you may want to reduce CPU usage by decreasing the threadCount (on a shared node). Or you can strengthen the service (on a dedicated node) by increasing the value. threadCount should not exceed the maximum number of cores - 1.

Performance tests show that the service can handle a throughput of about 20-25 requests/s per thread (and thus per dedicated core). You will notice a degraded service by hitting this upper limit. You may want to monitor the metrics

RequestCount{httpRequestCount_total="total"}
ServerStatus{property="requestTimeout"}

Additionally the ratio of

RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}
RequestCount{method="check-paragraph-spelling",statusCode="200"}

will show whether more than about 90% spelling requests are handled within 2 seconds as expected.

The runtime memory consumption for loading/unloading and accessing dictionaries depends on the locales in use. A maximum virtual memory allocation limit is specified via systemd service variables within the systemd unit file /lib/systemd/system/open-xchange-spellcheck.service. The defaults of LimitRSS=1500M and LimitAS=1500M are sufficient for a standard deployment containing several western languages/locales as well as e.g. one or two Asian languages/locales. If the SpellCheck service logs std::bad_alloc exceptions you may want to increase these values in steps of 200M (Megabytes) depending on the demands of the deployment.

Spellcheck Service Monitoring

The SpellCheck service internally sThe runtime memory consumption for loading and accessing such a dictionary depends on the locale currently used atarts a Prometheus service in parallel to allow the administrator to get access to runtime metrics 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.

com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0
com.openexchange.spellcheck.port.metrics=8002

Besides using a Prometheus system to constantly gather metrics, the current values can be retrieved with the following call.

curl localhost:8002/metrics

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

# 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

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

/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

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.

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 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

# Override certain settings
default:
    host: all
    openInSingleTab: true