Zextras Docs
Introduction
Zextras Docs is based on a heavily customized LibreOffice online package allowing for collaborative editing of documents, spreadsheets and presentations straight from the Zimbra WebClient.
Warning
Zextras Docs is not compatible with Zimbra version 8.8.11 and lower.
Components
Zextras Docs Server
The Zextras Docs server is the heart of the service. The service hosts each document opened through a LibreOffice engine and responds to the client via an image upon every keystroke and change in the document.
Important
This component must be installed on one or more dedicated nodes running Ubuntu 16.04 LTS, Ubuntu 18.04 LTS or Red Hat Centos 7.
Zextras Docs Extension
The extension is the key component which coordinates everything. Its main tasks are:
Select which Docs server the next document will be opened on.
Redirect the client when it needs to open a document.
Read and write documents to and from system storage on behalf of the Docs server.
Connect to each Docs server via an administrative websocket and keep track of the availability and the resource usage of each.
Orchestrate concurrent user connections to the same document in the same server. (document sharing)
The Zextras Docs Extension is contained within the Zextras Core component of Zextras Suite.
Zextras Docs Zimlet
A Zextras Docs Zimlet handles the integration with Drive items and with email attachments. It is a thin web client which connects to a native server instance via websocket, renders a document and only sends changes to the client in order to keep the fidelity of the document on par with a desktop client while at the same time reducing the bandwidth to the bare minimum.
Documents in preview and attachments are shown in read-only mode with a simplified interface, while edit mode has a full interface.
Its main tasks are:
Change the “create” button in the ZWC to the related Docs feature.
Change the preview feature to use Docs.
Allow the preview of documents.
Minimum System Requirements
Following are the minimum system requirements to install Zextras Docs server:
Centos 7, Ubuntu 16.04, or Ubuntu 18.04
At least 2 CPU cores
At least 4 GB RAM
At least 4 GB free disk space
Browser compatibility
The following list shows which browsers are known to fully support all Zextras features.
Browser |
Version |
OS |
Supported |
---|---|---|---|
Microsoft Edge (Chromium) |
Latest |
Windows |
Yes |
Microsoft Edge (Chromium) |
Others |
Windows |
Limited |
Microsoft Edge (EdgeHTML) |
Any |
Windows |
No |
Internet Explorer |
Any |
Windows |
No |
Mozilla Firefox |
Latest |
Windows/Linux/OSX |
Yes |
Mozilla Firefox |
ESR |
Windows/Linux/OSX |
Yes |
Mozilla Firefox |
Others |
Windows/Linux/OSX |
Limited |
Google Chrome |
Latest |
Windows/Linux/OSX |
Yes |
Google Chrome |
Others |
Windows/Linux/OSX |
Limited |
Safari |
Latest |
OSX |
Yes |
Safari |
Others |
OSX |
Limited |
Items marked as “ Limited” are only supported on the browser’s two previous stable releases.
Document Management Flow
This is what happens “behind the scenes” when a user creates a new document:
The Zimlet prompts the Extension to create a new empty document
The Extension creates the document and returns the document’s ID to the client
The Zimlet opens a new Zimbra tab containing an iframe pointing towards ‘/service/extension/wopi-proxy’
The extension receives the request from the client, creates a new token for the needed document, and replies with a new url
The new url points toward
/docs/[docs-node-id]/[token]
, which will be proxied by nginx to the specific Docs Server nodeThe Docs Server will respond with the web application in Javascript
The web application opens a websocket connection, going through the nginx
Docs Server receives the websocket connection along with a token, sends a
read wopi
command towards the mailbox url indicated in the parameters (the url is validates against allowed nodes)The Extension validates the token and replies with information and content
The Docs Server node parses the document, renders it and sends it back to the client.
The document is fully opened and editable.
Open document
redirect to docs
+------------------------+ +----------------------+
| Zimbra Proxy | | Mailbox |
| +-------------> |
| Nginx | | Zextras Docs Extension|
+------------------------+ +----------------------+
| | ^
| | |
| | WOPI:
| Admin Web Read/Write
| Socket Documents
| | |
| | |
| | |
| +---v----------------+
| | |
+--------------------> Docs Server |
Load Client | |
Open client websocket +--------------------+
Networking and ports
All mailbox servers will need to be able to directly communicate with the Docs Server over port 8443 (HTTPS Backend), which must be open on both ends.
The Docs Server communicates with the Extension through port 9980, so incoming traffic from all mailbox and proxy servers to that port must be allowed. The Docs Server component must also be able to directly communicate with the master LDAP server as well as with all Proxy servers.
Installation and Configuration
Important
This component must be installed on one or more dedicated nodes running Ubuntu 16.04 LTS, Ubuntu 18.04 LTS or Red Hat Centos 7.
Docs Nodes
Download the zextras-docs.tgz
standalone installer for your
distribution (Centos 7
| Ubuntu 16
| Ubuntu 18),
extract it and as the root user execute the install.sh
script
contained in the package.
To obtain the information required for the initial Docs Server setup, run the following command on any mailbox server:
zimbra@mbx1:~$ zmlocalconfig -s ldap_master_url zimbra_ldap_user zimbra_ldap_userdn zimbra_ldap_password
This will return the info you need in the following format:
ldap_master_url = ldap://ldap01.cfd6a9e5.test.example.com:389
zimbra_ldap_user = zimbra
zimbra_ldap_userdn = uid=zimbra,cn=admins,cn=zimbra
zimbra_ldap_password = Deyked4ofMarj
The script will install the Zextras Docs package and then ask the
information about the master ldap, url, username and password, which
will be used to add a new server in the LDAP with just the ‘docs’
service installed/enabled. Every Docs Server will be visible by every
node, and will read the LDAP in order to write the configuration in
/opt/zimbra/conf/docs/loolwsd.xml
.
Once the setup is completed no other configuration is needed.
Docs Server download links
Adding Custom Fonts to the Docs Server
To add Custom Fonts to your Docs Server, simply copy the .ttf
font
files in the /opt/zimbra/docs/core/share/fonts/truetype/
directory,
then generate the new font cache and restart the docs server running
zdocs restart
as root
.
To generate the new font cache, run the following command based on the Docs Server’s Operating System:
dpkg-reconfigure zextras-docs-server
fc-cache /opt/zimbra/docs/zextras-docs-core/share/fonts
Warning
The server will briefly be unavailable during the restart, and clients will need to close and open again any open document to see the new fonts in the list.
Mailbox Nodes
While the Zextras Docs extension is already contained within Zextras Suite, the com_zextras_docs Zimlet needs to be deployed on the server and enabled on all users and COS that need to have access to the Zextras Docs features.
The com_zextras_docs
Zimlet can be deployed from the “Core” section
of the Zextras Adminictration Zimlet.
No configuration on the mailboxd side is needed after the Zimlet has been deployed and enabled.
Proxy Nodes
The proxy configuration must be re-generated after adding one or more
Zextras Docs Servers to the infrastructure: to do so, run
/opt/zimbra/libexec/zmproxyconfgen
as the zimbra user and then
restart the proxy service running zmproxyctl restart
as the same
user.
The new docs nodes will be read from ldap and no manual configuration is needed.
Licensing
Zextras Docs is included in every Zextras Suite Pro license..
The standalone installer is released under the MPLv2 license while the extension and Zimlet are released under a proprietary license.
Removal
Before uninstalling the software the node must be removed form LDAP either from the docs node via command:
zdocs remove-local-server
or via the zmprov command from any zimbra node:
zmprov deleteServer {servername}
Commands
Zextras Docs Server CLI - zdocs
On Docs server zdocs (/usr/local/bin/zdocs as root) command can generate the config for lool (it’s already on cron), add/remove the docs server from ldap, test configuration and manage the service.
``zdocs`` command.
usage: zdocs [-h] [--auto-restart] [--ldap-dn LDAP_DN] [--ldap-pass LDAP_PASS]
[--ldap-url LDAP_URL] [--hostname HOSTNAME] [--debug][--cron]
{genkey,write-local-server,remove-local-server,generate-config,ldap-write-config,ldap-test,start,stop,restart,status,setup}
Manage Zextras Docs service.
Available commands:
genkey Generate a private key needed for authentication between docs and mailbox servers.
write-local-server Add or update in LDAP the necessary server entry for this server in order to be reachable from other servers.
remove-local-server Remove local server entry in LDAP.
generate-config Populate the config template with ldap values and write a new configuration file.
ldap-write-config Write new configuration about the ldap access needed to generate the docs configuration file.
ldap-test Check the ldap connection.
start Start the service.
stop Stop the service.
restart Restart the service.
status Print service status.
setup Start the initial setup.
positional arguments:
{genkey,write-local-server,remove-local-server,generate-config,ldap-write-config,ldap-test,start,stop,restart,status,setup}
optional arguments:
-h, --help show this help message and exit
--auto-restart Automatically restart the service if configuration is changed (to be used with generate-config)
--ldap-dn LDAP_DN Ldap dn (distinguish name) to bind to (to be used with ldap-test and ldap-settings)
--ldap-pass LDAP_PASS Ldap password used of the DN (to be used with ldap-test and ldap-settings)
--ldap-url LDAP_URL Ldap url completed with schema (ex.: ldaps://ldap.example.com, to be used with ldap-test and ldap-settings)
--hostname HOSTNAME Hostname of this server (to be used with add-local-server)
--debug Show complete errors when things go bad.
--cron Start in cron mode, avoid any output unless there is an error (to be used with generate-config).
examples:
#regenerate the config and restart the server if config changed
zdocs --auto-restart generate-config
#restart the service
zdocs restart
#check ldap connection availability using current settings
zdocs ldap-test
#check ldap connection using custom settings
zdocs --ldap-url ldaps://ldap.example.com/ --ldap-dn 'uid=zimbra,cn=admins,cn=zimbra' --ldap-pass password ldap-test
#change the ldap connection settings
zdocs --ldap-url ldap://ldap2.example.com/ --ldap-dn 'uid=zimbra,cn=admins,cn=zimbra' --ldap-pass password
ldap-write-config
#add the local server
zdocs write-local-server
#add the local server with a custom hostname in LDAP, this command should be already invoked during setup.
zdocs --hostname myhostname write-local-server
#remove the local server from LDAP, useful when destroying the server, you can also use 'zmprov deleteServer' from a mailbox server.
zdocs remove-local-server
Zextras Docs Extension CLI - zxsuite docs
On a Mailbox server, the zxsuite docs
command is available. This
command allows to check and control the Docs service’s status, to
force a configuration reload and to see the Docs Servers’
status. Please refer to section Zextras Docs CLI.
Troubleshooting
Nothing happens when opening a document / extension requests returns 503
This is most likely due to a connection issue between the
mailbox server and the Docs server. Check the mailbox.log
and see the reason for the connection failure. If there are no
connection errors, check the Docs server with zdocs status
on the docs node.
The mailbox will log every connection and disconnection for each Docs server.
404 error code instead of docs
The proxy configuration needs to be re-generated and the proxy restarted
Docs opens but a message “this is embarrassing…” appears instead of the document
This happens if the Docs server cannot connect back to the mailbox server to read and write the document. Check name resolution and SSL certificate of mailboxd which must be valid for the Docs server that does not inherit Zimbra certificate management.
Zextras Docs CLI
This section contains the index of all zxsuite docs
commands. Full
reference can be found in the dedicated section
ZxDocs CLI Commands.
doDeployDocsZimlet doReloadConfig doRestartService doStartService doStopService getServices status