Proxy settings

Server part of Collabora Online (coolwsd daemon) is listening on port 9980 by default, and clients should be able to communicate with it through port 9980. Sometimes it is not possible, for example a corporate firewall can allow only ports of well known services, such as port 80 (HTTP) and port 443 (HTTPS). The coolwsd daemon is configurable. It can use other ports than 9980. Port can be set by the command line option --port. However we cannot use for example port 443, when a web server is running on the same server, which is already bound to port 443. Reverse proxy setup is also required, when you would like to setup load balancing.

Reverse proxy with Apache 2 webserver

We assume that coolwsd and Apache2 are running on the same server: collaboraonline.example.com. For this to work, you have to setup follow the steps below:

  • Set the server name in Collabora Online configuration

  • Enable the required Apache2 modules

  • Add reverse proxy settings to Apache2 configuration file

Configure Collabora Online

Collabora Online configuration file is /etc/coolwsd/coolwsd.xml. Look for the setting server_name, which is empty by default, and enter the host name here, for example collaboraonline.example.com. This is necessary, because the proxy will redirect request to localhost. Answers from coolwsd server must contain the original host name, otherwise the connection will fail.

Required Apache2 modules

Apache2 web server is modular. We need to enable the required modules for this reverse proxy setup. We can use the a2enmod command to enable modules. If a module has been enabled already, nothing happens.

  • Enable proxy in general: a2enmod proxy

  • Enable proxy for HTTP protocol: a2enmod proxy_http

  • Enable SSL support: a2enmod proxy_connect

  • Enable proxy of websockets: a2enmod proxy_wstunnel

On CentOS / RHEL there is no a2enmod available. Enabling the modules has to be done by adjusting a config file and add the LoadModule oneself. See server-world.info on CentOS.

Reverse proxy settings in Apache2 config (SSL)

These lines should be inserted into <VirtualHost> definition of the site.

 1 ########################################
 2
 3 # Reverse proxy for Collabora Online
 4 #
 5
 6 ########################################
 7
 8
 9 AllowEncodedSlashes NoDecode
10 SSLProxyEngine On
11 ProxyPreserveHost On
12
13
14 # cert is issued for collaboraonline.example.com and we proxy to localhost
15 SSLProxyVerify None
16 SSLProxyCheckPeerCN Off
17 SSLProxyCheckPeerName Off
18
19
20 # static html, js, images, etc. served from coolwsd
21 # browser is the client part of Collabora Online
22 ProxyPass           /browser https://127.0.0.1:9980/browser retry=0
23 ProxyPassReverse    /browser https://127.0.0.1:9980/browser
24
25
26 # WOPI discovery URL
27 ProxyPass           /hosting/discovery https://127.0.0.1:9980/hosting/discovery retry=0
28 ProxyPassReverse    /hosting/discovery https://127.0.0.1:9980/hosting/discovery
29
30
31 # Capabilities
32 ProxyPass           /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities retry=0
33 ProxyPassReverse    /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities
34
35 # Main websocket
36 ProxyPassMatch      "/cool/(.*)/ws$"      wss://127.0.0.1:9980/cool/$1/ws nocanon
37
38
39 # Admin Console websocket
40 ProxyPass           /cool/adminws wss://127.0.0.1:9980/cool/adminws
41
42
43 # Download as, Fullscreen presentation and Image upload operations
44 ProxyPass           /cool https://127.0.0.1:9980/cool
45 ProxyPassReverse    /cool https://127.0.0.1:9980/cool
46 # Compatibility with integrations that use the /lool/convert-to endpoint
47 ProxyPass           /lool https://127.0.0.1:9980/cool
48 ProxyPassReverse    /lool https://127.0.0.1:9980/cool

Reverse proxy settings in Apache2 config (SSL termination)

These lines should be inserted into <VirtualHost> definition of the site. Basically the configuration is the same as , but in this case we have HTTP-only connection between the proxy and the Collabora Online server.

 1 ########################################
 2
 3 # Reverse proxy for Collabora Online
 4 #
 5
 6 ########################################
 7
 8
 9 AllowEncodedSlashes NoDecode
10 ProxyPreserveHost On
11
12
13 # static html, js, images, etc. served from coolwsd
14 # browser is the client part of Collabora Online
15 ProxyPass           /browser http://127.0.0.1:9980/browser retry=0
16 ProxyPassReverse    /browser http://127.0.0.1:9980/browser
17
18
19 # WOPI discovery URL
20 ProxyPass           /hosting/discovery http://127.0.0.1:9980/hosting/discovery retry=0
21 ProxyPassReverse    /hosting/discovery http://127.0.0.1:9980/hosting/discovery
22
23
24 # Capabilities
25 ProxyPass           /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities retry=0
26 ProxyPassReverse    /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities
27
28
29 # Main websocket
30 ProxyPassMatch      "/cool/(.*)/ws$"      ws://127.0.0.1:9980/cool/$1/ws nocanon
31
32
33 # Admin Console websocket
34 ProxyPass           /cool/adminws ws://127.0.0.1:9980/cool/adminws
35
36
37 # Download as, Fullscreen presentation and Image upload operations
38 ProxyPass           /cool http://127.0.0.1:9980/cool
39 ProxyPassReverse    /cool http://127.0.0.1:9980/cool
40 # Compatibility with integrations that use the /lool/convert-to endpoint
41 ProxyPass           /lool http://127.0.0.1:9980/cool
42 ProxyPassReverse    /lool http://127.0.0.1:9980/cool

Reverse proxy with Nginx webserver

Add a new server block to your nginx config for collaboraonline.example.com.

 1server {
 2 listen       443 ssl;
 3 server_name  collaboraonline.example.com;
 4
 5
 6 ssl_certificate /path/to/certificate;
 7 ssl_certificate_key /path/to/key;
 8
 9
10 # static files
11 location ^~ /browser {
12   proxy_pass https://127.0.0.1:9980;
13   proxy_set_header Host $http_host;
14 }
15
16
17 # WOPI discovery URL
18 location ^~ /hosting/discovery {
19   proxy_pass https://127.0.0.1:9980;
20   proxy_set_header Host $http_host;
21 }
22
23
24 # Capabilities
25 location ^~ /hosting/capabilities {
26   proxy_pass https://127.0.0.1:9980;
27   proxy_set_header Host $http_host;
28 }
29
30
31 # main websocket
32 location ~ ^/cool/(.*)/ws$ {
33   proxy_pass https://127.0.0.1:9980;
34   proxy_set_header Upgrade $http_upgrade;
35   proxy_set_header Connection "Upgrade";
36   proxy_set_header Host $http_host;
37   proxy_read_timeout 36000s;
38 }
39
40
41 # download, presentation and image upload
42 location ~ ^/(c|l)ool {
43   proxy_pass https://127.0.0.1:9980;
44   proxy_set_header Host $http_host;
45 }
46
47
48 # Admin Console websocket
49 location ^~ /cool/adminws {
50   proxy_pass https://127.0.0.1:9980;
51   proxy_set_header Upgrade $http_upgrade;
52   proxy_set_header Connection "Upgrade";
53   proxy_set_header Host $http_host;
54   proxy_read_timeout 36000s;
55 }
56}

Load balancing

In order for Collaborative Editing to function correctly, it is vital to ensure that all users editing the same document end up being served by the same Collabora Office instance. Using the WOPI protocol, the https URL includes a unique identifier (WOPISrc) for use with this document. Thus load balancing can be done by using WOPISrc – ensuring that all URLs that contain the same WOPISrc are sent to the same Collabora Office instance.

Note: for optimal performance all load balanced nodes must run the same version of Collabora Online. Currently Javascript, CSS and HTML that is served contains a unique version specific hash to enable browser caching while ensuring consistent upgrades. This version is provided in URLs provided from discovery.xml. When doing an incremental upgrade of a cluster an upgraded node will still provide new Javascript for an old version hash but will avoid sending ETag and CacheControl headers so that the files will be re-loaded when next fetched. This ensures that many minor upgrades can be done incrementally while an HA cluster continues running.

Example with HAProxy

In this example we will do load balancing between two Collabora Online server instances, which are running in docker containers. Load balancing is based on WOPISrc URL parameter.

The browser reaches the proxy with HTTPS protocol. The proxy terminates the HTTPS connection and passes traffic to backends via HTTP. Therefore in Collabora Online’s config file, in /etc/coolwsd/coolwsd.xml , or in the command line which starts coolwsd daemon, SSL should be disabled, and SSL termination should be enabled.

add the following blocks to /etc/haproxy/haproxy.cfg
 1frontend coolwsd
 2  bind *:443 ssl crt /path/to/your/certificate_and_key.pem
 3  mode http
 4  default_backend coolwsd
 5backend coolwsd
 6  timeout tunnel 3600s
 7  mode http
 8  balance url_param WOPISrc check_post
 9  hash-type consistent
10  server coolwsd01 127.0.0.1:9993
11  server coolwsd02 127.0.0.1:9994

Start Docker containers as described above, with -p 127.0.0.1:9993:9980 and -p 127.0.0.1:9994:9980.

Example with Nginx

Just like in the previous section (HAProxy), the Nginx load balancer also utilizes the WOPISrc URL parameter. In this example SSL settings are managed by Certbot (see https://letsencrypt.org/). The load balancer server listens on standard HTTPS port 443, and HTTP port 80 is redirected to HTTPS port 443. The coolwsd servers are reached through port 9980 directly (private network). The address for the outside world (for WOPI hosts) is coolwsd.public.example.com.

 1upstream coolwsd {
 2  zone coolwsd 64k;
 3  hash $arg_WOPISrc;
 4
 5  server coolwsd1.private:9980;
 6  server coolwsd2.private:9980;
 7}
 8
 9server {
10  listen 80 default_server;
11  listen 443 ssl; # managed by Certbot
12  ssl_certificate /etc/letsencrypt/live/1b255632-ce4b-4581-9e80-16f701c27034.pub.cloud.scaleway.com/fullchain.pem; # managed by Certbot
13  ssl_certificate_key /etc/letsencrypt/live/1b255632-ce4b-4581-9e80-16f701c27034.pub.cloud.scaleway.com/privkey.pem; # managed by Certbot
14  include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
15
16  if ($scheme != "https") {
17    return 301 https://$host$request_uri;
18  } # managed by Certbot
19
20  server_name coolwsd.public.example.com;
21
22  location / {
23    proxy_pass                 http://coolwsd;
24    proxy_set_header           Host $host;
25    proxy_http_version         1.1;
26    proxy_set_header           Upgrade $http_upgrade;
27    proxy_set_header           Connection "upgrade";
28    client_max_body_size       0;
29  }
30}

robots.txt

When you use Collabora Online behind a reverse proxy, add Disallow: /browser/* to your robots.txt file.