Nextcloud Collabora integration

! this is a wiki article - everybody can improve !

Nextcloud integrates functionality to edit office documents online (even collaborative - meaning multiple user can work on the same document at same time). This integration primarily happens with Collabora Online, but other integration using 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 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 model and results in confusion sometimes. The integration is not one-way where Nextcloud “pulls” integration from Collabora but it’s rather “communication triangle” between client, Nextcloud and Collabora, where each component access and provide resources from/to another. The requrements might become more clear reading the process of file edit with WOPI protocol (see below).



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

Technically integration migth be possible without public DNS and TLS certificates but such integration makes no sence in most scenarios so we don’t discuss it here.

edit file using WOPI protocol


implementation and troubleshooting checklist

while the process described above sounds complicated in real life it’s fairly aeasy to setup and troubleshoot the integration. you only need to complete the checklist and chances are high your integration will work.

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

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

    • the result must be an XML file describing capabilities of the WOPI client (long list of different file types which could be opened)
    • review the document reflect the right public hostname
  • from Nextcloud verify access to Collabora (from console run curl https://office.mydomain/hosting/discovery)

  • from Collabora verify access to 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

troubleshooting tips

if one of the above steps fail (likey curl will show useful error message, run verbose adding -v to command line)

  1. double check your DNS (for all systems!) - especially in case of docker or VM DNS resolution of the server might differ from the client
  2. verify TLS certificates of cloud and office
  3. verify both severs trust assigned TLS certificate of the other system
  4. verify client trust 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 is means “service running on the client”
      • for Nextcloud it means “service running on Nextcloud server”
      • for CODE it means “service running on the CODE server”
  • don’t use internal names or IPs e.g., http://office:9980,
  • don’t use plain http:// http://office:9980, http://cloud:80, http://cloud
    • this might allow communication from cloud to office and result is a green checkmark in Nextcloud Office settings but communication from the client will fail
    • technically it could be possible to run the whole stack without TLS but you never ever want to publish you system on the internet without TLS, so forget it immediately

related forum posts

other references