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 if you would like to setup load balancing.
Attention
In some cases CODE can be packaged as part of integrator’s image and so, it might have different set of instructions. Thus, the easiest way to configure reverse proxy might be better documented in the integrator’s documentation.
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 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’s configuration file is /etc/coolwsd/coolwsd.xml.
The proxy redirects incoming requests to 127.0.0.1, but replies from coolwsd server must contain the original host name, otherwise the connection will fail. The service can usually figure out the external host name, except in more complex cases. In that case look for the setting server_name (empty by default), and enter the host name here, for example collaboraonline.example.com.
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 proxyEnable proxy for HTTP protocol:
a2enmod proxy_httpEnable SSL support:
a2enmod proxy_connectEnable 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 adding the LoadModule manually. See server-world.info on CentOS.
Reverse proxy settings in Apache2 config (SSL)
These lines should be inserted into <VirtualHost> definition of the site.
In coolwsd.xml the corresponding setting is ssl.enable=true.
1 ########################################
2
3 # Reverse proxy for Collabora Online #
4
5 ########################################
6
7
8 AllowEncodedSlashes NoDecode
9 SSLProxyEngine On
10 ProxyPreserveHost On
11
12
13 # cert is issued for collaboraonline.example.com and we proxy to localhost
14 SSLProxyVerify None
15 SSLProxyCheckPeerCN Off
16 SSLProxyCheckPeerName Off
17
18
19 # static html, js, images, etc. served from coolwsd
20 # browser is the client part of Collabora Online
21 ProxyPass /browser https://127.0.0.1:9980/browser retry=0
22 ProxyPassReverse /browser https://127.0.0.1:9980/browser
23
24
25 # WOPI discovery URL
26 ProxyPass /hosting/discovery https://127.0.0.1:9980/hosting/discovery retry=0
27 ProxyPassReverse /hosting/discovery https://127.0.0.1:9980/hosting/discovery
28
29
30 # Capabilities
31 ProxyPass /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities retry=0
32 ProxyPassReverse /hosting/capabilities https://127.0.0.1:9980/hosting/capabilities
33
34 # Main websocket
35 ProxyPassMatch "/cool/(.*)/ws$" wss://127.0.0.1:9980/cool/$1/ws nocanon
36
37
38 # Admin Console websocket
39 ProxyPass /cool/adminws wss://127.0.0.1:9980/cool/adminws
40
41
42 # Download as, Fullscreen presentation and Image upload operations
43 ProxyPass /cool https://127.0.0.1:9980/cool
44 ProxyPassReverse /cool https://127.0.0.1:9980/cool
45 # Compatibility with integrations that use the /lool/convert-to endpoint
46 ProxyPass /lool https://127.0.0.1:9980/cool
47 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 above, but in this case we have HTTP-only connection between the proxy and the Collabora Online server.
In coolwsd.xml the corresponding setting is ssl.enable=false and ssl.termination=true.
1 ########################################
2
3 # Reverse proxy for Collabora Online #
4
5 ########################################
6
7
8 AllowEncodedSlashes NoDecode
9 ProxyPreserveHost On
10
11
12 # static html, js, images, etc. served from coolwsd
13 # browser is the client part of Collabora Online
14 ProxyPass /browser http://127.0.0.1:9980/browser retry=0
15 ProxyPassReverse /browser http://127.0.0.1:9980/browser
16
17
18 # WOPI discovery URL
19 ProxyPass /hosting/discovery http://127.0.0.1:9980/hosting/discovery retry=0
20 ProxyPassReverse /hosting/discovery http://127.0.0.1:9980/hosting/discovery
21
22
23 # Capabilities
24 ProxyPass /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities retry=0
25 ProxyPassReverse /hosting/capabilities http://127.0.0.1:9980/hosting/capabilities
26
27
28 # Main websocket
29 ProxyPassMatch "/cool/(.*)/ws$" ws://127.0.0.1:9980/cool/$1/ws nocanon
30
31
32 # Admin Console websocket
33 ProxyPass /cool/adminws ws://127.0.0.1:9980/cool/adminws
34
35
36 # Download as, Fullscreen presentation and Image upload operations
37 ProxyPass /cool http://127.0.0.1:9980/cool
38 ProxyPassReverse /cool http://127.0.0.1:9980/cool
39 # Compatibility with integrations that use the /lool/convert-to endpoint
40 ProxyPass /lool http://127.0.0.1:9980/cool
41 ProxyPassReverse /lool http://127.0.0.1:9980/cool
Reverse proxy with Nginx webserver
Reverse proxy settings in Nginx config (SSL)
Add a new server block to your Nginx config for collaboraonline.example.com.
In coolwsd.xml the corresponding setting is ssl.enable=true.
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 $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 $host;
21 }
22
23
24 # Capabilities
25 location ^~ /hosting/capabilities {
26 proxy_pass https://127.0.0.1:9980;
27 proxy_set_header Host $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 $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 $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 $host;
54 proxy_read_timeout 36000s;
55 }
56}
Reverse proxy settings in Nginx config (SSL termination)
Add a new server block to your Nginx config for collaboraonline.example.com. Basically the configuration is the same as above, but in this case we have HTTP-only connection between the proxy and the Collabora Online server.
In coolwsd.xml the corresponding setting is ssl.enable=false and ssl.termination=true.
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 http://127.0.0.1:9980;
13 proxy_set_header Host $host;
14 }
15
16
17 # WOPI discovery URL
18 location ^~ /hosting/discovery {
19 proxy_pass http://127.0.0.1:9980;
20 proxy_set_header Host $host;
21 }
22
23
24 # Capabilities
25 location ^~ /hosting/capabilities {
26 proxy_pass http://127.0.0.1:9980;
27 proxy_set_header Host $host;
28 }
29
30
31 # main websocket
32 location ~ ^/cool/(.*)/ws$ {
33 proxy_pass http://127.0.0.1:9980;
34 proxy_set_header Upgrade $http_upgrade;
35 proxy_set_header Connection "Upgrade";
36 proxy_set_header Host $host;
37 proxy_read_timeout 36000s;
38 }
39
40
41 # download, presentation and image upload
42 location ~ ^/(c|l)ool {
43 proxy_pass http://127.0.0.1:9980;
44 proxy_set_header Host $host;
45 }
46
47
48 # Admin Console websocket
49 location ^~ /cool/adminws {
50 proxy_pass http://127.0.0.1:9980;
51 proxy_set_header Upgrade $http_upgrade;
52 proxy_set_header Connection "Upgrade";
53 proxy_set_header Host $host;
54 proxy_read_timeout 36000s;
55 }
56}
Load balancing
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.
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.