Collabora integration guide

Wiki
, ,
1

! this is a wiki article - everybody can improve !

Nextcloud integrates functionality to edit office documents online (even collaborative - meaning multiple users can work on the same document at the same time). This integration primarily happens with Collabora Online, but other integrations using the same protocol exist with OnlyOffice and Microsoft Online. As this forum primarily targets private users this article covers CODE (Collabora Online Development Edition) which is a free self-hosted Collabora Online variant for testing and home use. The integration builds on a protocol called WOPI which is widely used for similar integrations e.g. in Microsoft 365.

integration overview

Integration between Nextcloud and Collabora (or other WOPI clients) differs from classical web request/response models and results in confusion sometimes. The integration is not one-way where Nextcloud “pulls” integration from Collabora but it’s rather a “communication triangle” between clients, Nextcloud and Collabora, where each component accesses and provides resources from/to another. The requirements might become more clear by reading the process of file editing with the WOPI protocol (see below).

image

prerequisits

  • Nextcloud (WOPI server)
  • Collabora CODE (WOPI client)
    • public DNS name
    • valid TLS certificate

Technically integration might be possible without a public DNS and TLS certificates. But such integration makes no sense in most scenarios so we won’t discuss it here.

edit file using WOPI protocol

wopi1
wopi11032×483 43.1 KB

References

implementation and troubleshooting checklist

while the process described above sounds complicated in real life. But it’s fairly easy to setup and troubleshoot the. You only need to complete the checklist and it’s likely your integration will work.

  • from the client, verify access to the Nextcloud UI (use a browser or run curl https://cloud.mydomain/status.php)

  • from the client, verify access to Collabora (use browser or run curl https://office.mydomain/hosting/discovery)

    • the result must be an XML document describing the capabilities of the WOPI client
      (long list of different file types which could be opened)
    • review the content of the XML document reflect the right public hostname
    • verify the content of the document reflect the right - https:// - URL scheme

  • from Nextcloud, verify access to Collabora (from console run curl https://office.mydomain/hosting/discovery)

  • from Collabora, verify access to the Nextcloud UI (from console run curl https://cloud.mydomain/status.php)

  • install richdocuments app occ app:enable richdocuments

    # adopt to your system e.g. add sudo, www user etc..
occ app:enable richdocuments
# docker CLI
docker exec --user www-data ${name of NC container} php occ app:enable richdocuments
# docker compose
docker compose exec ${service name} php occ app:enable richdocuments

  • configure CODE server URL

    # adopt to your system e.g. add sudo, www user etc..
occ config:app:set richdocuments wopi_url --value ${CODE_URL} 
occ richdocuments:activate-config

# docker compose
docker compose exec ${service name} php occ config:app:set richdocuments wopi_url --value ${CODE_URL} 
docker compose exec ${service name} php occ richdocuments:activate-config

# GUI "Administration Settings" > Administration > Office 
# (https://cloud.mydomain/settings/admin/richdocuments)

    image

  • verify “Allow list for WOPI requests” entries. empty the list for testing then add IPs as needed

troubleshooting tips

if one of the above steps fail (likely curl will show a useful error message, enable verbose logging by adding -v to command line)

  1. double check your DNS (for all systems!) - especially in the case of docker or a VM. DNS resolution of the server might differ from the client
  2. verify the TLS certificates of cloud and office
  3. verify that both severs trust the assigned TLS certificate of the other system
  4. verify that the client trusts TLS certificates of both office and cloud

common issues

  • don’t use localhost
    • this reserved hostname is always different depending on the point of view:
      • for client, this means “the service running on the client”
      • for Nextcloud it means “the service running on Nextcloud server”
      • for CODE it means “the service running on the CODE server”
  • don’t use internal names or IPs e.g. http://127.0.0.1, http://office:9980, http://192.168.0.7:80
  • don’t use plain http:// http://office:9980, http://cloud:80, http://cloud
    • this might allow communication from cloud to office and result in a green checkmark within Nextcloud Office settings. But communication from the client will fail.
    • technically it’s possible to run the whole stack without TLS but you should never expose your system on the internet without TLS.

related forum posts

other references

https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/reverse_proxy_configuration.html

Apache reverse proxy config for build-in CODE

NGINX reverse proxy with built-in CODE

10 Likes
2

4 posts were split to a new topic: Nextcloud Collabora integration questions

3

2 posts were split to a new topic: Collabora integration guide missing AIO info

4

A post was split to a new topic: Collabora CODE running on same server

5

Really just came here to say Thank you for posting this. Really helpful to have this overview. It’s very confusing.

This one seems tricky. For my setup: running coolwsd ‘natively’ on Debian from .deb packages (i.e. not in docker), on the same server as nextcloud, I had to put in

127.0.0.1,11.22.33.44

Where 11.22.33.44 is the public IP of my server. Despite them both being on the same host it appears that this is the IP that the other sees. Also note that there’s no space around the comma.

1 Like