# Collabora integration guide **URL:** \ **Category:** 📑 How to\ **Tags:** wiki, code, wopi, collabora-online, collabora-built-in\ **Created:** [December 14, 2022, 9:31pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879 "2022-12-14T21:31:20Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [December 14, 2022, 9:31pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/1 "2022-12-14T21:31:20Z")
# [Collabora integration guide](https://help.nextcloud.com/t/collabora-integration-guide/151879) 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](https://www.collaboraoffice.com/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). ```mermaid flowchart LR clientint(client) clientint ---> Nextcloud; clientint ---> Collabora; Nextcloud(Nextcloud) Collabora(Collabora) Nextcloud --> Collabora Collabora --> Nextcloud ``` ## prerequisites - Nextcloud (WOPI server) - with “[Nextcloud Office (richdocuments)](https://apps.nextcloud.com/apps/richdocuments)” app - public DNS name - valid TLS certificate - 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 without TLS **makes no sense in most scenarios** so we won’t discuss it here. ## edit file using WOPI protocol ```mermaid sequenceDiagram participant client participant NC as Nextcloud
https://cloud.mydomain participant CODE as Collabora
https://office.mydomain loop Healthcheck NC->>CODE: GET https://office.mydomain.tld/hosting/discovery Note right of CODE: "green checkmark in Nextcloud UI" end client->>NC: open document "the bill.odt"
(which is fileid=1234546) NC->>client: "use CODE server to open document online
the url is https://office.mydomain/???open" client->>CODE: GET "https://office.mydomain/?????open&https://cloud.mydomain.tld/richdocuments/fileid=123456" CODE->>NC: GET "https://cloud.mydomain/richdocuments/fileid=123456" CODE->>client: edit document bill.odt (fileid=123456) ``` ### protocol references > **[\[MS-WOPI\]: Overview](https://learn.microsoft.com/en-us/openspecs/office_protocols/ms-wopi/0f0bf842-6353-49ed-91c0-c9d672f21200)** > > WOPI defines a set of operations that enables a client to access and change files stored by a server. This allows the > **[WOPI Overview – Office Web Apps Server and SharePoint](https://sharepointgadget.wordpress.com/2013/02/21/wopi-overview-office-web-apps-server-and-sharepoint/)** > > Here is a drawing I made to understand WOPI request with Office Web Apps Server and SharePoint. Get the PDF here: ## implementation and troubleshooting checklist while the process described above sounds complicated in real life it’s fairly easy to setup and troubleshoot. Often only need to complete the checklist and your integration likely 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 server console, verify access to Collabora, run: - `curl https://office.mydomain/hosting/discovery` - it should return a long XML doc (same as in previous check) with valid https:// URLs - from Collabora, verify access to the Nextcloud UI - from CODE console run - `curl https://cloud.mydomain/status.php` - it should return a JSON document similar to ```json {"installed":true,"maintenance":false,"needsDbUpgrade":false,"version":"33.0.2.2","versionstring":"33.0.2","edition":"","productname":"Nextcloud","extendedSupport":false} ``` - from any client access Collabora WOPI check endpoint - install richdocuments app `occ app:enable richdocuments` - configure CODE server URL - verify “Allow list for WOPI requests” entries ## troubleshooting tips if one of the above steps fail - often curl error message help - search the internet to understand the problem if the error doesn’t help increase verbosity by adding **-v** to curl command 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 local virtual or Docker names and IPs e.g. `http://127.0.0.1`, `http://office:9980`, `http://192.168.0.7:80` - this might allow communication from cloud to office and result in a ✅ within Nextcloud Office settings… but communication from the client will fail - don’t use plain http:// `http://office:9980`, `http://cloud:80`, `http://cloud` - 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 - [Collabora CODE for Nextcloud with Docker](https://help.nextcloud.com/t/how-to-configure-collabora-code-with-docker/216725) - [How to Install Nextcloud Office](https://help.nextcloud.com/t/how-to-install-nextcloud-office/155172) - [HowTo: Ubuntu + Docker + Nextcloud + Talk + Collabora](https://help.nextcloud.com/t/howto-ubuntu-docker-nextcloud-talk-collabora/76430) - [Docker Compose for Nextcloud + Collabora + Traefik?](https://help.nextcloud.com/t/docker-compose-for-nextcloud-collabora-traefik/127733) - [Important changes regarding Collabora COOL/CODE 26.04](https://help.nextcloud.com/t/important-changes-regarding-collabora-cool-code-26-04/246654) - [Important changes regarding COOL/CODE docker versions from v21.11.3.6 on (multiple domains setup)](https://help.nextcloud.com/t/important-changes-that-seem-to-affect-cool-docker-versions-from-v21-11-3-6-on-multiple-domains-setup/137867) - [Collabora/CODE not working with NC 24.0.3 in Docker](https://help.nextcloud.com/t/collabora-code-not-working-with-nc-24-0-3-in-docker/143324) - [Opening documents fail because of content security policy violation](https://help.nextcloud.com/t/opening-documents-fail-because-of-content-security-policy-violation/155148) - configure local shortcut avoiding all communications going through the internet (on Docker) → #splitbraindns for Docker [Probably DNS help with NC Docker + Collabora + Wireguard tunnel - #5 by wwe](https://help.nextcloud.com/t/probably-dns-help-with-nc-docker-collabora-wireguard-tunnel/176562/5) - [Collabora, websocket, nginx, self-hosted issues. Solved. // Fixed Collabora WebSocket issues behind nginx - complete troubleshooting guide](https://help.nextcloud.com/t/collabora-websocket-nginx-self-hosted-issues-solved-fixed-collabora-websocket-issues-behind-nginx-complete-troubleshooting-guide/236292) - [Collabora Online + Nextcloud + Nginx Proxy – Success! A Quick Write-Up](https://help.nextcloud.com/t/collabora-online-nextcloud-nginx-proxy-success-a-quick-write-up/207917) - search for [unauthorized WOPI host](https://help.nextcloud.com/search?q=%22unauthorized%20WOPI%20host%22%20order%3Alatest) look at #wopi_allowlist as well! - issues with #traefik 3.6 [Traefik reverse proxy v3.6.4 causes issues with CollaboraOnline (Nextcloud office)](https://help.nextcloud.com/t/using-collabora-nextcloud-office-behind-a-traefik-reverse-proxy/237844) - [running CODE as custom UID](https://help.nextcloud.com/t/collabora-code-for-nextcloud-with-docker/216725/4) ## other references - [Collabora CODE for Nextcloud with Docker](https://help.nextcloud.com/t/collabora-code-for-nextcloud-with-docker/216725) - [Nextcloud reverse proxy](https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/reverse_proxy_configuration.html) - [Collabora reverse proxy settings](https://sdk.collaboraonline.com/docs/installation/Proxy_settings.html) - [Collabora distroless image migration (from 26.04.02.1.1)](https://sdk.collaboraonline.com/docs/installation/Distroless_migration.html) - [Solved: Collabora CODE 26.04.2.2.1 (Docker) behind Nginx reverse proxy - #2 by wwe - Installation & Configuration - Collabora Online](https://forum.collaboraonline.com/t/solved-collabora-code-26-04-2-2-1-docker-behind-nginx-reverse-proxy/4894/2) - [CollaboraOnline Troubleshooting Guide](https://sdk.collaboraonline.com/docs/installation/Collabora_Online_Troubleshooting_Guide.html) - [Collabora forum: Debugging help - Nextcloud- coolwsd servers](https://forum.collaboraonline.com/t/debugging-help-nextcloud-coolwsd-servers/3269) - [Collabora forum: unauthorized WOPI host](https://forum.collaboraonline.com/t/unauthorized-wopi-host-with-docker-compose/3900) - [Nextcloud snap - configure CODE and Nextcloud office](https://github.com/nextcloud-snap/nextcloud-snap/wiki/Configure-CODE-and-Nextcloud-office-for-Nextcloud-snap) - [Arno Welzel blog / Nextcloud Office](https://arnowelzel.de/en/nextcloud-office) # AiO AiO uses a “separated” CODE not a built-in version. The biggest speciality is it is sharing the public fqdn for office and cloud so you will see same domain for `https://cloud.mydomain/status.php` and `https://office.mydomain/hosting/discovery` but other troubleshooting steps remain untouched. ⚠ some time ago an ugly hack was implemented to allow _internal connection_ through Docker networks > [@Local access for Collabora](https://help.nextcloud.com/t/local-access-for-collabora/231248/1): > > ```auto > Configured WOPI URL: http://nextcloud-aio-collabora:9980 > Configured public WOPI URL: https://cloud.mydomain > Configured callback URL: http://nextcloud-aio-apache:11000 > > ``` → see [Local access for Collabora](https://help.nextcloud.com/t/local-access-for-collabora/231248) for details # Nextcloud Office aka Built-In CODE #collabora-built-in There is nothing wrong with this installation method but I feel it is harder to troubleshoot, especially for not very skilled admins who look for a “simple” solution. In general if you run Docker(-compose) setup I would recommend separate CODE container which is easier to understand and control. All above mechanics apply to built-in CODE as well. The most important difference is _CODE doesn’t have it’s own public DNS records and lives in a subdirectory of Nextcloud application_. Office URLs to check are (_replace in the above guide_) - `https://cloud.mydomain/apps/richdocumentscode/proxy.php?req=/hosting/capabilities` - `https://cloud.mydomain/apps/richdocumentscode/proxy.php?req=/hosting/discovery` for ARM architecture: - `https://cloud.mydomain/apps/richdocumentscode_arm64/proxy.php?req=/hosting/capabilities` - `https://cloud.mydomain/apps/richdocumentscode_arm64/proxy.php?req=/hosting/discovery` another important fact - built-in CODE **does not use** Nextcloud integrated reverse proxy _OVERWRITE_\* settings. Running #collabora-built-in behind a #reverseproxy highly depends on reverse proxy _X\_FORWARDED_\* http headers - make sure your proxy adds them! discussion on custom webroot (subdirectory): [richdocuments ignores custom webroot · Issue #3420 · nextcloud/richdocuments · GitHub](https://github.com/nextcloud/richdocuments/issues/3420) Valuable Github discussion regarding built-in CODE: [Collabora Online - Built-in CODE Server in Nextcloud docker. Documents do not load · Issue #1896 · nextcloud/docker · GitHub](https://github.com/nextcloud/docker/issues/1896) Key learning’s - Docker `-alpine` image variant don’t work - additional volume `-tmpfs` might be required - additional variable `APPIMAGE_EXTRACT_AND_RUN=1` might be required ## NGINX reverse proxy with built-in CODE - [Missing public hostname in /hosting/discovery, documents don't load](https://help.nextcloud.com/t/missing-public-hostname-in-hosting-discovery-documents-dont-load/160788) - [Nextcloud can't open documents in Nextcloud Office - #12 by ardinusawan](https://help.nextcloud.com/t/nextcloud-cant-open-documents-in-nextcloud-office/168561/12) ## Apache reverse proxy config for built-in CODE - [Collabora - Built in Code - Reverse Proxy / "ssl.enable" and "ssl.termination" - #5 by DerP4si](https://help.nextcloud.com/t/collabora-built-in-code-reverse-proxy-ssl-enable-and-ssl-termination/161943/5) ---
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [October 19, 2023, 7:33pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/2 "2023-10-19T19:33:39Z")
4 posts were split to a new topic: [Nextcloud Collabora integration questions](https://help.nextcloud.com/t/nextcloud-collabora-integration-questions/172534) ---
**Author:** ![anon75456558](https://help.nextcloud.com/letter_avatar/anon75456558/32/5_5575768a8748004e209b776fc1b2916d.png) [@anon75456558](https://help.nextcloud.com/u/anon75456558)\ **Post date:** [January 3, 2024, 2:36am UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/3 "2024-01-03T02:36:56Z")
2 posts were split to a new topic: [Collabora integration guide missing AIO info](https://help.nextcloud.com/t/collabora-integration-guide-missing-aio-info/178082) ---
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [January 17, 2024, 8:42pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/4 "2024-01-17T20:42:24Z")
A post was split to a new topic: [Collabora CODE running on same server](https://help.nextcloud.com/t/collabora-code-running-on-same-server/179295) ---
**Author:** ![artfulrobot](https://help.nextcloud.com/user_avatar/help.nextcloud.com/artfulrobot/32/7260_2.png) [@artfulrobot](https://help.nextcloud.com/u/artfulrobot)\ **Post date:** [April 9, 2024, 1:31pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/5 "2024-04-09T13:31:18Z")
Really just came here to say **Thank you** for posting this. Really helpful to have this overview. It’s very confusing. > [@wwe](#): > > Allow list for WOPI requests 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 ```auto 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. ---
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [January 5, 2025, 4:50pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/6 "2025-01-05T16:50:21Z")
A post was split to a new topic: [Collabora licensing](https://help.nextcloud.com/t/collabora-licensing/214137) ---
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [March 17, 2025, 8:22am UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/7 "2025-03-17T08:22:44Z")
A post was split to a new topic: [CODE reports untrusted NC TLS certificate](https://help.nextcloud.com/t/code-reports-untrusted-nc-tls-certificate/220278) ---
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [August 30, 2025, 7:45pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/8 "2025-08-30T19:45:44Z")
4 posts were split to a new topic: [Local access for Collabora](https://help.nextcloud.com/t/local-access-for-collabora/231248) ---
**Author:** ![wwe](https://help.nextcloud.com/user_avatar/help.nextcloud.com/wwe/32/72963_2.png) [@wwe](https://help.nextcloud.com/u/wwe)\ **Post date:** [September 3, 2025, 8:12pm UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/10 "2025-09-03T20:12:32Z")
3 posts were merged into an existing topic: [Local access for Collabora](https://help.nextcloud.com/t/local-access-for-collabora/231248/3) ---
**Author:** ![MatthiasJ](https://help.nextcloud.com/user_avatar/help.nextcloud.com/matthiasj/32/50310_2.png) [@MatthiasJ](https://help.nextcloud.com/u/MatthiasJ)\ **Post date:** [August 6, 2026, 7:20am UTC](https://help.nextcloud.com/t/collabora-integration-guide/151879/11 "2026-08-06T07:20:36Z")
Thank you for this guide! I was trying it on my nextcloudpi instance and I noticed that the urls need to be changed (at least on my odroid-hc4 and probably on other arm-based sbc): ```auto https://cloud.mydomain.tld/apps/richdocumentscode_arm64/proxy.php?req=/hosting/discovery https://cloud.mydomain.tld/apps/richdocumentscode_arm64/proxy.php?req=/hosting/capabilities ``` I also noticed a small typo in the section about the built-in CODE: one of the urls uses `mydomain-tld `instead of `mydomain.tld`