https://www.oxpedia.org/wiki/api.php?action=feedcontributions&user=Stx12&feedformat=atomOpen-Xchange - User contributions [en]2024-03-29T06:31:19ZUser contributionsMediaWiki 1.31.0https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentAutomation&diff=26834AppSuite:DocumentAutomation2022-03-16T10:07:09Z<p>Stx12: Blanked the page</p>
<hr />
<div></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=26572AppSuite:Documents Installation Guide2021-12-08T20:34:24Z<p>Stx12: add note that SSL mixed mode is not supported</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
<!-- === Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.''' --><br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
<!-- === SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration --><br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
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.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
====SSL configuration====<br />
<br />
The DCS supports to secure the network traffic between DCS nodes and between DCS and middleware nodes using Java key- and truststore files.<br />
SSL support has to be enabled by using the config item:<br />
<pre><br />
dcs.usessl=true<br />
</pre><br />
<br />
If the optional config item <tt>advertiseURL</tt> is used it has to be adapted by adding the protocol part '''ssl''' which also reflects the secure connection. E.g.<br />
<pre><br />
dcs.advertiseURL=ssl://dcs.example.com:61616<br />
</pre><br />
<br />
For security reasons it's recommended to enable host name verification for SSL connections. If you enable this option, you have to configure <tt>dcs.host</tt> or <tt>dcs.advertiseURL</tt> 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.<br />
<pre><br />
dcs.ssl.verifyHostname=true<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.server.keystore.path=/opt/open-xchange/etc/example-broker.ks<br />
</pre><br />
<br />
You have to provide the password for the keystore which you have set while creating the keystore.<br />
<pre><br />
dcs.ssl.server.keystore.password=my-ks-password<br />
</pre><br />
<br />
If you use a truststore you have to provide the path to the file, too.<br />
<pre><br />
dcs.ssl.server.truststore.path=/opt/open-xchange/etc/example-broker.ts<br />
</pre><br />
<br />
The truststore is also secured with a password which must be provided by the config item:<br />
<pre><br />
dcs.ssl.server.truststore.password=my-ts-password<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.client.keystore.path=/opt/open-xchange/etc/example-client.ks<br />
dcs.ssl.client.keystore.password=my-ks-password<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.client.truststore.path=/opt/open-xchange/etc/example-client.ts<br />
dcs.ssl.client.truststore.password=my-ts-password<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
====SSL configuration====<br />
<br />
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'''.<br />
<br />
To enable SSL connections for the DCS client the following config must be set to true.<br />
<pre><br />
com.openexchange.dcs.client.ssl.enabled=true<br />
</pre><br />
<br />
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.<br />
<pre><br />
com.openexchange.dcs.client.ssl.verifyHostname=true<br />
</pre><br />
<br />
The DCS client also needs key- and optional truststore config items to be set.<br />
<pre><br />
com.openexchange.dcs.client.ssl.keystore.path=/opt/open-xchange/etc/example-client.ks<br />
com.openexchange.dcs.client.ssl.keystore.password=my-ks-password<br />
com.openexchange.dcs.client.ssl.truststore.path=/opt/open-xchange/etc/example-client.ts<br />
com.openexchange.dcs.client.ssl.truststore.password=my-ts-password<br />
</pre><br />
<br />
'''Note:</br><br />
Please keep in mind that mixed setups of SSL and non-SSL configured DCS nodes or DCS clients (Middleware nodes) are not supported.'''<br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
<!--<br />
'''Note:''' The SpellCheck Service '''does not support 'keep-alive'''' connections.<br><br />
<br />
This means that each HTTP(S) connection opened to make a request to the SpellCheck service needs to be closed as soon as the service response has been consumed by the client/caller side.<br />
The OX App Suite Middleware client implementation ensures this behaviour. Care has to be taken if client requests are routed via a HTTP proxy (e.g loadbalancer). In this case the configuration of the loadbalancer needs to be configured in a way that no 'keep-alive' connections are established.<br />
<br />
In the case of an Apache loadbalancer an appropriate entry would look like this example:<br />
Disable Apache LoadBalancer keep-alive<br />
<pre><br />
<Proxy balancer://oxcluster_spellcheck><br />
...<br />
BalancerMember http://localhost:8003 keepalive=Off timeout=... smax=... ttl=... retry=... loadfactor=... route=...<br />
...<br />
</pre><br />
<br />
--><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds as expected.<br />
<br />
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.<br />
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.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=26482AppSuite:Documents Installation Guide2021-12-07T20:48:42Z<p>Stx12: add SSL for DCS client side MW</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
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.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
====SSL configuration====<br />
<br />
The DCS supports to secure the network traffic between DCS nodes and between DCS and middleware nodes using Java key- and truststore files.<br />
SSL support has to be enabled by using the config item:<br />
<pre><br />
dcs.usessl=true<br />
</pre><br />
<br />
If the optional config item <tt>advertiseURL</tt> is used it has to be adapted by adding the protocol part '''ssl''' which also reflects the secure connection. E.g.<br />
<pre><br />
dcs.advertiseURL=ssl://dcs.example.com:61616<br />
</pre><br />
<br />
For security reasons it's recommended to enable host name verification for SSL connections. If you enable this option, you have to configure <tt>dcs.host</tt> or <tt>dcs.advertiseURL</tt> 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.<br />
<pre><br />
dcs.ssl.verifyHostname=true<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.server.keystore.path=/opt/open-xchange/etc/example-broker.ks<br />
</pre><br />
<br />
You have to provide the password for the keystore which you have set while creating the keystore.<br />
<pre><br />
dcs.ssl.server.keystore.password=my-ks-password<br />
</pre><br />
<br />
If you use a truststore you have to provide the path to the file, too.<br />
<pre><br />
dcs.ssl.server.truststore.path=/opt/open-xchange/etc/example-broker.ts<br />
</pre><br />
<br />
The truststore is also secured with a password which must be provided by the config item:<br />
<pre><br />
dcs.ssl.server.truststore.password=my-ts-password<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.client.keystore.path=/opt/open-xchange/etc/example-client.ks<br />
dcs.ssl.client.keystore.password=my-ks-password<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.client.truststore.path=/opt/open-xchange/etc/example-client.ts<br />
dcs.ssl.client.truststore.password=my-ts-password<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
====SSL configuration====<br />
<br />
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'''.<br />
<br />
To enable SSL connections for the DCS client the following config must be set to true.<br />
<pre><br />
com.openexchange.dcs.client.ssl.enabled=true<br />
</pre><br />
<br />
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.<br />
<pre><br />
com.openexchange.dcs.client.ssl.verifyHostname=true<br />
</pre><br />
<br />
The DCS client also needs key- and optional truststore config items to be set.<br />
<pre><br />
com.openexchange.dcs.client.ssl.keystore.path=/opt/open-xchange/etc/example-client.ks<br />
com.openexchange.dcs.client.ssl.keystore.password=my-ks-password<br />
com.openexchange.dcs.client.ssl.truststore.path=/opt/open-xchange/etc/example-client.ts<br />
com.openexchange.dcs.client.ssl.truststore.password=my-ts-password<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
<!--<br />
'''Note:''' The SpellCheck Service '''does not support 'keep-alive'''' connections.<br><br />
<br />
This means that each HTTP(S) connection opened to make a request to the SpellCheck service needs to be closed as soon as the service response has been consumed by the client/caller side.<br />
The OX App Suite Middleware client implementation ensures this behaviour. Care has to be taken if client requests are routed via a HTTP proxy (e.g loadbalancer). In this case the configuration of the loadbalancer needs to be configured in a way that no 'keep-alive' connections are established.<br />
<br />
In the case of an Apache loadbalancer an appropriate entry would look like this example:<br />
Disable Apache LoadBalancer keep-alive<br />
<pre><br />
<Proxy balancer://oxcluster_spellcheck><br />
...<br />
BalancerMember http://localhost:8003 keepalive=Off timeout=... smax=... ttl=... retry=... loadfactor=... route=...<br />
...<br />
</pre><br />
<br />
--><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds as expected.<br />
<br />
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.<br />
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.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=26479AppSuite:Documents Installation Guide2021-12-07T20:44:26Z<p>Stx12: add SSL for DCS</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
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.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
====SSL configuration====<br />
<br />
The DCS supports to secure the network traffic between DCS nodes and between DCS and middleware nodes using Java key- and truststore files.<br />
SSL support has to be enabled by using the config item:<br />
<pre><br />
dcs.usessl=true<br />
</pre><br />
<br />
If the optional config item <tt>advertiseURL</tt> is used it has to be adapted by adding the protocol part '''ssl''' which also reflects the secure connection. E.g.<br />
<pre><br />
dcs.advertiseURL=ssl://dcs.example.com:61616<br />
</pre><br />
<br />
For security reasons it's recommended to enable host name verification for SSL connections. If you enable this option, you have to configure <tt>dcs.host</tt> or <tt>dcs.advertiseURL</tt> 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.<br />
<pre><br />
dcs.ssl.verifyHostname=true<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.server.keystore.path=/opt/open-xchange/etc/example-broker.ks<br />
</pre><br />
<br />
You have to provide the password for the keystore which you have set while creating the keystore.<br />
<pre><br />
dcs.ssl.server.keystore.password=my-ks-password<br />
</pre><br />
<br />
If you use a truststore you have to provide the path to the file, too.<br />
<pre><br />
dcs.ssl.server.truststore.path=/opt/open-xchange/etc/example-broker.ts<br />
</pre><br />
<br />
The truststore is also secured with a password which must be provided by the config item:<br />
<pre><br />
dcs.ssl.server.truststore.password=my-ts-password<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.client.keystore.path=/opt/open-xchange/etc/example-client.ks<br />
dcs.ssl.client.keystore.password=my-ks-password<br />
</pre><br />
<br />
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.<br />
<pre><br />
dcs.ssl.client.truststore.path=/opt/open-xchange/etc/example-client.ts<br />
dcs.ssl.client.truststore.password=my-ts-password<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
<!--<br />
'''Note:''' The SpellCheck Service '''does not support 'keep-alive'''' connections.<br><br />
<br />
This means that each HTTP(S) connection opened to make a request to the SpellCheck service needs to be closed as soon as the service response has been consumed by the client/caller side.<br />
The OX App Suite Middleware client implementation ensures this behaviour. Care has to be taken if client requests are routed via a HTTP proxy (e.g loadbalancer). In this case the configuration of the loadbalancer needs to be configured in a way that no 'keep-alive' connections are established.<br />
<br />
In the case of an Apache loadbalancer an appropriate entry would look like this example:<br />
Disable Apache LoadBalancer keep-alive<br />
<pre><br />
<Proxy balancer://oxcluster_spellcheck><br />
...<br />
BalancerMember http://localhost:8003 keepalive=Off timeout=... smax=... ttl=... retry=... loadfactor=... route=...<br />
...<br />
</pre><br />
<br />
--><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds as expected.<br />
<br />
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.<br />
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.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:ImageConverter_Install&diff=26363AppSuite:ImageConverter Install2021-10-26T09:01:17Z<p>Stx12: </p>
<hr />
<div>= Download & Installation Imageconverter =<br />
<br />
=== General Information ===<br />
<br />
OX App Suite displays images (photos and graphics) in many different ways as<br />
<br />
* Thumbnails<br />
* Icons<br />
* Images embedded in documents <br />
* in Emails<br />
* in an own pop-up window.<br />
<br />
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.<br />
<br />
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.<br />
<br />
The separation of the Image Converter service has the following advantages:<br />
<br />
Configuration and usage of one or more separate storages<br />
Performance improvements via persistent cache<br />
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.<br />
Best matching size will be delivered without new conversion, if an image is requested by the Middleware<br />
Browser is able to cache those images<br />
No limits for image sizes<br />
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.<br />
Reduce load of OX Middleware<br />
<br />
== Requirements ==<br />
<br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately on the user servicing OX App Suite middleware nodes:<br />
<br />
* The Image Converter Client: See [[AppSuite:ImageConverterClientInstall|Image converter client installation instructions]]<br />
<br />
== Installation ==<br />
<br />
The Image Converter deployment consists of the package <tt>open-xchange-imageconverter-server</tt>.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Redhat Enterprise Linux 7, CentOS 7 or Amazon Linux 2 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until 7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-imageconverter-server<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
The following property files need to be adjusted on the Image Converter node to ensure correct runtime behavior of the ImageConverter implementation<br />
<br />
* fileitem.properties<br />
* imageconverter.properties<br />
<br />
=== Filestores ===<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
Create a directory for the FileItemService filestore(s) with OS commands, that is writable for the user, running the OX backends:<br />
<br />
$ mkdir -p /var/opt/fileitemstore<br />
$ chown open-xchange:open-xchange /var/opt/fileitemstore<br />
<br />
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.<br />
<br />
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.<br />
<br />
$ env RMI_HOSTNAME=rmi://localhost:1095 /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P ${AS_ADMINMASTER_PASS} -x 0 -t file:///var/opt/fileitemstore<br />
<br />
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<br />
<br />
Create a new, empty database schema to be used by the FileItemService: <br />
<br />
$ /opt/open-xchange/imageconverter/sbin/initfileitemdb -i --fileitemdb-pass="${AS_DB_PASS}" --fileitemdb-user=openexchange --fileitemdb-host=localhost --fileitemdb-port=3306 --fileitemdb-dbname=fileitemdb<br />
<br />
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.<br />
<br />
The following properties of the fileitem.properties need to be adjusted, at least (example values are provided):<br />
<br />
$ com.openexchange.fileItem.fileStoreIds=3<br />
$<br />
$ com.openexchange.fileItem.readUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.readProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.readProperty.2=password=${AS_DB_PASS}<br />
$<br />
$ com.openexchange.fileItem.writeUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.writeProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.writeProperty.2=password=${AS_DB_PASS}<br />
<br />
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<br />
<br />
=== ImageMagick ===<br />
<br />
On Amazon Linux 2, ImageMagick is located under ''/bin''. Therefore the property ''com.openexchange.imageconverter.imagemagick.searchPath'' must be adjusted accordingly.<br />
<br />
= Sizing and technical background =<br />
<br />
== Summary ==<br />
<br />
* One Image Converter node should have at least 4 cores<br />
* One Image Converter node needs to have at least 4GB RAM <br />
* Local storage space with a minimum of 10 GigaBytes needs to be available on an Image Converter node<br />
* 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<br />
<br />
== Background ==<br />
<br />
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.<br />
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.<br />
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. <br />
To get a best fit for most use case, the IC creates a set of differently processed target files (e.g.<br />
different image resolutions) for each source image and stores those results within its configured cache.<br />
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.<br />
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.<br />
<br />
== Storage ==<br />
<br />
=== Temporary files ===<br />
<br />
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.<br />
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.<br />
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.<br />
The working directory, that needs to have write access for the IC user can be configured via the following config item:<br />
<br />
* com.openexchange.imageconverter.spoolPath<br />
<br />
=== Persistent files ===<br />
<br />
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.<br />
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<br />
corresponding files (based on last access time) within the cache are configured via the the following IC config properties:<br />
<br />
* com.openexchange.imageconverter.cache.maxKeyCount <br />
* com.openexchange.imageconverter.cache.maxSizeGB<br />
* com.openexchange.imageconverter.cache.keyTimeoutMinutes<br />
<br />
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.<br />
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.<br />
<br />
== Memory usage ==<br />
<br />
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.<br />
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:<br />
<br />
* com.openexchange.imageconverter.queueLength<br />
<br />
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:<br />
<br />
* com.openexchange.imageconverter.threadCount<br />
<br />
=== Java VM memory usage ===<br />
<br />
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.<br />
If larger queue lengths are configured by the administrator, the maximum available Java VM memory limit should be increased as well. <br />
Exact numbers for the increment of available Java VM memory cannot be given due to quite different source sizes of images in general. <br />
A Java VM memory increment of 100 MegaBytes for an additional queue length of 100 entries should be sufficient.<br />
<br />
=== Processing backend memory usage ===<br />
<br />
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.<br />
<br />
== Request throughput ==<br />
<br />
When talking about request throughput, we need to take two different scenarios into account.<br />
The first one is the IC operation with no available cache or an available cache that has not been filled up much yet.<br />
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. <br />
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.<br />
<br />
* 1.0 / 0.15s = 6.7/s (median requests per second for 8 processing backends using no cache)<br />
<br />
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.<br />
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:<br />
<br />
* 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%)<br />
<br />
== Multiple nodes and number of users per node ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Metrics to Monitor ==<br />
<br />
Due to the fact that each user has a quite different usage scenario when working in OX App Suite, 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. Additional helpful metrics are CacheHitRatio (should be above 0.6) and CacheOldestEntrySeconds (>172800 = 2 days). If these values can't be met one may want to increase the size of the storage medium.</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:ImageConverter_Install&diff=26360AppSuite:ImageConverter Install2021-10-26T08:59:05Z<p>Stx12: add some sizing hints</p>
<hr />
<div>= Download & Installation Imageconverter =<br />
<br />
=== General Information ===<br />
<br />
OX App Suite displays images (photos and graphics) in many different ways as<br />
<br />
* Thumbnails<br />
* Icons<br />
* Images embedded in documents <br />
* in Emails<br />
* in an own pop-up window.<br />
<br />
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.<br />
<br />
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.<br />
<br />
The separation of the Image Converter service has the following advantages:<br />
<br />
Configuration and usage of one or more separate storages<br />
Performance improvements via persistent cache<br />
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.<br />
Best matching size will be delivered without new conversion, if an image is requested by the Middleware<br />
Browser is able to cache those images<br />
No limits for image sizes<br />
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.<br />
Reduce load of OX Middleware<br />
<br />
== Requirements ==<br />
<br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately on the user servicing OX App Suite middleware nodes:<br />
<br />
* The Image Converter Client: See [[AppSuite:ImageConverterClientInstall|Image converter client installation instructions]]<br />
<br />
== Installation ==<br />
<br />
The Image Converter deployment consists of the package <tt>open-xchange-imageconverter-server</tt>.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Redhat Enterprise Linux 7, CentOS 7 or Amazon Linux 2 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until 7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-imageconverter-server<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
The following property files need to be adjusted on the Image Converter node to ensure correct runtime behavior of the ImageConverter implementation<br />
<br />
* fileitem.properties<br />
* imageconverter.properties<br />
<br />
=== Filestores ===<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
Create a directory for the FileItemService filestore(s) with OS commands, that is writable for the user, running the OX backends:<br />
<br />
$ mkdir -p /var/opt/fileitemstore<br />
$ chown open-xchange:open-xchange /var/opt/fileitemstore<br />
<br />
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.<br />
<br />
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.<br />
<br />
$ env RMI_HOSTNAME=rmi://localhost:1095 /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P ${AS_ADMINMASTER_PASS} -x 0 -t file:///var/opt/fileitemstore<br />
<br />
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<br />
<br />
Create a new, empty database schema to be used by the FileItemService: <br />
<br />
$ /opt/open-xchange/imageconverter/sbin/initfileitemdb -i --fileitemdb-pass="${AS_DB_PASS}" --fileitemdb-user=openexchange --fileitemdb-host=localhost --fileitemdb-port=3306 --fileitemdb-dbname=fileitemdb<br />
<br />
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.<br />
<br />
The following properties of the fileitem.properties need to be adjusted, at least (example values are provided):<br />
<br />
$ com.openexchange.fileItem.fileStoreIds=3<br />
$<br />
$ com.openexchange.fileItem.readUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.readProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.readProperty.2=password=${AS_DB_PASS}<br />
$<br />
$ com.openexchange.fileItem.writeUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.writeProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.writeProperty.2=password=${AS_DB_PASS}<br />
<br />
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<br />
<br />
=== ImageMagick ===<br />
<br />
On Amazon Linux 2, ImageMagick is located under ''/bin''. Therefore the property ''com.openexchange.imageconverter.imagemagick.searchPath'' must be adjusted accordingly.<br />
<br />
= Sizing and technical background =<br />
<br />
== Summary ==<br />
<br />
* One Image Converter node should have at least 4 cores<br />
* One Image Converter node needs to have at least 4GB RAM <br />
* Local storage space with a minimum of 10 GigaBytes needs to be available on an Image Converter node<br />
* 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<br />
<br />
== Background ==<br />
<br />
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.<br />
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.<br />
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. <br />
To get a best fit for most use case, the IC creates a set of differently processed target files (e.g.<br />
different image resolutions) for each source image and stores those results within its configured cache.<br />
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.<br />
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.<br />
<br />
== Storage ==<br />
<br />
=== Temporary files ===<br />
<br />
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.<br />
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.<br />
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.<br />
The working directory, that needs to have write access for the IC user can be configured via the following config item:<br />
<br />
* com.openexchange.imageconverter.spoolPath<br />
<br />
=== Persistent files ===<br />
<br />
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.<br />
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<br />
corresponding files (based on last access time) within the cache are configured via the the following IC config properties:<br />
<br />
* com.openexchange.imageconverter.cache.maxKeyCount <br />
* com.openexchange.imageconverter.cache.maxSizeGB<br />
* com.openexchange.imageconverter.cache.keyTimeoutMinutes<br />
<br />
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.<br />
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.<br />
<br />
== Memory usage ==<br />
<br />
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.<br />
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:<br />
<br />
* com.openexchange.imageconverter.queueLength<br />
<br />
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:<br />
<br />
* com.openexchange.imageconverter.threadCount<br />
<br />
=== Java VM memory usage ===<br />
<br />
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.<br />
If larger queue lengths are configured by the administrator, the maximum available Java VM memory limit should be increased as well. <br />
Exact numbers for the increment of available Java VM memory cannot be given due to quite different source sizes of images in general. <br />
A Java VM memory increment of 100 MegaBytes for an additional queue length of 100 entries should be sufficient.<br />
<br />
=== Processing backend memory usage ===<br />
<br />
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.<br />
<br />
== Request throughput ==<br />
<br />
When talking about request throughput, we need to take two different scenarios into account.<br />
The first one is the IC operation with no available cache or an available cache that has not been filled up much yet.<br />
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. <br />
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.<br />
<br />
* 1.0 / 0.15s = 6.7/s (median requests per second for 8 processing backends using no cache)<br />
<br />
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.<br />
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:<br />
<br />
* 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%)<br />
<br />
== Multiple nodes and number of users per node ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Sizing ==<br />
<br />
Due to the fact that each user has a quite different usage scenario when working in OX App Suite, 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. Additional helpful metrics are CacheHitRatio (should be above 0.6) and CacheOldestEntrySeconds (>172800 = 2 days). If these values can't be met one may want to increase the size of the storage medium.</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Supported_file_types_draft_improvements&diff=25987AppSuite:Supported file types draft improvements2021-05-27T12:50:59Z<p>Stx12: point to documentation.ox</p>
<hr />
<div><!-- !!! --><br />
<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation --> <br />
<!-- !!! --><br />
<br />
The content on this page has never left the status of a draft.<br />
<br />
The content moved to https://documentation.open-xchange.com/latest/ui/miscellaneous/file-support.html<br />
<br />
Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25593AppSuite:Documents Installation Guide2020-09-09T15:05:52Z<p>Stx12: 1:1 Relation HZ and DCS cluster</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
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.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
<!--<br />
'''Note:''' The SpellCheck Service '''does not support 'keep-alive'''' connections.<br><br />
<br />
This means that each HTTP(S) connection opened to make a request to the SpellCheck service needs to be closed as soon as the service response has been consumed by the client/caller side.<br />
The OX App Suite Middleware client implementation ensures this behaviour. Care has to be taken if client requests are routed via a HTTP proxy (e.g loadbalancer). In this case the configuration of the loadbalancer needs to be configured in a way that no 'keep-alive' connections are established.<br />
<br />
In the case of an Apache loadbalancer an appropriate entry would look like this example:<br />
Disable Apache LoadBalancer keep-alive<br />
<pre><br />
<Proxy balancer://oxcluster_spellcheck><br />
...<br />
BalancerMember http://localhost:8003 keepalive=Off timeout=... smax=... ttl=... retry=... loadfactor=... route=...<br />
...<br />
</pre><br />
<br />
--><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds as expected.<br />
<br />
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.<br />
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.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25584AppSuite:Documents Installation Guide2020-08-25T18:55:06Z<p>Stx12: memory</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
<!--<br />
'''Note:''' The SpellCheck Service '''does not support 'keep-alive'''' connections.<br><br />
<br />
This means that each HTTP(S) connection opened to make a request to the SpellCheck service needs to be closed as soon as the service response has been consumed by the client/caller side.<br />
The OX App Suite Middleware client implementation ensures this behaviour. Care has to be taken if client requests are routed via a HTTP proxy (e.g loadbalancer). In this case the configuration of the loadbalancer needs to be configured in a way that no 'keep-alive' connections are established.<br />
<br />
In the case of an Apache loadbalancer an appropriate entry would look like this example:<br />
Disable Apache LoadBalancer keep-alive<br />
<pre><br />
<Proxy balancer://oxcluster_spellcheck><br />
...<br />
BalancerMember http://localhost:8003 keepalive=Off timeout=... smax=... ttl=... retry=... loadfactor=... route=...<br />
...<br />
</pre><br />
<br />
--><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds as expected.<br />
<br />
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.<br />
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.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25583AppSuite:Documents Installation Guide2020-08-25T16:57:16Z<p>Stx12: keep notes on keep-alive in comment</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
<!--<br />
'''Note:''' The SpellCheck Service '''does not support 'keep-alive'''' connections.<br><br />
<br />
This means that each HTTP(S) connection opened to make a request to the SpellCheck service needs to be closed as soon as the service response has been consumed by the client/caller side.<br />
The OX App Suite Middleware client implementation ensures this behaviour. Care has to be taken if client requests are routed via a HTTP proxy (e.g loadbalancer). In this case the configuration of the loadbalancer needs to be configured in a way that no 'keep-alive' connections are established.<br />
<br />
In the case of an Apache loadbalancer an appropriate entry would look like this example:<br />
Disable Apache LoadBalancer keep-alive<br />
<pre><br />
<Proxy balancer://oxcluster_spellcheck><br />
...<br />
BalancerMember http://localhost:8003 keepalive=Off timeout=... smax=... ttl=... retry=... loadfactor=... route=...<br />
...<br />
</pre><br />
<br />
--><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25582AppSuite:Documents Installation Guide2020-08-25T11:32:02Z<p>Stx12: /* Spellcheck Service Monitoring */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Besides using a ''Prometheus'' system to constantly gather metrics, the current values can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25578AppSuite:Documents Installation Guide2020-08-19T19:36:05Z<p>Stx12: metrics</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
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 <br />
<pre><br />
RequestCount{httpRequestCount_total="total"}<br />
ServerStatus{property="requestTimeout"}<br />
</pre><br />
Additionally the ratio of <br />
<pre><br />
RequestTime_bucket{method="check-paragraph-spelling",le="2.000000"}<br />
RequestCount{method="check-paragraph-spelling",statusCode="200"}<br />
</pre><br />
will show whether more than about 90% spelling requests are handled within 2 seconds.<br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' system to constantly gather metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25577AppSuite:Documents Installation Guide2020-08-19T15:05:34Z<p>Stx12: /* Sizing and performance */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would consume 3 CPU cores.<br />
<br />
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.<br />
<br />
<!-- allows a throughput of about 20-25 requests/s per thread and per dedicated core. you will notice a degraded service by hitting this limit (see metric xxx ) and/or run in timeout errors --><br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' system to constantly gather metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25576AppSuite:Documents Installation Guide2020-08-19T15:04:12Z<p>Stx12: sizing and performance</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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, ...<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
==== Sizing and performance ====<br />
<br />
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<br />
<pre><br />
com.openexchange.spellcheck.threadCount = 3<br />
</pre><br />
A heavily used service thus would use 3 CPU cores.<br />
<br />
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.<br />
<br />
<!-- allows a throughput of about 20-25 requests/s per thread and per dedicated core. you will notice a degraded service by hitting this limit (see metric xxx ) and/or run in timeout errors --><br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' system to constantly gather metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25575AppSuite:Documents Installation Guide2020-08-19T14:22:01Z<p>Stx12: /* SpellCheck Monitoring */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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.<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== Spellcheck Service Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' system to constantly gather metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25574AppSuite:Documents Installation Guide2020-08-19T14:21:24Z<p>Stx12: /* SpellCheck Monitoring */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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.<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' system to constantly gather metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25573AppSuite:Documents Installation Guide2020-08-19T14:20:16Z<p>Stx12: /* Separate Service valid from 7.10.4 on */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
If the default listening port 8003 doesn't fit your needs the following property needs to be set.<br />
<pre><br />
com.openexchange.spellcheck.port=4711<br />
</pre><br />
<br />
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.<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
The SpellCheck service internally starts 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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' system to constantly gather metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25572AppSuite:Documents Installation Guide2020-08-19T14:10:24Z<p>Stx12: /* Valid from 7.10.4 */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Separate Service valid from 7.10.4 on ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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. <br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
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.<br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25571AppSuite:Documents Installation Guide2020-08-19T13:53:59Z<p>Stx12: /* Valid up to and including 7.10.3 */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Integrated Functionality valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Valid from 7.10.4 ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25570AppSuite:Documents Installation Guide2020-08-19T13:51:32Z<p>Stx12: /* Valid until 7.10.3 */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Valid up to and including 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Valid from 7.10.4 ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25569AppSuite:Documents Installation Guide2020-08-19T13:49:12Z<p>Stx12: removal of note that no additional packages are needed on MW for documents collaboration framework</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/7.10.3|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Valid until 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Valid from 7.10.4 ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25403AppSuite:Documents Installation Guide2020-06-17T07:44:56Z<p>Stx12: Undo revision 25402 by Stx12 (talk)</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Valid until 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Valid from 7.10.4 ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25402AppSuite:Documents Installation Guide2020-06-17T07:43:57Z<p>Stx12: /* Documents Collaboration Service */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration service (see below).<br />
<br />
The package <tt>open-xchange-spellcheck</tt> has been introduced with 7.10.4. It provides the SpellCheck service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Notes:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.</br><br />
The SpellCheck service is available since 7.10.4 and as such not available for RHEL6.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.4) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration|spellcheck}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid from v7.10.3) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid from v7.10.4) === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration open-xchange-spellcheck<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
The DCS is mandatory for OX Documents to work. It needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
== SpellCheck Service ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
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 <b>/opt/open-xchange/etc/documents.properties</b> file.</br><br />
<br />
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.<br />
<pre><br />
com.openexchange.office.spellcheck.remoteURL = http://192.168.10.25:8003<br />
</pre><br />
<br />
=== Spell Checking ===<br />
<br />
<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
==== Valid until 7.10.3 ====<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
==== Valid from 7.10.4 ====<br />
<br />
Prepare spellcheck repository as described above.<br />
<br />
The SpellCheck service will be installed via the package:<br />
<pre><br />
open-xchange-spellcheck<br />
</pre><br />
<br />
The target directory is <b>/opt/open-xchange/spellcheck</b><br />
<br />
The SpellCheck service internally uses ''hunspell'' for spell checking functionality.<br />
<br />
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.<br />
<pre><br />
29582 29582 29582 ? 00:00:00 oxspell<br />
29583 29582 29582 ? 00:00:02 |-oxspell<br />
</pre><br />
<br />
The SpellCheck service configuration file is located at <b>/opt/open-xchange/spellcheck/etc/spellcheck.properties</b>. All available configuration items are described on this [https://documentation.open-xchange.com/components/spellcheck/config/7.10.4/ page]<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.dictionaryPath=/usr/share/hunspell<br />
</pre><br />
<br />
Additional dictionaries are published for your platform as packages named hunspell-de-de, hunspell-fr, ...</br><br />
''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.<br />
<br />
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.<br><br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress = 0.0.0.0<br />
</pre><br />
<br />
===== SpellCheck Service Transport Security =====<br />
<br />
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.</br><br />
<pre><br />
com.openexchange.spellcheck.ssl.enable=true<br />
com.openexchange.spellcheck.ssl.certFile=/path/to/sslcertificate/certfile<br />
com.openexchange.spellcheck.ssl.keyFile=/path/to/sslcertificate/keyfile<br />
</pre><br />
<br />
===== SpellCheck Monitoring =====<br />
<br />
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.<br />
<pre><br />
com.openexchange.spellcheck.listenAddress.metrics=0.0.0.0<br />
com.openexchange.spellcheck.port.metrics=8002<br />
</pre><br />
Beside using a ''Prometheus'' frontend to constanly visualize metrics, the current metrics can be retrieved with the following call.<br />
<pre><br />
curl localhost:8002/metrics | sort<br />
</pre><br />
<br />
== Templates ==<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
== OX Documents in Browser Tabs ==<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:ImageConverter_Install&diff=25228AppSuite:ImageConverter Install2020-01-23T12:41:31Z<p>Stx12: add hint about scality sproxyd</p>
<hr />
<div>= Download & Installation Imageconverter =<br />
<br />
=== General Information ===<br />
<br />
OX App Suite displays images (photos and graphics) in many different ways as<br />
<br />
* Thumbnails<br />
* Icons<br />
* Images embedded in documents <br />
* in Emails<br />
* in an own pop-up window.<br />
<br />
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.<br />
<br />
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 ImageConverter server. It's deployment model is exactly corresponding to the documentconverter server via a client/server service.<br />
<br />
The separation of the ImageConverter service has the following advantages:<br />
<br />
Configuration and usage of one or more separate storages<br />
Performance improvements via persistent cache<br />
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.<br />
Best matching size will be delivered without new conversion, if an image is requested by the Middleware<br />
Browser is able to cache those images<br />
No limits for image sizes<br />
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.<br />
Reduce load of OX Middleware<br />
<br />
== Requirements ==<br />
<br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately on the user servicing OX App Suite middleware nodes:<br />
<br />
* The Image Converter Client: See [[AppSuite:ImageConverterClientInstall|Image converter client installation instructions]]<br />
<br />
== Installation ==<br />
<br />
The Image Converter deployment consists of the package <tt>open-xchange-imageconverter-server</tt>.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Redhat Enterprise Linux 7, CentOS 7 or Amazon Linux 2 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-imageconverter-server<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
The following property files need to be adjusted on the ImageConverter node to ensure correct runtime behavior of the ImageConverter implementation<br />
<br />
* fileitem.properties<br />
* imageconverter.properties<br />
<br />
=== Filestores ===<br />
<br />
Since the ImageConverter 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 ImageConverter WebService.<br />
<br />
'''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.<br />
<br />
Create a directory for the FileItemService filestore(s) with OS commands, that is writable for the user, running the OX backends:<br />
<br />
$ mkdir -p /var/opt/fileitemstore<br />
$ chown open-xchange:open-xchange /var/opt/fileitemstore<br />
<br />
Register the FileItemService filestore(s) via the OX admin command registerfilestore after installation. Since the the RMI port for administrative calls to the ImageConverter 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.<br />
<br />
Since the ImageConverter 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.<br />
<br />
$ env RMI_HOSTNAME=rmi://localhost:1095 /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P ${AS_ADMINMASTER_PASS} -x 0 -t file:///var/opt/fileitemstore<br />
<br />
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<br />
<br />
Create a new, empty database schema to be used by the FileItemService: <br />
<br />
$ /opt/open-xchange/imageconverter/sbin/initfileitemdb -i --fileitemdb-pass="${AS_DB_PASS}" --fileitemdb-user=openexchange --fileitemdb-host=localhost --fileitemdb-port=3306 --fileitemdb-dbname=fileitemdb<br />
<br />
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.<br />
<br />
The following properties of the fileitem.properties need to be adjusted, at least (example values are provided):<br />
<br />
$ com.openexchange.fileItem.fileStoreIds=3<br />
$<br />
$ com.openexchange.fileItem.readUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.readProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.readProperty.2=password=${AS_DB_PASS}<br />
$<br />
$ com.openexchange.fileItem.writeUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.writeProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.writeProperty.2=password=${AS_DB_PASS}<br />
<br />
The ImageConverter itself currently relies on the external ImageMagick framework, so that this package has to be installed on the node, the ImageConverter is running on<br />
<br />
=== ImageMagick ===<br />
<br />
On Amazon Linux 2, ImageMagick is located under ''/bin''. Therefore the property ''com.openexchange.imageconverter.imagemagick.searchPath'' must be adjusted accordingly.</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25227AppSuite:DocumentsMonitoring2020-01-22T16:37:50Z<p>Stx12: /* DCS */</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
The Spring Boot framework offers general metrics about system, JVM, ...<br />
As an example the metric process.cpu.usage is picked from the list at https://docs.spring.io/spring-boot/docs/2.0.10.BUILD-SNAPSHOT/actuator-api/html/#metrics :<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/metrics/process.cpu.usage" <br />
{"name": "process.cpu.usage","measurements":[{"value": 0.03215434083601286, ...<br />
</pre><br />
These general metrics can also be retrieved in prometheus format<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/prometheus"<br />
# HELP jvm_threads_peak_threads ...<br />
# TYPE jvm_threads_peak_threads gauge<br />
jvm_threads_peak_threads 58.0<br />
...<br />
</pre><br />
Data specific to ActiveMQ is explained in the [https://activemq.apache.org/jmx ActiveMQ MBeans Reference].<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25226AppSuite:DocumentsMonitoring2020-01-22T16:36:50Z<p>Stx12: links to activemq and spring boot</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
The Spring Boot framework offers general metrics about system, JVM, ...<br />
As an example the metric process.cpu.usage is picked from the list at https://docs.spring.io/spring-boot/docs/2.0.10.BUILD-SNAPSHOT/actuator-api/html/#metrics :<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/metrics/process.cpu.usage" <br />
{"name": "process.cpu.usage","measurements":[{"value": 0.03215434083601286, ...<br />
</pre><br />
Metrics can also be retrieved in prometheus format<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/prometheus"<br />
# HELP jvm_threads_peak_threads ...<br />
# TYPE jvm_threads_peak_threads gauge<br />
jvm_threads_peak_threads 58.0<br />
...<br />
</pre><br />
Data specific to ActiveMQ is shown in the [https://activemq.apache.org/jmx ActiveMQ MBeans Reference].<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:ImageConverter_Install&diff=25225AppSuite:ImageConverter Install2020-01-22T16:18:13Z<p>Stx12: added s3</p>
<hr />
<div>= Download & Installation Imageconverter =<br />
<br />
=== General Information ===<br />
<br />
OX App Suite displays images (photos and graphics) in many different ways as<br />
<br />
* Thumbnails<br />
* Icons<br />
* Images embedded in documents <br />
* in Emails<br />
* in an own pop-up window.<br />
<br />
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.<br />
<br />
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 ImageConverter server. It's deployment model is exactly corresponding to the documentconverter server via a client/server service.<br />
<br />
The separation of the ImageConverter service has the following advantages:<br />
<br />
Configuration and usage of one or more separate storages<br />
Performance improvements via persistent cache<br />
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.<br />
Best matching size will be delivered without new conversion, if an image is requested by the Middleware<br />
Browser is able to cache those images<br />
No limits for image sizes<br />
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.<br />
Reduce load of OX Middleware<br />
<br />
== Requirements ==<br />
<br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately on the user servicing OX App Suite middleware nodes:<br />
<br />
* The Image Converter Client: See [[AppSuite:ImageConverterClientInstall|Image converter client installation instructions]]<br />
<br />
== Installation ==<br />
<br />
The Image Converter deployment consists of the package <tt>open-xchange-imageconverter-server</tt>.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Redhat Enterprise Linux 7, CentOS 7 or Amazon Linux 2 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-imageconverter-server<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
The following property files need to be adjusted on the ImageConverter node to ensure correct runtime behavior of the ImageConverter implementation<br />
<br />
* fileitem.properties<br />
* imageconverter.properties<br />
<br />
=== Filestores ===<br />
<br />
Since the ImageConverter 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 ImageConverter WebService.<br />
<br />
'''Please note:''' Initially file-system based filestores (NFS) were supported only. Object storage support (S3) has been added with 7.10.3.<br />
<br />
Create a directory for the FileItemService filestore(s) with OS commands, that is writable for the user, running the OX backends:<br />
<br />
$ mkdir -p /var/opt/fileitemstore<br />
$ chown open-xchange:open-xchange /var/opt/fileitemstore<br />
<br />
Register the FileItemService filestore(s) via the OX admin command registerfilestore after installation. Since the the RMI port for administrative calls to the ImageConverter 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.<br />
<br />
Since the ImageConverter 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.<br />
<br />
$ env RMI_HOSTNAME=rmi://localhost:1095 /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P ${AS_ADMINMASTER_PASS} -x 0 -t file:///var/opt/fileitemstore<br />
<br />
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<br />
<br />
Create a new, empty database schema to be used by the FileItemService: <br />
<br />
$ /opt/open-xchange/imageconverter/sbin/initfileitemdb -i --fileitemdb-pass="${AS_DB_PASS}" --fileitemdb-user=openexchange --fileitemdb-host=localhost --fileitemdb-port=3306 --fileitemdb-dbname=fileitemdb<br />
<br />
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.<br />
<br />
The following properties of the fileitem.properties need to be adjusted, at least (example values are provided):<br />
<br />
$ com.openexchange.fileItem.fileStoreIds=3<br />
$<br />
$ com.openexchange.fileItem.readUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.readProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.readProperty.2=password=${AS_DB_PASS}<br />
$<br />
$ com.openexchange.fileItem.writeUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.writeProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.writeProperty.2=password=${AS_DB_PASS}<br />
<br />
The ImageConverter itself currently relies on the external ImageMagick framework, so that this package has to be installed on the node, the ImageConverter is running on<br />
<br />
=== ImageMagick ===<br />
<br />
On Amazon Linux 2, ImageMagick is located under ''/bin''. Therefore the property ''com.openexchange.imageconverter.imagemagick.searchPath'' must be adjusted accordingly.</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25224AppSuite:DocumentsMonitoring2020-01-22T15:39:02Z<p>Stx12: /* DCS */</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
A metric picked from the list at https://docs.spring.io/spring-boot/docs/2.0.10.BUILD-SNAPSHOT/actuator-api/html/#metrics :<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/metrics/process.cpu.usage" <br />
{"name": "process.cpu.usage","measurements":[{"value": 0.03215434083601286, ...<br />
</pre><br />
Metrics can also be retrieved in prometheus format<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/prometheus"<br />
# HELP jvm_threads_peak_threads ...<br />
# TYPE jvm_threads_peak_threads gauge<br />
jvm_threads_peak_threads 58.0<br />
...<br />
</pre><br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25223AppSuite:DocumentsMonitoring2020-01-22T15:38:18Z<p>Stx12: pointer to documentation</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
A metric picked from the list at https://docs.spring.io/spring-boot/docs/2.0.10.BUILD-SNAPSHOT/actuator-api/html/#metrics :<br />
<pre><br />
# curl "http://oxadmin:secret@localhost:8004/dcs/management/metrics/process.cpu.usage" <br />
{"name": "process.cpu.usage","measurements":[{"value": 0.03215434083601286, ...<br />
</pre><br />
Metrics can also be retrieved in prometheus format<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/prometheus"<br />
# HELP jvm_threads_peak_threads ...<br />
# TYPE jvm_threads_peak_threads gauge<br />
jvm_threads_peak_threads 58.0<br />
...<br />
</pre><br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25222AppSuite:Documents Installation Guide2020-01-22T15:17:48Z<p>Stx12: add DCS</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Note:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25221AppSuite:Documents Installation Guide2020-01-22T15:15:25Z<p>Stx12: dcs requirements and clustering</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Note:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
The service can be run as one additional server (JVM) or - for larger deployments - several instances can be clustered.<br />
Following requirements described for node sizing (4GB RAM / 4 CPU core) one should provide 1 DCS node per 10 OX App Suite Middleware nodes.<br />
<br />
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.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
sudo systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database.<br />
<br />
'''Note:</br><br />
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it<br />
to use the db username and password you configured above.<br />
'''<br />
<pre><br />
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
sudo a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25217AppSuite:DocumentsMonitoring2020-01-21T19:17:48Z<p>Stx12: /* DCS */</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
Metrics can also be retrieved in prometheus format<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/prometheus"<br />
# HELP jvm_threads_peak_threads ...<br />
# TYPE jvm_threads_peak_threads gauge<br />
jvm_threads_peak_threads 58.0<br />
...<br />
</pre><br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25216AppSuite:DocumentsMonitoring2020-01-21T19:16:25Z<p>Stx12: /* DCS */</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
Metrics can also be retrieved in prometheus format<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/prometheus"<br />
</pre><br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25215AppSuite:DocumentsMonitoring2020-01-21T19:13:02Z<p>Stx12: Spring Boot Actuator examples</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
Some examples for useful endpoints:<br />
<pre><br />
# curl "http://localhost:8004/dcs/management/health"<br />
{"status":"UP"}<br />
</pre><br />
Note that the health endpoint returns additional data if the call is authenticated.<br />
<pre><br />
# curl "http://ausername:thepass@localhost:8004/dcs/management/health"<br />
{"status":"UP","details":{"db":{"status":"UP","details":...<br />
</pre><br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25214AppSuite:DocumentsMonitoring2020-01-21T18:56:52Z<p>Stx12: link to documentation.ox</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [https://documentation.open-xchange.com/latest/middleware/monitoring/monitoring_interface.html OX_monitoring_interface]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Jolokia]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the JMX connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in [https://documentation.open-xchange.com/latest/middleware/monitoring/jolokia.html Middleware documentation].<br />
<br />
A call derived from this for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25213AppSuite:DocumentsMonitoring2020-01-21T18:29:26Z<p>Stx12: add jmx connection example</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [[OX_monitoring_interface]]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994. So the connection can be established via<br />
<pre><br />
service:jmx:rmi:///jndi/rmi://10.20.28.108:9994/jmxrmi<br />
</pre><br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].<br />
<br />
A call derived from this example for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25153AppSuite:Documents Installation Guide2019-12-06T10:42:59Z<p>Stx12: /* Redhat Enterprise Linux 6 or CentOS 6 */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Note:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25152AppSuite:Documents Installation Guide2019-12-06T10:42:09Z<p>Stx12: hint about rh6 and apache</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
'''Note:</br><br />
The Apache version 2.2 provided with RHEL6 does not support websockets. <br />
Please use Apache version 2.4.x available with RHSCL or another capable loadbalancer.'''<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25144AppSuite:Documents Installation Guide2019-12-05T13:03:45Z<p>Stx12: debian and internal/external IP</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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. <br />
<br />
'''Caveat:</br><br />
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.<br />
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.<br />
<pre>dcs.advertiseURL=dcs.example.com:61616</pre><br />
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like<br />
<pre>192.168.10.25 dcs.example.com</pre><br />
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).<br />
'''<br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs via the database is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25143AppSuite:Documents Installation Guide2019-12-05T12:24:48Z<p>Stx12: add documents-collaboration repo</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25104AppSuite:DocumentsMonitoring2019-12-02T13:31:21Z<p>Stx12: /* DCS */</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [[OX_monitoring_interface]]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
<pre><br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
</pre><br />
The default port is 9994<br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<pre><br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
</pre><br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].<br />
<br />
A call derived from this example for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25103AppSuite:DocumentsMonitoring2019-12-02T13:30:47Z<p>Stx12: /* DCS */</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [[OX_monitoring_interface]]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolokia is disabled by default.<br />
<br />
For the required settings in dcs.properties see https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/<br />
jmx.enabled=true<br />
jmx.username<br />
jmx.password<br />
The default port is 9994<br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are not accessible via Jolokia (except info and health).<br />
Additional endpoints have to be exposed and user credentials have to be configured.<br />
<br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].<br />
<br />
A call derived from this example for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:DocumentsMonitoring&diff=25102AppSuite:DocumentsMonitoring2019-12-02T13:13:29Z<p>Stx12: dcs monitoring and management</p>
<hr />
<div>= OX Documents / OX Documentconverter Monitoring =<br />
<br />
== General ==<br />
<br />
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, Documentconverter and Imageconverter.<br />
<br />
For general information about the JMX interface see: [[OX_monitoring_interface]]<br />
<br />
The usage of Jolokia to access monitoring data is described in the article [[Jolokia]]<br />
<br />
Plugins are available for integration in the munin monitoring framework: [[OX_munin_scripts]]<br />
<br />
== OX Documentconverter ==<br />
<br />
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.<br />
<br />
The following table shows all available Documentconverter server metrics, provided via the JMX interface:<br />
<br />
{| class="wikitable"<br />
!colspan="6"|Documentconverter server metrics<br />
|-<br />
|'''Metrics Name'''<br />
|'''Description'''<br />
|'''Instance / LongTerm'''<br />
|'''Remarks'''<br />
|-<br />
|CacheEntryCount<br />
|The current count of entries, stored within the persistent cache<br />
|Instance<br />
|<br />
|-<br />
|CacheFreeVolumeSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|CacheHitRatio<br />
|The ratio of successful job results that are retrieved from the cache against the total number of processed jobs as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|CacheOldestEntrySeconds<br />
|The age of the oldest entry within the cache in seconds<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|CachePersistentSize<br />
|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.<br />
|Instance<br />
|<br />
|-<br />
|ConversionCount<br />
|The total number of all physical ReaderEngine and PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountPDFTool<br />
|The total number of all physical PDFTool conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountReaderEngine<br />
|The total number of all physical ReaderEngine conversions<br />
|Instance<br />
|<br />
|-<br />
|ConversionCountWithMultipleRuns<br />
|The total number of physical ReaderEngine conversions, that needed a second, new ReaderEngine instance<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsGeneral<br />
|The total number of physical ReaderEngine conversions, that resulted in a general error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsTimeout<br />
|The total number of physical ReaderEngine conversions, that resulted in a tiemout error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsDisposed<br />
|The total number of physical ReaderEngine conversions, that resulted in a disposed error (ReaderEngine instance vanished during conversion)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPassword<br />
|The total number of physical ReaderEngine conversions, that resulted in a password error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsNoContent<br />
|The total number of physical ReaderEngine conversions, that resulted in a no content error (e.g. source document of 0 bytes length)<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsOutOfMemory<br />
|The total number of physical ReaderEngine conversions, that resulted in an out of memory error<br />
|Instance<br />
|<br />
|-<br />
|ConversionErrorsPDFTool<br />
|The total number of physical PDFTool conversions, that resulted in an error<br />
|Instance<br />
|<br />
|-<br />
|ErrorCacheHitRatio<br />
|The ratio of job errors that are retrieved from the errror cache against the total number of job errors as simple quotient<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTimeout<br />
|The total number of jobs, that returned with a timeout error<br />
|Instance<br />
|<br />
|-<br />
|JobErrorsTotal<br />
|The total number of jobs, that returned with an error<br />
|Instance<br />
|<br />
|-<br />
|JobsProcessed<br />
|The total number of jobs that have been processed<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianConversionTimeMillis_Total<br />
|The median time in milliseconds, a physical ReaderEngine conversion lasted, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianJobTimeMillis_Total<br />
|The median time in milliseconds, a job needed to complete, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Background<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Low<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Medium<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_High<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Instant<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|MedianQueueTimeMillis_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Background<br />
|The peak number of background priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Low<br />
|The peak number of low priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Medium<br />
|The peak number of medium priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_High<br />
|The peak number of high priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Instant<br />
|The peak number of instant priority jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInQueue_Total<br />
|The peak number of jobs in queue, measured from the beginning of the last reset/initialization on (default period: 5 minutes)<br />
|Instance<br />
|<br />
|-<br />
|PeakJobCountInAsyncQueue_Total<br />
|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)<br />
|Instance<br />
|<br />
|-<br />
|PendingStatefulJobCount<br />
|The number of stateful job conversions for that no endConvert has been called up to now<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountInstance<br />
|The accumulated number of times the job queue high limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountInstance<br />
|The accumulated number of times the job queue low limit has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitHighReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueLimitLowReachedCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountInstance<br />
|The accumulated number of times the job queue timeout has been reached for the current DocumentConverter server instance<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|QueueTimeoutCountLongTerm<br />
|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<br />
|Long term<br />
|From 7.10.3 on<br />
|-<br />
|RuntimeSecondsInstance<br />
|The runtime in seconds for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|RuntimeSecondsLongTerm<br />
|The accumulated runtime in seconds for all previously started DocumentConverter server instances and the current DocumentConverter server instance<br />
|Long term<br />
|<br />
|-<br />
|ScheduledJobCountInQueue<br />
|The current number of all scheduled, synchronous jobs within the queue, waiting to be processed<br />
|Instance<br />
|From 7.10.3 on<br />
|-<br />
|UserRequestCountInstance_Total<br />
|The number of all WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Text<br />
|The number of text document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Spreadsheet<br />
|The number of spreadsheet document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Presentation<br />
|The number of presentation document related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstance_Image<br />
|The number of image related WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Total<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountInstanceFailed_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestCountLongTermFailed_Image<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Total<br />
|The ratio of successful WebService requests against failed WebService requests, that have the user flag set to true, for the current DocumentConverter server instance<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Text<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Spreadsheet<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Presentation<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioInstance_Image<br />
|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<br />
|Instance<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Total<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Text<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Spreadsheet<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Presentation<br />
|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<br />
|Long term<br />
|<br />
|-<br />
|UserRequestSuccessRatioLongTerm_Image<br />
|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<br />
|Long term<br />
|<br />
|}<br />
<br />
Here is a list of sample data provided by<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -y -p 9998|sed -e 's/com.openexchange.documentconverter:name=DocumentConverterInformation,//g' | sort<br />
<br />
CacheEntryCount = 10258<br />
CacheFreeVolumeSize = 2709409792<br />
CacheHitRatio = 0.9642857142857143<br />
CacheOldestEntrySeconds = 1998029<br />
CachePersistentSize = 564215808<br />
ConversionCount = 1<br />
ConversionCountPDFTool = 0<br />
ConversionCountReaderEngine = 1<br />
ConversionCountWithMultipleRuns = 0<br />
ConversionErrorsDisposed = 0<br />
ConversionErrorsGeneral = 0<br />
ConversionErrorsNoContent = 0<br />
ConversionErrorsOutOfMemory = 0<br />
ConversionErrorsPassword = 1<br />
ConversionErrorsPDFTool = 0<br />
ConversionErrorsTimeout = 0<br />
ErrorCacheHitRatio = 0.0<br />
JobErrorsTimeout = 0<br />
JobErrorsTotal = 1<br />
JobsProcessed = 28<br />
MedianConversionTimeMillis_Background = 0<br />
MedianConversionTimeMillis_High = 0<br />
MedianConversionTimeMillis_Instant = 0<br />
MedianConversionTimeMillis_Low = 0<br />
MedianConversionTimeMillis_Medium = 0<br />
MedianConversionTimeMillis_Total = 0<br />
MedianJobTimeMillis_Background = 0<br />
MedianJobTimeMillis_High = 0<br />
MedianJobTimeMillis_Instant = 0<br />
MedianJobTimeMillis_Low = 0<br />
MedianJobTimeMillis_Medium = 0<br />
MedianJobTimeMillis_Total = 0<br />
MedianQueueTimeMillis_Background = 0<br />
MedianQueueTimeMillis_High = 0<br />
MedianQueueTimeMillis_Instant = 0<br />
MedianQueueTimeMillis_Low = 0<br />
MedianQueueTimeMillis_Medium = 0<br />
MedianQueueTimeMillis_Total = 0<br />
PeakJobCountInAsyncQueue_Total = 0<br />
PeakJobCountInQueue_Background = 0<br />
PeakJobCountInQueue_High = 0<br />
PeakJobCountInQueue_Instant = 0<br />
PeakJobCountInQueue_Low = 0<br />
PeakJobCountInQueue_Medium = 0<br />
PeakJobCountInQueue_Total = 0<br />
PendingStatefulJobCount = 0<br />
QueueLimitHighReachedCountInstance = 33<br />
QueueLimitHighReachedCountLongTerm = 66<br />
QueueLimitLowReachedCountInstance = 33<br />
QueueLimitLowReachedCountLongTerm = 66<br />
QueueTimeoutCountInstance = 22<br />
QueueTimeoutCountLongTerm = 44<br />
RuntimeSecondsInstance = 6707<br />
RuntimeSecondsLongTerm = 28607051<br />
ScheduledJobCountInQueue = 0<br />
UserRequestCountInstanceFailed_Image = 0<br />
UserRequestCountInstanceFailed_Presentation = 0<br />
UserRequestCountInstanceFailed_Spreadsheet = 0<br />
UserRequestCountInstanceFailed_Text = 0<br />
UserRequestCountInstanceFailed_Total = 0<br />
UserRequestCountInstance_Image = 0<br />
UserRequestCountInstance_Presentation = 0<br />
UserRequestCountInstance_Spreadsheet = 0<br />
UserRequestCountInstance_Text = 0<br />
UserRequestCountInstance_Total = 0<br />
UserRequestCountLongTermFailed_Image = 0<br />
UserRequestCountLongTermFailed_Presentation = 10694<br />
UserRequestCountLongTermFailed_Spreadsheet = 2598<br />
UserRequestCountLongTermFailed_Text = 6369<br />
UserRequestCountLongTermFailed_Total = 19661<br />
UserRequestCountLongTerm_Image = 0<br />
UserRequestCountLongTerm_Presentation = 121394<br />
UserRequestCountLongTerm_Spreadsheet = 33453<br />
UserRequestCountLongTerm_Text = 130801<br />
UserRequestCountLongTerm_Total = 285648<br />
UserRequestSuccessRatioInstance_Image = 1.0<br />
UserRequestSuccessRatioInstance_Presentation = 1.0<br />
UserRequestSuccessRatioInstance_Spreadsheet = 1.0<br />
UserRequestSuccessRatioInstance_Text = 1.0<br />
UserRequestSuccessRatioInstance_Total = 1.0<br />
UserRequestSuccessRatioLongTerm_Image = 1.0<br />
UserRequestSuccessRatioLongTerm_Presentation = 0.911906684020627<br />
UserRequestSuccessRatioLongTerm_Spreadsheet = 0.9223388036947359<br />
UserRequestSuccessRatioLongTerm_Text = 0.9513077117147423<br />
UserRequestSuccessRatioLongTerm_Total = 0.9311705315633227<br />
</pre><br />
<br />
=== OX Documentconverter and munin ===<br />
<br />
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.<br />
<br />
<pre><br />
[ox_documentconverter*]<br />
env.oxJolokiaUrl http://localhost:8008/monitoring/jolokia<br />
</pre><br />
<br />
== OX Documents ==<br />
<br />
Monitoring data for OX Documents can be obtained after installation of the package open-xchange-documents-monitoring.<br />
<br />
Here is a list of sample data provided by<br />
<br />
<pre><br />
# /opt/open-xchange/sbin/showruntimestats -f<br />
DocumentsSizeMedian_Spreadsheet = 0<br />
DocumentsCreated_Presentation = 2<br />
DocumentsCreated_Spreadsheet = 2<br />
RestoreDocCurrent = 40<br />
RestoreDocRestoredSuccess = 0<br />
RestoreDocRestoredFailure = 0<br />
DocumentsSizeMedian_Text = 0<br />
DocumentsSizeMedian_Presentation = 0<br />
RestoreDocCreated_Total = 40<br />
RestoreDocRemoved_Total = 0<br />
DocumentsSizeMedian_Total = 0<br />
DocumentsCreated_Total = 4<br />
DocumentsCreated_Text = 0<br />
DocumentsClosed_Text_Timeout = 0<br />
DocumentsSaved_Text_Total = 2<br />
DocumentsSaved_Text_Close = 2<br />
DocumentsSaved_Text_100ops = 0<br />
DocumentsSaved_Text_15mins = 0<br />
DocumentsOperations_Text_Incoming = 8<br />
DocumentsOperations_Text_Distributed = 0<br />
DocumentsOpened_Text_Total = 2<br />
DocumentsOpened_Text_OOXML = 1<br />
DocumentsOpened_Text_Binary = 0<br />
DocumentsOpened_Text_ODF = 1<br />
DocumentsClosed_Text_Total = 2<br />
DocumentsOpened_Spreadsheet_Total = 22<br />
DocumentsOpened_Spreadsheet_OOXML = 16<br />
DocumentsOpened_Spreadsheet_Binary = 0<br />
DocumentsOpened_Spreadsheet_ODF = 6<br />
DocumentsClosed_Spreadsheet_Total = 19<br />
DocumentsClosed_Spreadsheet_Timeout = 0<br />
DocumentsSaved_Spreadsheet_Total = 10<br />
DocumentsSaved_Spreadsheet_Close = 10<br />
DocumentsSaved_Spreadsheet_100ops = 0<br />
DocumentsSaved_Spreadsheet_15mins = 0<br />
DocumentsOperations_Spreadsheet_Incoming = 46<br />
DocumentsOperations_Spreadsheet_Distributed = 0<br />
</pre><br />
<br />
== DCS ==<br />
<br />
JMX and access via Jolikia is disabled by default.<br />
<br />
dcs.properties see documentation.open-xchange.com/...<br />
<br />
jmx.enabled=true<br />
and jmx credentials<br />
<br />
The DCS offers Spring Boot Actuator functionality for management and monitoring.<br />
By default endpoints are accessible. To allow access via jolokia the user credentials have to be configured.<br />
<br />
management.endpoints.web.exposure.include=*<br />
spring.security.user.name=ausername<br />
spring.security.user.password=thepass<br />
<br />
For details see<br />
https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/production-ready-endpoints.html<br />
<br />
== Further Reading ==<br />
<br />
Further details about accessing JMX data via Jolokia are described in an [[Jolokia_LoginCounter_HOWTO]].<br />
<br />
A call derived from this example for OX Documentconverter looks like<br />
<br />
<pre><br />
$ curl http://yourname:yourpassword@localhost:8008/monitoring/jolokia/read/com.openexchange.documentconverter:name=DocumentConverterInformation/JobsProcessed<br />
{"timestamp":1471868314,"status":200,"request":{"mbean":"com.openexchange.documentconverter:name=DocumentConverterInformation","attribute":"JobsProcessed","type":"read"},"value":6616}<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25101AppSuite:Documents Installation Guide2019-12-02T12:53:23Z<p>Stx12: </p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
For working websocket support Apache version 2.4.10 or newer is required.<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25099AppSuite:Documents Installation Guide2019-11-29T14:11:14Z<p>Stx12: link to 7.10.2</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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.5 and higher. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide_7103&diff=25098AppSuite:Documents Installation Guide 71032019-11-29T08:58:39Z<p>Stx12: redirect to main page</p>
<hr />
<div>#REDIRECT [[AppSuite:Documents Installation Guide]]</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25097AppSuite:Documents Installation Guide2019-11-29T08:57:18Z<p>Stx12: new content for 7.10.3</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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.5 and higher. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide&diff=25096AppSuite:Documents Installation Guide2019-11-29T08:53:50Z<p>Stx12: Stx12 moved page AppSuite:Documents Installation Guide to AppSuite:Documents Installation Guide 7.10.2 and earlier: to be replaced with new version for 7.10.3</p>
<hr />
<div>#REDIRECT [[AppSuite:Documents Installation Guide 7.10.2 and earlier]]</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide_7.10.2_and_earlier&diff=25095AppSuite:Documents Installation Guide 7.10.2 and earlier2019-11-29T08:53:49Z<p>Stx12: Stx12 moved page AppSuite:Documents Installation Guide to AppSuite:Documents Installation Guide 7.10.2 and earlier: to be replaced with new version for 7.10.3</p>
<hr />
<div>{{Version|7.8.3}}<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
Learn more about the highlights of OX Spreadsheet here: [http://software.open-xchange.com/products/appsuite/doc/OX_Spreadsheet_Product_Guide.pdf OX Spreadsheet Product Guide].<br />
<br />
<br />
== Requirements ==<br />
<br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
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).<br />
<br />
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.<br />
<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
=== Documents in Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre><br />
<br />
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.</div>Stx12https://www.oxpedia.org/wiki/index.php?title=AppSuite:Documents_Installation_Guide_7103&diff=25094AppSuite:Documents Installation Guide 71032019-11-28T17:41:53Z<p>Stx12: /* Requirements */</p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
= Download & Installation OX Documents =<br />
<br />
=== General Information ===<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
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.5 and higher. <br />
<br />
<br />
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).<br />
<br />
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.<br />
<br />
<!--<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately: <br />
<br />
* The Document Converter API: See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
--><br />
<br />
== Installation ==<br />
<br />
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:<br />
<br />
* <tt>open-xchange-file-distribution</tt><br />
* <tt>open-xchange-sessionstorage-hazelcast</tt><br />
<br />
The following Packages are no longer needed since 7.10.3<br />
* <tt>open-xchange-realtime-core</tt><br />
* <tt>open-xchange-realtime-json</tt><br />
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Debian GNU/Linux 9.0 (valid from v7.10) ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{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}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Documents Collaboration Service ==<br />
<br />
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.<br />
<br />
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.<br />
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.<br />
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.<br />
<br />
'''Note:</br><br />
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.'''<br />
<br />
=== Documents Collaboration Service (DCS) ===<br />
<br />
Prepare documents-collaboration repository as described above.<br />
<br />
The DCS will be installed via the package:<br />
<pre><br />
open-xchange-documents-collaboration<br />
</pre><br />
<br />
The target directory is <b>/usr/share/open-xchange-documents-collaboration</b><br />
<br />
The DCS configuration file is located at <b>/etc/documents-collaboration/dcs.properties</b>. 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]<br />
<br />
The following entries need to be reviewed and values need to be adjusted during the setup.<br><br />
Configure bind host IP and JMS Port to listen to<br />
<pre><br />
dcs.host = 192.168.10.25 # Interface of the DCS node<br />
dcs.port = 61616<br />
</pre> <br />
<br />
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:<br />
<br />
<pre><br />
db.host=192.168.10.172<br />
db.port=3306<br />
db.schema=dcsdb<br />
db.username=db_user<br />
db.password=db_password<br />
</pre><br />
<br />
After setting these database related properties within the <b>/etc/documents-collaboration/dcs.properties</b> file, the admin needs to call the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script as super user of the system. <br />
<br />
Database related settings made in the <b>/etc/documents-collaboration/dcs.properties</b> 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.<br />
<br />
If all database properties have been set correctly within the <b>/etc/documents-collaboration/dcs.properties</b> file, a valid call to the <b>/usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh</b> script is e.g. the following one:<br />
<br />
<pre><br />
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password<br />
</pre><br />
<br />
The default logging path is set in <b>/etc/documents-collaboration/logback-spring.xml</b> and points to <b>/var/log/open-xchange/documents-collaboration/documents-collaboration.log</b><br />
<br />
The Documents Collaboration Service will be started by executing the following comand:<br />
<pre><br />
systemctl start open-xchange-documents-collaboration.service<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
JMX access to the DCS can be enabled and configured in dcs.properties.<br />
By default it is disabled. To enable JMX change the appropriate line to<br />
<pre><br />
jmx.enabled=true<br />
</pre><br />
<br />
===Middleware node===<br />
<br />
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.<br />
<br />
Discovery of running DCSs is configured in file <b>/opt/open-xchange/etc/documents-collaboration-client.properties</b>.<br />
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):<br />
<pre><br />
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb<br />
com.openexchange.dcs.client.database.userName=db_user<br />
com.openexchange.dcs.client.database.password=db_password<br />
</pre><br />
<br />
A command line tool allows to check the values in the database<br />
<pre><br />
$ /opt/open-xchange/sbin/documents-collaboration-admin -l<br />
+---------------------+---------------+---------------+---------+<br />
| ID | Host | Interface | JMSPort |<br />
+---------------------+---------------+---------------+---------+<br />
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |<br />
+---------------------+---------------+---------------+---------+<br />
</pre><br />
<br />
===Apache configuration===<br />
<br />
The Apache module proxy_wstunnel has to be enabled:<br />
<pre><br />
a2enmod proxy_wstunnel<br />
</pre><br />
<br />
and the the following entries need to be added to the Apache configuration:<br />
<pre><br />
<Proxy balancer://oxcluster_ws><br />
Order Deny,Allow<br />
Allow from all<br />
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2<br />
</pre><br />
<br />
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.<br />
<br />
== Printing and legacy MS binary formats Editing ==<br />
<br />
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)<br />
<br />
* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]<br />
<br />
== Monitoring ==<br />
<br />
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.<br />
<br />
== Configuration ==<br />
<br />
=== Permissions ===<br />
<br />
To enable the OX Documents Applications for OX Drive the associated permission has to be set.<br />
<br />
The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.<br />
<br />
After installation the functionality is disabled:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
# com.openexchange.capability.text=true<br />
<br />
# Enables or disables the "spreadsheet" module capability globally.<br />
# com.openexchange.capability.spreadsheet=true<br />
<br />
# Enables or disables the "presentation" module capability globally.<br />
# com.openexchange.capability.presentation=true<br />
<br />
</pre><br />
<br />
The following line enables the functionality:<br />
<pre><br />
# Enables or disables the "text" module capability globally.<br />
com.openexchange.capability.text=true<br />
</pre><br />
<br />
Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':<br />
<pre><br />
permissions=textportaldisabled<br />
</pre><br />
<br />
=== Collaboration on shared documents ===<br />
<br />
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.<br />
<br />
in ''/opt/open-xchange/etc/sharing.properties'' <br />
<br />
<pre><br />
# Specifies whether guest sessions are treated as transient or not. Transient<br />
# sessions are only held in the short-term session containers, and are not put<br />
# into the distributed session storage. Defaults to "true".<br />
com.openexchange.share.transientSessions=false<br />
</pre><br />
<br />
com.openechange.share.transientSessions has to be set to false.<br />
<br />
=== Spell Checking===<br />
<br />
OX Text and OX Presentation use ''hunspell'' for spell checking functionality.<br />
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''<br />
with the following entry<br />
<pre><br />
# Determines whether online spelling is enabled for office documents.<br />
# Possible values: true|false<br />
# If this property is missing true is taken.<br />
io.ox/office//module/spellingEnabled=true<br />
</pre><br />
<br />
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)<br />
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. <br />
<br />
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...<br />
<br />
Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.<br />
The values for the shared library file and dictionary path have to be set according to the platform.<br />
<br />
This example shows the values for Debian:<br />
<br />
<pre><br />
# The name and location of the hunspell library<br />
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"<br />
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0<br />
# The location of the dictionaries<br />
# Default value: "/usr/share/hunspell"<br />
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell<br />
</pre><br />
<br />
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.<br />
<br />
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.<br />
<br />
=== Templates ===<br />
<br />
OX Documents support different levels to provide document templates for users.<br />
<br />
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 <br />
<br />
<pre><br />
# Defines the absolute path where document templates are located inside the local (!) file system.<br />
# The templates are displayed in the documents applications.<br />
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.<br />
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents<br />
</pre><br />
<br />
The content in the directory specified by the path must comply to the following rules:<br />
<br />
<pre><br />
/opt/open-xchange/templates/documents <br />
| <br />
----> text [application type]<br />
| | <br />
| ----> en-US [language-region]<br />
| | <br />
| ----> en [language fallback, en is also fallback for all other non-convered languages]<br />
| | <br />
| ----> de-DE<br />
| | <br />
| ----> de<br />
| | <br />
| ----> common [language independent, used in addition to the language specific ones]<br />
| <br />
----> spreadsheet<br />
| <br />
----> presentation<br />
</pre><br />
<br />
A context administrator can additionally provide global templates for all users in the same context.<br />
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.<br />
<br />
[[File:template-folder.png|border|600px|caption]]<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== OX Documents in Browser Tabs ===<br />
<br />
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.<br />
<br />
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml<br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
openInSingleTab: true<br />
</pre></div>Stx12