mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-03 10:20:02 +07:00
Merge pull request #7871 from nextcloud/enh/office
Nextcloud Office documentation
This commit is contained in:
Julius Härtl
@@ -15,6 +15,7 @@ Table of contents
|
||||
configuration_files/index
|
||||
file_workflows/index
|
||||
groupware/index
|
||||
office/index
|
||||
configuration_database/index
|
||||
configuration_mimetypes/index
|
||||
maintenance/index
|
||||
|
||||
BIN
admin_manual/images/office.png
Normal file
BIN
admin_manual/images/office.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 115 KiB |
62
admin_manual/office/configuration.rst
Normal file
62
admin_manual/office/configuration.rst
Normal file
@@ -0,0 +1,62 @@
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Nextcloud Office App Settings
|
||||
=============================
|
||||
|
||||
Collabora Online Server
|
||||
***********************
|
||||
|
||||
URL (and port) of the Collabora Online server that provides the editing functionality as a WOPI client. Collabora Online should use the same protocol (http:// or https://) as the server installation. Naturally, https:// is recommended.
|
||||
|
||||
Restrict usage to specific groups
|
||||
By default the app is enabled for all. When this setting is active, only members of specified groups can use Nextcloud Office.
|
||||
|
||||
Restrict edit to specific groups
|
||||
********************************
|
||||
By default all users can edit documents with Nextcloud Office. When this setting is active, only the members of specified groups can edit, others can only view documents.
|
||||
|
||||
Use OOXML by default for new files
|
||||
**********************************
|
||||
By default new files created by users are in OpenDocument Format (ODF). When this setting is active, new files will be created in Office Open XML (OOXML) format.
|
||||
|
||||
Enable access for external apps
|
||||
*******************************
|
||||
Nextcloud internally passes an access token to Collabora Online that is used later by it to do various operations. By default, it's not possible to generate this token by 3rd parties; only Nextcloud can generate and pass it to Collabora Online.
|
||||
|
||||
In some applications, it might be necessary to generate the token by a 3rd party application. For this, one needs to add the 3rd party application (external apps) in this setting. You need to add an application identifier and a secret
|
||||
token. These credentials then can be used by the 3rd party application to make calls to `wopi/extapp/data/{fileId}` to fetch the access token and URL source for given fileId, both required to open a connection to Collabora Online.
|
||||
|
||||
Canonical webroot
|
||||
*****************
|
||||
Canonical webroot, in case there are multiple, for Collabora Online to use. Provide the one with least restrictions. E.g.: Use non-shibbolized webroot if this instance is accessed by both shibbolized and non-shibbolized webroots. You can ignore this setting if only one webroot is used to access this instance.
|
||||
|
||||
|
||||
Additional configuration options
|
||||
================================
|
||||
|
||||
The coolwsd service allows additional configuration options which can be found in the `Collabora Online documentation <https://sdk.collaboraonline.com/docs/installation/Configuration.html>`_.
|
||||
|
||||
Previews
|
||||
********
|
||||
|
||||
In order to allow Nextcloud to use the coolwsd conversion API to generate previews, the Nextcloud host IP needs to be added to the allow list:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo coolconfig set net.post_allow.host 10.0.0.4
|
||||
|
||||
|
||||
Custom fonts
|
||||
************
|
||||
|
||||
When you install coolwsd package, the post-install script will look for additional fonts on your system, and install them in the systemplate. If you install fonts to your system after installing coolwsd, you need to update the systemplate manually.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
coolconfig update-system-template
|
||||
|
||||
|
||||
.. seealso::
|
||||
https://sdk.collaboraonline.com/docs/installation/Fonts.html
|
||||
129
admin_manual/office/example-docker.rst
Normal file
129
admin_manual/office/example-docker.rst
Normal file
@@ -0,0 +1,129 @@
|
||||
================================
|
||||
Installation example with Docker
|
||||
================================
|
||||
|
||||
We'll describe how to get Nextcloud Office running on your server and how to integrate it into your Nextcloud using the docker image Nextcloud and Collabora built.
|
||||
|
||||
|
||||
To install it the following dependencies are required:
|
||||
|
||||
- A host that can run a Docker container
|
||||
- A subdomain or a second domain that the Collabora Online server can run on
|
||||
- An Apache server with some enabled modules
|
||||
- A valid SSL certificate for the domain that Collabora Online should run on
|
||||
- A valid SSL certificate for your Nextcloud
|
||||
|
||||
|
||||
Install the Collabora Online server
|
||||
**************************************
|
||||
|
||||
The following steps will download the Collabora Online docker. Make sure to replace "cloud.example.com" with the host that your own Nextcloud runs on. Also make sure to escape all dots with double backslashes (`\\`), since this string will be evaluated as a regular expression (and your bash 'eats' the first backslash.) If you want to use the docker container with more than one Nextcloud, you'll need to use `domain=cloud\\.nextcloud\\.com\|second\\.nextcloud\\.com` instead. (All hosts are separated by `\|`.)
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker pull collabora/code
|
||||
docker run -t -d -p 127.0.0.1:9980:9980 \
|
||||
-e 'domain=cloud\\.example\\.com' \
|
||||
--restart always \
|
||||
--cap-add MKNOD \
|
||||
collabora/code
|
||||
|
||||
That will be enough. Once you have done that the server will listen on "localhost:9980". Now we just need to configure the locally installed Apache reverse proxy.
|
||||
|
||||
Install the Apache reverse proxy
|
||||
***********************************
|
||||
|
||||
On a recent Ubuntu or Debian this should be possible using:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
apt-get install apache2
|
||||
a2enmod proxy proxy_wstunnel proxy_http ssl
|
||||
|
||||
Afterward, configure one VirtualHost properly to proxy the traffic. For security reason we recommend to use a subdomain such as office.example.com instead of running on the same domain. An example config can be found below:
|
||||
|
||||
.. code-block:: apache2
|
||||
|
||||
########################################
|
||||
# Reverse proxy for Collabora Online
|
||||
########################################
|
||||
|
||||
AllowEncodedSlashes NoDecode
|
||||
SSLProxyEngine On
|
||||
ProxyPreserveHost On
|
||||
|
||||
# cert is issued for collaboraonline.example.com and we proxy to localhost
|
||||
SSLProxyVerify None
|
||||
SSLProxyCheckPeerCN Off
|
||||
SSLProxyCheckPeerName Off
|
||||
|
||||
# static html, js, images, etc. served from coolwsd
|
||||
# browser is the client part of Collabora Online
|
||||
ProxyPass /browser https://127.0.0.1:9980/browser retry=0
|
||||
ProxyPassReverse /browser https://127.0.0.1:9980/browser
|
||||
|
||||
# WOPI discovery URL
|
||||
ProxyPass /hosting/discovery https://127.0.0.1:9980/hosting/discovery retry=0
|
||||
ProxyPassReverse /hosting/discovery https://127.0.0.1:9980/hosting/discovery
|
||||
|
||||
# Capabilities
|
||||
ProxyPass /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities retry=0
|
||||
ProxyPassReverse /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities
|
||||
|
||||
# Main websocket
|
||||
ProxyPassMatch "/cool/(.*)/ws$" wss://127.0.0.1:9980/cool/$1/ws nocanon
|
||||
|
||||
# Admin Console websocket
|
||||
ProxyPass /cool/adminws wss://127.0.0.1:9980/cool/adminws
|
||||
|
||||
# Download as, Fullscreen presentation and Image upload operations
|
||||
ProxyPass /cool https://127.0.0.1:9980/cool
|
||||
ProxyPassReverse /cool https://127.0.0.1:9980/cool
|
||||
# Compatibility with integrations that use the /lool/convert-to endpoint
|
||||
ProxyPass /lool https://127.0.0.1:9980/cool
|
||||
ProxyPassReverse /lool https://127.0.0.1:9980/cool
|
||||
|
||||
|
||||
After configuring these do restart your apache using ``systemctl restart apache2``.
|
||||
|
||||
.. seealso::
|
||||
Full configuration examples for reverse proxy setup can be found in the Collabora Online documentation:
|
||||
https://sdk.collaboraonline.com/docs/installation/Proxy_settings.html
|
||||
|
||||
|
||||
Configure the app in Nextcloud
|
||||
*********************************
|
||||
|
||||
Go to the Apps section and choose "Office & text"
|
||||
Install the "Collabora Online app"
|
||||
Admin -> Office -> Specify the server you have setup before (e.g. "https://office.example.com")
|
||||
Congratulations, your Nextcloud has Collabora Online Office integrated!
|
||||
|
||||
|
||||
Updating
|
||||
********
|
||||
|
||||
Occasionally, new versions of this docker image are released with security and feature updates. We will of course let you know when that happens! This is how you upgrade to a new version:
|
||||
|
||||
Update the docker image:
|
||||
.. code-block:: bash
|
||||
|
||||
docker pull collabora/code
|
||||
|
||||
List running docker containers:
|
||||
.. code-block:: bash
|
||||
|
||||
docker ps
|
||||
|
||||
Stop and remove the Collabora Online container with the container id of the running one:
|
||||
.. code-block:: bash
|
||||
|
||||
docker stop CONTAINER_ID
|
||||
docker rm CONTAINER_ID
|
||||
|
||||
Start the new container:
|
||||
.. code-block:: bash
|
||||
|
||||
docker run -t -d -p 127.0.0.1:9980:9980 -e 'domain=cloud\\.example\\.com' \
|
||||
--restart always --cap-add MKNOD collabora/code
|
||||
|
||||
50
admin_manual/office/example-ubuntu.rst
Normal file
50
admin_manual/office/example-ubuntu.rst
Normal file
@@ -0,0 +1,50 @@
|
||||
====================================
|
||||
Installation example on Ubuntu 20.04
|
||||
====================================
|
||||
|
||||
Import signing keys:
|
||||
********************
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd /usr/share/keyrings && sudo wget https://collaboraoffice.com/downloads/gpg/collaboraonline-release-keyring.gpg
|
||||
|
||||
Add repository:
|
||||
***************
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo echo "deb https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-ubuntu2004 ./" > /etc/apt/sources.list.d/collaboraonline.sources
|
||||
|
||||
Install packages
|
||||
****************
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt update && sudo apt install coolwsd code-brand
|
||||
|
||||
Configuration
|
||||
*************
|
||||
|
||||
Edit /etc/coolwsd/coolwsd.xml. Collabora Online (coolwsd) service runs via systemd. After editing the configuration file, you have to restart the service:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl restart coolwsd
|
||||
|
||||
The default configuration is looking for an SSL certificate and key, which are not present, so probably it’s the best to disable SSL, and optionally enable SSL termination, then set up the reverse proxy.
|
||||
|
||||
.. seealso::
|
||||
Full configuration examples for reverse proxy setup can be found in the Collabora Online documentation:
|
||||
https://sdk.collaboraonline.com/docs/installation/Proxy_settings.html
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo coolconfig set ssl.enable false
|
||||
sudo coolconfig set ssl.termination true
|
||||
sudo coolconfig set storage.wopi.host nextcloud.example.com
|
||||
sudo coolconfig set-admin-password
|
||||
sudo systemctl restart coolwsd
|
||||
systemctl status coolwsd
|
||||
|
||||
25
admin_manual/office/index.rst
Normal file
25
admin_manual/office/index.rst
Normal file
@@ -0,0 +1,25 @@
|
||||
===============
|
||||
Office
|
||||
===============
|
||||
|
||||
.. image:: ../images/office.png
|
||||
|
||||
Nextcloud Office supports editing your documents in real time with multiple other editors, showing high fidelity, WYSIWYG rendering and preserving the layout and formatting of your documents.
|
||||
|
||||
Users can insert and reply to comments and invite others without a Nextcloud account for anonymous editing of files with a public link shared folder.
|
||||
|
||||
Nextcloud Office supports dozens of document formats including DOC, DOCX, PPT, PPTX, XLS, XLSX + ODF, Import/View Visio, Publisher and many more...
|
||||
|
||||
Nextcloud Office is based on the Collabora Online Development Edition (CODE) and is available free and under heavy development, adding features and improvements all the time! Enterprise users have access to the more stable, scalable Collabora Online Enterprise based version through a `Nextcloud support subscription <https://nextcloud.com/enterprise/>`_.
|
||||
|
||||
We are able to provide a solution for Online Office for the entire Nextcloud community through our partnership with Collabora with various deployment options. Enterprise users looking for a more reliable solution should contact Nextcloud Sales.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:includehidden:
|
||||
|
||||
installation
|
||||
configuration
|
||||
migration
|
||||
troubleshooting
|
||||
42
admin_manual/office/installation.rst
Normal file
42
admin_manual/office/installation.rst
Normal file
@@ -0,0 +1,42 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Nextcloud Office is built on Collabora Online which requires a dedicated service running next to the Nextcloud webserver stack. There are several ways to run the coolwsd service.
|
||||
|
||||
- **Nextcloud All In One:** Nextcloud Office comes preinstalled out of the box in the `Nextcloud All In One <https://github.com/nextcloud/all-in-one>`_ setup and provides easy deployment and maintenance with most features included in this one Nextcloud instance.
|
||||
|
||||
For manual installations there are multiple options to get Nextcloud Office deployed:
|
||||
|
||||
- **Installation through distribution packages**
|
||||
There are packages for all major Linux distributions available which allow deploying a Collabora Online server through installing it through the regular package management. For an example installation guide on Ubuntu, see see: :doc:`example-ubuntu`
|
||||
|
||||
.. seealso::
|
||||
https://www.collaboraoffice.com/code/linux-packages/
|
||||
https://sdk.collaboraonline.com/docs/installation/index.html
|
||||
|
||||
|
||||
- **Installation through Docker**
|
||||
Docker images are available for deploying the Collabora Online server in container environments. For a detailed step by step guide, see: :doc:`example-docker`
|
||||
|
||||
.. seealso::
|
||||
https://sdk.collaboraonline.com/docs/installation/CODE_Docker_image.html
|
||||
|
||||
|
||||
- **Built-in CODE server**
|
||||
This app provides a built-in server with all of the document editing features of Collabora Online. Easy to install, for personal use or for small teams. A bit slower than a standalone server and without the advanced scalability features. Installation can be performed by enabling the according Nextcloud app. Further details can be found in the `app documentation <https://github.com/CollaboraOnline/richdocumentscode>`_.
|
||||
|
||||
.. note::
|
||||
This is the default option which works out of the box in most scenarios, however for improved performance it is highly recommended to switch to a dedicated Collabora Online installation using one of the other options.
|
||||
|
||||
|
||||
.. note::
|
||||
In most scenarios running a dedicated Collabora Online server will require some sort of reverse proxy to be setup in front of it. For more details see :doc:`proxy`.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
example-ubuntu
|
||||
example-docker
|
||||
proxy
|
||||
39
admin_manual/office/migration.rst
Normal file
39
admin_manual/office/migration.rst
Normal file
@@ -0,0 +1,39 @@
|
||||
===============================
|
||||
Migration from Collabora Online
|
||||
===============================
|
||||
|
||||
Nextcloud Office is based on Collabora Online so for enabling all Nextcloud Office functionality it would be enough to update to the most recent release. Nextcloud Office is available since CODE 21.11.
|
||||
|
||||
.. note::
|
||||
This upgrade guide is aimed for upgrading from CODE 6.4 to CODE 21.11.
|
||||
|
||||
Update the reverse proxy configuration
|
||||
**************************************
|
||||
|
||||
Due to naming changes in the Collabora Online releases it may be required to adjust reverse proxy configurations that are already in use for previously existing setups.
|
||||
|
||||
- Paths with ``lool`` have been renamed to ``cool``
|
||||
- Paths with ``loleaflet`` have been renamed to ``browser``
|
||||
|
||||
Fully detailed reverse proxy configration guides for various solutions can be found at https://sdk.collaboraonline.com/docs/installation/Proxy_settings.html
|
||||
|
||||
Upgrade distribution packages
|
||||
*****************************
|
||||
|
||||
- The main service has been renamed from ``loolwsd`` to ``coolwsd``
|
||||
- The service rename also affects the location of the configuration file ``/etc/coolwsd/coolwsd.xml``
|
||||
|
||||
Required upgrade steps:
|
||||
|
||||
- Stop the ``loolwsd`` service
|
||||
- Backup ``/etc/loolwsd/loolwsd.xml`` configuration file.
|
||||
- Remove ``loolwsd`` and ``collaboraoffice*`` packages.
|
||||
- Change the version number in the repository URL, e.g. from 6.4 to 21.11
|
||||
- Install the ``coolwsd`` package
|
||||
- Adapt the new configuration file in ``/etc/coolwsd/coolwsd.xml`` to match your previous configuration
|
||||
- Start and enable the ``coolwsd`` service
|
||||
|
||||
Upgrade the docker image
|
||||
************************
|
||||
|
||||
For upgrading the docker images it is enough to pull the latest CODE image from Docker Hub.
|
||||
18
admin_manual/office/proxy.rst
Normal file
18
admin_manual/office/proxy.rst
Normal file
@@ -0,0 +1,18 @@
|
||||
=============
|
||||
Reverse proxy
|
||||
=============
|
||||
|
||||
The server part of Nextcloud Office (coolwsd daemon) is listening on port 9980 by default, and clients should be able to communicate with it through port 9980. However on most setups it is common to use a reverse proxy to more easily handle SSL termination and have a unified entrypoint for HTTP requests.
|
||||
|
||||
THe following rules should be in place to forward requests to the coolwsd daemon on port 9980:
|
||||
|
||||
- /browser
|
||||
- /hosting/discovery
|
||||
- /hosting/capabilities
|
||||
- /cool/adminws
|
||||
- /cool
|
||||
- Web socket connections through /cool/(.*)/ws
|
||||
|
||||
.. seealso::
|
||||
Full configuration examples can be found in the Collabora Online documentation:
|
||||
https://sdk.collaboraonline.com/docs/installation/Proxy_settings.html
|
||||
41
admin_manual/office/troubleshooting.rst
Normal file
41
admin_manual/office/troubleshooting.rst
Normal file
@@ -0,0 +1,41 @@
|
||||
===============
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
In case of connectivity issues, ensure that the following required connections are possible and not blocked by any firewall:
|
||||
|
||||
- The users browser can reach both the Nextcloud Server as well as the Collabora Online server through HTTP(S)
|
||||
- The Nextcloud and the Collabora Online server are using the same protocol
|
||||
- The Nextcloud server can reach the Collabora Online server through HTTP(S)
|
||||
- The Collabora Online server can reach the Nextcloud server through HTTP(S)
|
||||
|
||||
Both the Nextcloud log as well as the Collabora Online server log may reveal more detailed error messages in case of connection issues.
|
||||
|
||||
- Verify connectivity from the browser:
|
||||
- https://office.example.com/hosting/capabilities
|
||||
- https://office.example.com/hosting/discovery
|
||||
- Verify connectivity from Nextcloud
|
||||
- ``curl https://office.example.com/hosting/capabilities``
|
||||
- ``curl https://office.example.com/hosting/discovery``
|
||||
- Verify connection from the Collabora server
|
||||
- ``curl https://nextcloud.example.com/status.php``
|
||||
|
||||
Frequently asked questions
|
||||
==========================
|
||||
|
||||
Issue: I get connection errors when trying to open documents
|
||||
Be sure to check the error log from docker through ``docker logs container-id``. If the logs note something like:
|
||||
``No acceptable WOPI hosts found matching the target host [YOUR NEXTCLOUD DOMAIN] in config.``
|
||||
Unauthorized WOPI host. Please try again later and report to your administrator if the issue persists. You might have started the docker container with the wrong URL. Be sure to triplecheck that you start it with the URL of your Nextcloud server, not the server where Collabora Online runs on.
|
||||
|
||||
Issue: Connection is not allowed errors.
|
||||
It is possible your firewall is blocking connections. Try to start docker after you started the firewall, it makes changes to your iptables to enable Collabora Online to function.
|
||||
|
||||
Issue: We are sorry, this is an unexpected connection error. Please try again. error.
|
||||
The Collabora Online app doesn't work at the moment, if you enable it only for certain groups. Remove the group filter in the App section.
|
||||
|
||||
Issue: Collabora Online doesn't handle my 100 users.
|
||||
This docker image is designed for home usage. If you need a more scalable solution, consider a support subscription for a reliable, business-ready online office experience.
|
||||
|
||||
Issue: Collabora Online doesn't work with Encryption.
|
||||
Yes, this is currently unsupported.
|
||||
Reference in New Issue
Block a user