Apply suggestions from code reviewenh/office

Co-authored-by: Jonas <jonas@nextcloud.com>
Signed-off-by: Julius Härtl <jus@bitgrid.net>

6 files changed, 98 insertions, 84 deletions

diff --git a/admin_manual/office/example-docker.rst b/admin_manual/office/example-docker.rst
index a9de552b1..7391c410a 100644
--- a/admin_manual/office/example-docker.rst
+++ b/admin_manual/office/example-docker.rst
@@ -14,10 +14,12 @@ To install it the following dependencies are required:
 - A valid SSL certificate for your Nextcloud
 
 
-1. Install the Collabora Online server
+Install the Collabora Online server
 **************************************
 
-The following steps will download the Collabora Online docker, make sure to replace "cloud.nextcloud.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 \|.)
+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 \
@@ -28,7 +30,7 @@ The following steps will download the Collabora Online docker, make sure to repl
 
 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.
 
-2. Install the Apache reverse proxy
+Install the Apache reverse proxy
 ***********************************
 
 On a recent Ubuntu or Debian this should be possible using:
@@ -42,57 +44,54 @@ Afterward, configure one VirtualHost properly to proxy the traffic. For security
 
 .. code-block:: apache2
 
-    <VirtualHost *:443>
-        ServerName office.example.com:443
-
-        # SSL configuration, you may want to take the easy route instead and use Lets Encrypt!
-        SSLEngine on
-        SSLCertificateFile /path/to/signed_certificate
-        SSLCertificateChainFile /path/to/intermediate_certificate
-        SSLCertificateKeyFile /path/to/private/key
-        SSLProtocol             all -SSLv2 -SSLv3
-        SSLCipherSuite ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS
-        SSLHonorCipherOrder     on
-
-        # Encoded slashes need to be allowed
-        AllowEncodedSlashes NoDecode
-
-        # Container uses a unique non-signed certificate
-        SSLProxyEngine On
-        SSLProxyVerify None
-        SSLProxyCheckPeerCN Off
-        SSLProxyCheckPeerName Off
-
-        # keep the host
-        ProxyPreserveHost On
-
-        # static html, js, images, etc. served from loolwsd
-        # loleaflet is the client part of LibreOffice Online
-        ProxyPass           /loleaflet https://127.0.0.1:9980/loleaflet retry=0
-        ProxyPassReverse    /loleaflet https://127.0.0.1:9980/loleaflet
-
-        # 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
-
-        # Main websocket
-        ProxyPassMatch "/lool/(.*)/ws$" wss://127.0.0.1:9980/lool/$1/ws nocanon
-
-        # Admin Console websocket
-        ProxyPass   /lool/adminws wss://127.0.0.1:9980/lool/adminws
-
-        # Download as, Fullscreen presentation and Image upload operations
-        ProxyPass           /lool https://127.0.0.1:9980/lool
-        ProxyPassReverse    /lool https://127.0.0.1:9980/lool
-
-        # Endpoint with information about availability of various features
-        ProxyPass           /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities retry=0
-        ProxyPassReverse    /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities
-    </VirtualHost>
-			
-After configuring these do restart your apache using /etc/init.d/apache2 restart.    
-
-3. Configure the app in Nextcloud
+    ########################################
+    # 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"
@@ -106,13 +105,25 @@ 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:
 
-grab new docker image:
-    docker pull collabora/code
-List docker images:
-    docker ps 
-from the output you can glean the Container ID of your Collabora Online docker image.
-stop and remove the Collabora Online docker image:
-    docker stop CONTAINER_ID 
-    docker rm CONTAINER_ID
-start the new image:
-    docker run -t -d -p 127.0.0.1:9980:9980 -e 'domain=cloud\\.nextcloud\\.com' --restart always --cap-add MKNOD collabora/code
+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
+
diff --git a/admin_manual/office/example-ubuntu.rst b/admin_manual/office/example-ubuntu.rst
index d1d413e36..efcdf2099 100644
--- a/admin_manual/office/example-ubuntu.rst
+++ b/admin_manual/office/example-ubuntu.rst
@@ -34,6 +34,10 @@ Edit /etc/coolwsd/coolwsd.xml. Collabora Online (coolwsd) service runs via syste
 
 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
 
@@ -41,6 +45,6 @@ The default configuration is looking for an SSL certificate and key, which are n
     sudo coolconfig set ssl.termination true
     sudo coolconfig set storage.wopi.host nextcloud.example.com
     sudo coolconfig set-admin-password
-    sudo systemctl restart loolwsd
-    systemctl status loolwsd
+    sudo systemctl restart coolwsd
+    systemctl status coolwsd
 
diff --git a/admin_manual/office/index.rst b/admin_manual/office/index.rst
index 1ebd8113e..2dacf1a11 100644
--- a/admin_manual/office/index.rst
+++ b/admin_manual/office/index.rst
@@ -10,7 +10,7 @@ Users can insert and reply to comments and invite others without a Nextcloud acc
 
 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.
+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.
 
diff --git a/admin_manual/office/installation.rst b/admin_manual/office/installation.rst
index 08262cd7a..65dc3c38d 100644
--- a/admin_manual/office/installation.rst
+++ b/admin_manual/office/installation.rst
@@ -2,21 +2,14 @@
 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, which is further referred to as Nextcloud Office Server.
+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:
 
-- **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 recommended to switch to a dedicated Nextcloud Office installation
-
-
 - **Installation through distribution packages**
-    There are packages for all major Linux distributions available which allow deploying a Nextcloud Office Server through installing it through the regular package management. For an example installation guide on Ubuntu, see see: :doc:`example-ubuntu`
+    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/ 
@@ -24,15 +17,21 @@ For manual installations there are multiple options to get Nextcloud Office depl
 
 
 - **Installation through Docker**
-    Docker images are available for deploying Nextcloud Office in container environments. For a detailed step by step guide, see: :doc:`example-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 Nextcloud Office server will require some sort of reverse proxy to be setup in front of it. For more details see :doc:`proxy`.
+    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::
diff --git a/admin_manual/office/migration.rst b/admin_manual/office/migration.rst
index 3cd056787..f201fb1a2 100644
--- a/admin_manual/office/migration.rst
+++ b/admin_manual/office/migration.rst
@@ -2,7 +2,7 @@
 Migration from Collabora Online
 ===============================
 
-Nextcloud Office is based on Collabora Online so for enabling all Nextcloud Office functionallity it would be enough to update to the most recent release. Nextcloud Office is available since CODE 21.11.
+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.
diff --git a/admin_manual/office/troubleshooting.rst b/admin_manual/office/troubleshooting.rst
index 0249a31a6..ceca5d1e3 100644
--- a/admin_manual/office/troubleshooting.rst
+++ b/admin_manual/office/troubleshooting.rst
@@ -4,12 +4,12 @@ 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 Nextcloud Office server through HTTP(S)
-- The Nextcloud and the Nextcloud Office Server are using the same protocol
-- The Nextcloud server can reach the Nextcloud Office Server through HTTP(S)
-- The Nextcloud Office Server can reach the Nextcloud server through HTTP(S)
+- 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 Nextcloud Office Server log may reveal more detailed error messages in case of connection issues.
+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