AppSuite:Documents Installation Guide
For earlier versions see Guide for 7.10.2
Download & Installation OX Documents
General Information
OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.
Requirements
See the Open-Xchange software requirements page for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.
OX Documents needs to be installed in an OX App Suite configuration with a backend based on Grizzly (including hazelcast as installed and activated by default).
For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.
Installation
The OX Documents deployment consists of the packages open-xchange-documents-backend and open-xchange-documents-ui. The open-xchange-documents-backend package also requires and installs these packages:
- open-xchange-file-distribution
- open-xchange-sessionstorage-hazelcast
The following Packages are no longer needed since 7.10.3
- open-xchange-realtime-core
- open-xchange-realtime-json
Furthermore all open-xchange-realtime-* packages will be replaced with empty transitive packages to remove relicts of the realtime framework.
The package open-xchange-documents-collaboration has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).
Redhat Enterprise Linux 6 or CentOS 6
Add the following repositories to your Open-Xchange yum configuration:
[open-xchange-office] name=Open-Xchange-office baseurl=https://software.open-xchange.com/products/appsuite/stable/office/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-office-web] name=Open-Xchange-office-web baseurl=https://software.open-xchange.com/products/appsuite/stable/office-web/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documentconverter-api] name=Open-Xchange-documentconverter-api baseurl=https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documents-collaboration] name=Open-Xchange-documents-collaboration baseurl=https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
[open-xchange-office-updates] name=Open-Xchange-office-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-office-web-updates] name=Open-Xchange-office-web-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documentconverter-api-updates] name=Open-Xchange-documentconverter-api-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documents-collaboration-updates] name=Open-Xchange-documents-collaboration-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/updates/RHEL6/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration
Note:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.
Redhat Enterprise Linux 7 or CentOS 7
Add the following repositories to your Open-Xchange yum configuration:
[open-xchange-office] name=Open-Xchange-office baseurl=https://software.open-xchange.com/products/appsuite/stable/office/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-office-web] name=Open-Xchange-office-web baseurl=https://software.open-xchange.com/products/appsuite/stable/office-web/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documentconverter-api] name=Open-Xchange-documentconverter-api baseurl=https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documents-collaboration] name=Open-Xchange-documents-collaboration baseurl=https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
[open-xchange-office-updates] name=Open-Xchange-office-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-office-web-updates] name=Open-Xchange-office-web-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documentconverter-api-updates] name=Open-Xchange-documentconverter-api-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[open-xchange-documents-collaboration-updates] name=Open-Xchange-documents-collaboration-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration
Debian GNU/Linux 9.0 (valid from v7.10)
Add the following repositories to your Open-Xchange apt configuration:
deb https://software.open-xchange.com/products/appsuite/stable/office/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/office-web/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/DebianStretch /
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/DebianStretch /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/DebianStretch /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/DebianStretch /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/DebianStretch /
$ apt-get update $ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration
Debian GNU/Linux 10.0 (valid from v7.10.3)
Add the following repositories to your Open-Xchange apt configuration:
deb https://software.open-xchange.com/products/appsuite/stable/office/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/office-web/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/DebianBuster /
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/DebianBuster /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/DebianBuster /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/DebianBuster /
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/updates/DebianBuster /
$ apt-get update $ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration
SUSE Linux Enterprise Server 12
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/office/SLE_12 office
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/office-web/SLE_12 office-web
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/documentconverter-api/SLE_12 documentconverter-api
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/documents-collaboration/SLE_12 documents-collaboration
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office/updates/SLE_12 office-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/office-web/updates/SLE_12 office-web-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documentconverter-api/updates/SLE_12 documentconverter-api-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/documents-collaboration/SLE_12 documents-collaboration
$ zypper ref $ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration
Univention Corporate Server
OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.
Documents Collaboration Service
Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.
The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments. The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered. The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.
Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.
Documents Collaboration Service (DCS)
Prepare documents-collaboration repository as described above.
The DCS will be installed via the package:
open-xchange-documents-collaboration
The target directory is /usr/share/open-xchange-documents-collaboration
The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this page
The following entries need to be reviewed and values need to be adjusted during the setup.
Configure bind host IP and JMS Port to listen to
dcs.host = 192.168.10.25 # Interface of the DCS node dcs.port = 61616
A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.
Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item advertiseURL can be set to the name of the DCS node.
dcs.advertiseURL=dcs.example.com:61616
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
192.168.10.25 dcs.example.com
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:
db.host=192.168.10.172 db.port=3306 db.schema=dcsdb db.username=db_user db.password=db_password
After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.
Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.
If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log
The Documents Collaboration Service will be started by executing the following comand:
sudo systemctl start open-xchange-documents-collaboration.service
A command line tool allows to check the values in the database
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l +---------------------+---------------+---------------+---------+ | ID | Host | Interface | JMSPort | +---------------------+---------------+---------------+---------+ | 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 | +---------------------+---------------+---------------+---------+
JMX access to the DCS can be enabled and configured in dcs.properties. By default it is disabled. To enable JMX change the appropriate line to
jmx.enabled=true
Middleware node
No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.
Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties. Add the appropriate values to access the dcsdb Database as previously set during the DCS configuration (see above):
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb com.openexchange.dcs.client.database.userName=db_user com.openexchange.dcs.client.database.password=db_password
A command line tool allows to check the values in the database
$ /opt/open-xchange/sbin/documents-collaboration-admin -l +---------------------+---------------+---------------+---------+ | ID | Host | Interface | JMSPort | +---------------------+---------------+---------------+---------+ | 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 | +---------------------+---------------+---------------+---------+
Apache configuration
For working websocket support Apache version 2.4.10 or newer is required.
The Apache module proxy_wstunnel has to be enabled:
a2enmod proxy_wstunnel
and the the following entries need to be added to the Apache configuration:
<Proxy balancer://oxcluster_ws> Order Deny,Allow Allow from all BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1 ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On SetEnv proxy-initial-not-pooled SetEnv proxy-sendchunked </Proxy> ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.
Monitoring
OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This article guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.
Printing and legacy MS binary formats Editing
For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)
Configuration
Permissions
To enable the OX Documents Applications for OX Drive the associated permission has to be set.
The default setting for all users is changed in the file documents.properties in the directory /opt/open-xchange/etc.
After installation the functionality is disabled:
# Enables or disables the "text" module capability globally. # com.openexchange.capability.text=true # Enables or disables the "spreadsheet" module capability globally. # com.openexchange.capability.spreadsheet=true # Enables or disables the "presentation" module capability globally. # com.openexchange.capability.presentation=true
The following line enables the functionality:
# Enables or disables the "text" module capability globally. com.openexchange.capability.text=true
Starting with 7.6.2, you can disable the text portal app. In permissions.properties:
permissions=textportaldisabled
If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.
in /opt/open-xchange/etc/sharing.properties
# Specifies whether guest sessions are treated as transient or not. Transient # sessions are only held in the short-term session containers, and are not put # into the distributed session storage. Defaults to "true". com.openexchange.share.transientSessions=false
com.openechange.share.transientSessions has to be set to false.
Spell Checking
OX Text and OX Presentation use hunspell for spell checking functionality. By default Spellchecking is enabled in /opt/open-xchange/etc/settings/office.properties with the following entry
# Determines whether online spelling is enabled for office documents. # Possible values: true|false # If this property is missing true is taken. io.ox/office//module/spellingEnabled=true
After installation of the hunspell package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below) Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.
Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...
Spell checking has to be configured in the file /opt/open-xchange/etc/hunspell.properties. The values for the shared library file and dictionary path have to be set according to the platform.
This example shows the values for Debian:
# The name and location of the hunspell library # Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0" com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0 # The location of the dictionaries # Default value: "/usr/share/hunspell" com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.
If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.
Templates
OX Documents support different levels to provide document templates for users.
A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file
# Defines the absolute path where document templates are located inside the local (!) file system. # The templates are displayed in the documents applications. # If this property is missing a default '/opt/open-xchange/templates/documents' is taken. io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
The content in the directory specified by the path must comply to the following rules:
/opt/open-xchange/templates/documents | ----> text [application type] | | | ----> en-US [language-region] | | | ----> en [language fallback, en is also fallback for all other non-convered languages] | | | ----> de-DE | | | ----> de | | | ----> common [language independent, used in addition to the language specific ones] | ----> spreadsheet | ----> presentation
A context administrator can additionally provide global templates for all users in the same context. If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.
Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.
For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see here for different installation modes.
OX Documents in Browser Tabs
OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.
To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
# Override certain settings
default:
host: all
openInSingleTab: true