Intermittent “app 'Collabora' not found” error caused by UID/GID mismatch between OpenCloud and Collabora containers

[federicoB]

Hello everyone,

I’d like to share an issue I ran into while setting up OpenCloud with Collabora, along with the root cause and solution, in case it helps others.

Context

OpenCloud running via Docker on a home server

Service exposed only on the local network

Collabora integrated via WOPI

Setup otherwise working correctly

Observed issue

When opening office documents, Collabora would behave inconsistently:

The first document open usually worked

Subsequent attempts failed with an error

Restarting the Docker services temporarily fixed the problem

From the OpenCloud logs:
gateway: error calling findAppProvider: error: not found: app "Collabora" not found

No other error logs from the wopiserver or collabora container.

At first glance, it looked like an app registry or provider discovery issue, since the app registry did know about Collabora, but the app provider could not be resolve the app.

Root cause

The issue was caused by a user mismatch between containers:

OpenCloud containers were running as root

Collabora / WOPI server was running as user 1000:1000

This led to permission and provider resolution problems that only surfaced after a few document opens, making the issue appear intermittent and difficult to diagnose.

The actual root cause was an incorrect environment variable configuration.
COLLABORA_DOMAIN was set on the opencloud service, even though it should only be defined on the collaboration service. This caused inconsistent app registration in the app_registry and misleading runtime errors when opening documents.

---

Solution

Ensure that OpenCloud and Collabora (including the WOPI server) run under matching UID/GID, possibily non-root users, and that all shared volumes have correct ownership and permissions.

After aligning the UID/GID across containers, the issue disappeared completely and has not reoccurred.

Check that you did not set any COLLABORA_DOMAIN environment variable in the opencloud service.
It should only be defined on the collaboration service to ensure Collabora is registered correctly.

---

Why I’m sharing this

The error message does not clearly indicate a misconfiguration or duplicate app registration

The reverse app registration flow (collaboration → app_registry) is not obvious and easy to misunderstand

The same opencloud image running multiple roles makes it easy to apply configuration to the wrong service

This can easily happen when deviating slightly from the recommended Docker setup

Hopefully this saves someone else a few hours of debugging.
@Svanvith I’m happy to turn this into a docs PR, i would like to add a section "Common Issues" to the "Collaboration" service here:
https://github.com/opencloud-eu/docs/tree/main/docs/dev/server/services/collaboration

[micbar]

@federicoB
This needs clear reproduction, I must admit that i doubt a bit about that. These apps are communicating via api. They do not share any state or storage. So which container user is used should have no influence on the api.

[federicoB]

Goodmorning @micbar !

I double-checked with a proper reproduction and the root cause was different from my initial conclusion. The issue was caused by an incorrect environment variable: I left COLLABORA_DOMAIN set on the opencloud service, even though it should only be defined on the collaboration service. This led to inconsistent behavior in the app registry and misleading errors during document opening.

What made this hard to reason about is the reverse registration flow: my assumption was that opencloud itself needs to know the address of Collabora. Instead, the collaboration service is responsible for registering the app into opencloud’s app_registry. Given that the same opencloud image can run different roles (gateway, collaboration, etc.), it’s easy to apply configuration to the wrong service and still end up with a partially working setup.

I suspect this resulted in two Collabora app entries, one valid and one broken, but the logs don’t make that clear. I still believe this is a documentation and diagnostics issue. Clearer guidance on env var scope and better detection or warnings for conflicting configuration would help a lot. My offer to contribute a docs PR still stands.

[micbar]

Did you use a custom compose stack? We currently document in our admin docs the standard deployment via the official compose project.

[federicoB]

I used a custom compose stack because I organize my compose files with dockge and wanted a single compose file for the entire OpenCloud cluster, rather than multiple separated files as in the official project.

That said, I would suggest having the WOPI server run in a separate image where the COLLABORA_ environment variables are allowed, while they are not allowed in the OpenCloud service itself. This would make it much harder to accidentally misconfigure the system.

I wonder what the purpose is of allowing the Collabora service to run in the OpenCloud service if it’s supposed to run only via the WOPI service. Defining COLLABORA_DOMAIN in the OpenCloud service leads to very confusing and inconsistent behavior, as I experienced.

[chiragkrishna]

official compose.yaml for web office has COLLABORA_DOMAIN set in opencloud service.

services:

  opencloud:
    environment:
      # this is needed for setting the correct CSP header
      COLLABORA_DOMAIN: ${COLLABORA_DOMAIN:-collabora.opencloud.test}

[federicoB]

Hi @chiragkrishna true, i will reproduce again this evening and post here my full docker-compose.

[federicoB]

Hi Everyone,

quick update: I spent some time this evening trying to reproduce the issue again, testing different combinations of users, environment variables, and directory ownership, but I was not able to trigger the problem anymore.

At this point I can’t provide a minimal or reliable reproduction, so I’ll pause the investigation here. If I manage to reproduce it again in a clean setup, I’ll come back with a full compose file and concrete steps.

Thanks for the patience and for challenging my assumptions

[micbar]

Thank you for sharing!

Did you mean cluster deployment? If you have more than one openCloud services, this can occur. But I think docker compose is always single node and one openCloud service.

If you don’t mind, that question would be interesting for me.

[federicoB]

Goodmorning, "cluster" can be ambigous yes :-D
No, i meant docker compose with one single node of opencloud + collabora + wopiserver (together they make a "opencloud" cluster in my mind)
Have a good start of the day!